For the complete documentation index, see llms.txt. This page is also available as Markdown.

Vault Auto-Conversion

Auto-Conversion converts non-stablecoin vault deposits into the stablecoin you choose — USDT or USDC — before you are credited. Your player deposits ETH; you receive USDT. One deposit, one credit, one webhook, denominated in your chosen stablecoin.

Quick version: turn it on, pick USDT or USDC, and every new deposit address you create converts native-token deposits (ETH, BNB, POL) and MAKA on Ethereum into that stablecoin before crediting you. Stablecoin deposits are not swapped. A successful conversion pays the single 1% Vault fee from realized converted output after the route's 6 bps affiliate fee; when no conversion succeeds, the single 1% fee is taken from the token swept. Existing addresses keep their current behavior until you explicitly migrate them.

Auto-Conversion is opt-in and off by default. With it off, every deposit behaves exactly as described in the Vault System guide.

Mainnet-only availability: Auto-Conversion is available to every mainnet account, but cannot be enabled when NEXT_PUBLIC_MAKA_NETWORK is testnet or local. New sandbox accounts therefore use ordinary V2 Vault addresses and cannot acquire the capability latch. An already-latched account keeps router-salted derivation, but its addresses use signed passthrough: deposits settle in the deposited asset without conversion and pay the normal single 1% fee. The account may always switch conversion off, and MakaPay never clears the latch, so existing addresses remain recoverable.

How it works

When Auto-Conversion applies to a deposit:

  1. Your player sends a supported native token (e.g. ETH) to their deposit address.

  2. Makapay converts it to your Target Stable on the same chain it arrived on. The conversion is executed on-chain via audited routing infrastructure and is atomic with the sweep: either the conversion succeeds and you receive the Target Stable, or nothing moves and the funds remain safely at the deposit address awaiting retry.

  3. The route realizes an amount of the Target Stable after market execution, route costs, and MakaPay's 6 bps deBridge affiliate fee. MakaPay then deducts the fixed 1% Vault fee from that realized Target Stable output and sends the remaining 99% to you.

  4. You are credited — and webhooked — exactly once, denominated in the Target Stable. The source token remains in the webhook's source-accounting fields for auditability; the conversion object states the target-token gross output, 1% fee, and net amount you should credit. The only source-token credit is an explicitly flagged Degraded Credit below.

A deposit undergoing Auto-Conversion is not yet credited: it is pending until the conversion completes. Funds are never held in Makapay custody at any point — Auto-Conversion preserves the vault's non-custodial guarantee.

What converts — and what credits as-is

Auto-Conversion only touches tokens in the Convertible Set — an explicit per-chain allowlist. In the current EVM release, the Convertible Set is the native tokens of the conversion-supported chains plus MAKA on Ethereum:

Token
Chains

ETH (native)

Ethereum, Base

BNB (native)

BSC

POL (native)

Polygon

MAKA (ERC-20)

Ethereum

Everything else is swept without a swap. The fixed 1% Vault fee still applies to the token being swept:

Deposit
Behavior with Auto-Conversion enabled

USDT or USDC on any chain (the Stable Set)

Never converted, regardless of your Target Stable; swept with the 1% fee charged in that stablecoin

A Convertible Set token (ETH, BNB, POL, MAKA on Ethereum)

Converted to your Target Stable, then credited

Any other token

Swept as-is with the 1% fee charged in that token

Any deposit on MakaChain

Swept as-is with the 1% fee charged in that token; conversion is unavailable on MakaChain

Two rules worth stating plainly:

  • Conversion is same-chain only. A conversion always executes on the chain the deposit arrived on. Auto-Conversion never moves funds across chains, never performs stable-to-stable swaps, and never bridges the same token between chains. An ETH deposit on Base becomes a stablecoin on Base.

  • You elect a token, never a chain. Your Target Stable election is chain-independent. Your stablecoin balances stay on the chains where deposits arrive.

Your Target Stable

The Target Stable is the Stable Set token you elect to receive from Auto-Conversion: USDT or USDC. The election is:

  • Merchant-level — it applies to your whole vault; individual vault users cannot override it.

  • Changeable at any time — a conversion uses the election in force at the moment it executes, not at the moment the deposit was detected.

On a chain where your elected token is unsupported or illiquid, a fixed per-chain resolution substitutes the other Stable Set token. The resolution is deterministic and defined by Makapay — never chosen per-deposit:

Chain
You elected USDT
You elected USDC

Ethereum

USDT

USDC

Base

USDC (Base has no supported USDT)

USDC

Polygon

USDT (listed under the symbol USDT0 on Polygon)

USDC

BSC

USDT

USDC

What you receive: realized proceeds, then the 1% Vault fee

The swap's realized output is the actual target-token amount that reaches ConversionRouterV2 after:

  • Market execution — the price at which the conversion actually fills, including slippage.

  • Route fees — fees charged by the on-chain routing infrastructure executing the swap.

  • MakaPay deBridge affiliate fee — 6 bps (0.06%), configured as affiliateFeePercent=0.06 in deBridge's percentage-point format.

After those swap-level costs, MakaPay charges the standard Vault fee: 1% of the realized target-token output. You receive the remaining 99%. There is no second 1% fee in the source token.

For example, if the route delivers 1,000.00 USDC to the V2 router after route and affiliate costs, the Vault fee is 10.00 USDC and your wallet receives 990.00 USDC.

MakaPay never guarantees a quoted amount and never carries price risk on a converting deposit. Every conversion is protected by a minimum-output guard on the net amount you receive after the 1% fee. If market movement would put that net amount below the signed minimum, the whole conversion reverts and is retried with a fresh quote.

When a conversion can't complete: the Degraded Credit

Occasionally a conversion keeps failing — the market moves too fast, or the route is temporarily unavailable. When that happens:

  1. Makapay retries the conversion with a fresh quote each attempt, over a bounded retry window (minutes, not hours). Between attempts the funds remain safely at the deposit address.

  2. If the retry budget is exhausted, the deposit is swept as-is and you are credited in the original token (e.g. ETH). This is a Degraded Credit.

Because no conversion succeeds, the fixed 1% Vault fee is charged in that original token on the passthrough. The 6 bps deBridge affiliate fee is not charged on a Degraded Credit because no swap completes.

A Degraded Credit is explicitly flagged everywhere it appears:

  • The deposit.completed webhook carries conversion.outcome: "degraded_passthrough".

  • The deposit is marked as degraded in Dashboard → Vault → Deposits.

Three things your finance team should know:

  • A Degraded Credit is a completed credit, not a failure. The player's deposit is credited and the deposit lifecycle ends. It is never silently retried, converted later, or reversed. deposit.completed remains the single success event for every deposit.

  • It is denominated in the source token. A Degraded Credit is the only case in which a conversion-enabled merchant receives a Convertible Set token. Your ledger must be able to book a credit in that token — even if it is not in your enabled tokens list — and your reporting must not drop these rows.

  • The player is always credited within a known worst-case window. Bounded retries exist so that a stalled conversion never leaves a player waiting indefinitely.

To reconcile, branch on the conversion object in the webhook (full payloads below):

conversion object

Meaning

Credit denominated in

Absent

Ordinary deposit — no conversion involved (stable deposit, non-convertible token, MakaChain, grandfathered address, or Auto-Conversion off); 1% was charged during the source-token sweep

The deposited token

outcome: "converted"

Conversion succeeded

conversion.netOut in your Target Stable (after the 1% Vault fee)

outcome: "degraded_passthrough"

Degraded Credit — retry budget exhausted

The original (source) token

Existing users are unaffected

Enabling Auto-Conversion changes nothing for your existing vault users. A deposit address created before you enabled Auto-Conversion is a Grandfathered Deposit Address: it sweeps directly to your wallet as-is, forever, and can never convert.

  • Conversion applies only to deposit addresses created after enablement.

  • Grandfathering is per address — not per user, not per merchant.

  • To make one existing user's deposits convertible, you can re-derive that user's deposit address via the Vault Users API.

  • To opt every grandfathered user into conversion, use Dashboard → Vault → Settings → Auto-Conversion → Migrate existing users. Each affected user receives a new deposit address, which your integration must display.

Auto-Conversion now derives new and migrated addresses against ConversionRouterV2. Addresses previously derived against ConversionRouterV1 remain valid historical deposit addresses but do not silently become V2 addresses: CREATE2 includes the router identity, so the V2 address is different. Use the general Vault contract upgrade action in Settings to move every existing EVM row from FactoryV1 to FactoryV2 while preserving whether it is ordinary or router-based. Use the separate Auto-Conversion migration action only when you also want grandfathered ordinary users to become conversion-capable. Continue monitoring legacy addresses for recovery and update the address shown in your cashier before asking the player to use it.

This lets you enable or upgrade Auto-Conversion without abandoning historical funds: existing player flows remain recoverable, and you opt users into the current router address at your own pace.

Configuration

Dashboard

Navigate to Dashboard → Vault → Settings:

  1. Toggle Auto-Conversion on.

  2. Elect your Target Stable: USDT or USDC.

  3. Optionally choose Migrate existing users to give every grandfathered user a new conversion-capable address.

You can change the election at any time; it applies to conversions that execute after the change.

On sandbox, the enable control is disabled and the dashboard reports that Auto-Conversion is unavailable. If an account is already enabled, the off transition remains available. Existing router-salted addresses remain recoverable, new users on that already-latched account remain router-salted, and sandbox deposits settle through signed passthrough regardless of the stored legacy election.

API

The vault config endpoints (GET / POST / PATCH /api/vault/v1/config) carry an autoConversion block:

  • enabled — whether new deposit addresses are created conversion-capable.

  • targetStable — "USDT" or "USDC"; resolved per-chain according to the resolution table above.

Sandbox POST and PATCH enable attempts return HTTP 403 with code: "CONVERSION_UNAVAILABLE_ON_SANDBOX". Requests that keep or set enabled: false remain valid.

Per-user re-derivation (to opt an existing user into conversion) is available under the vault Users API — see the API Reference.

Deposit statuses

Auto-Conversion adds one status to the deposit lifecycle:

Status
Description

converting

A conversion is being attempted or retried; funds remain at the deposit address

A converting deposit completes with a single deposit.completed event — either converted into your Target Stable, or credited as a flagged Degraded Credit. All other active statuses (detected, processing, completed, failed) are unchanged — see Vault System → Deposit Statuses.

Webhook: the conversion object

The deposit.completed payload gains an optional, backward-compatible conversion object. If you don't use Auto-Conversion — or the deposit didn't involve a conversion — the object is simply absent and the payload is unchanged. Signature verification is identical to all other vault webhooks (see Vault System → Webhook Signature Verification).

Converted deposit — a player deposited 0.5 ETH; source accounting remains in ETH and the conversion object records the USDT credit:

Degraded Credit — the conversion could not complete; you are credited the original 0.5 ETH, flagged:

conversion fields:

Field
Description

targetToken

Contract address of the resolved Target Stable on the deposit's chain

targetTokenSymbol

Symbol of the resolved Target Stable (e.g. USDT, USDC)

grossOut

Target token received by V2 after route costs and the 6 bps deBridge affiliate fee, before the Vault fee; omitted for a Degraded Credit

feeAmount

Exactly 1% of grossOut, in target-token smallest units; omitted for a Degraded Credit

netOut

Target token sent to your wallet (grossOut - feeAmount), in smallest units; this is the amount to credit; omitted for a Degraded Credit

realizedOut

Backward-compatible alias of netOut for a V2 conversion; null for a Degraded Credit

affiliateFeeBps

deBridge affiliate setting in basis points (6); the effect is already reflected in grossOut

outcome

"converted" — credited in the Target Stable. "degraded_passthrough" — a Degraded Credit, credited in the original token

attempts

Number of conversion attempts made before the deposit completed. The retry budget is an internal operational constant — treat this as informational, not as a fixed contract

As with every vault webhook, amounts are raw smallest-unit strings, and handlers should be idempotent on (event, data.depositId).

FAQ

Does Auto-Conversion change anything for stablecoin deposits? No. USDT and USDC are not swapped and remain on the chain where they arrived. Because no conversion runs, the single 1% Vault fee is charged in that stablecoin during the sweep.

Can I receive everything on one chain? No — conversion is same-chain only. You elect a token, never a chain; converted proceeds stay on the deposit's arrival chain.

What happens on MakaChain? MakaChain deposits are never converted. They sweep in the deposited token with the single 1% Vault fee charged from that token.

If I switch my Target Stable from USDT to USDC, what happens to in-flight deposits? A conversion uses the election in force when it executes. A deposit already detected but not yet converted will convert to your new election.

Can Makapay end up holding my funds mid-conversion? No. The conversion is atomic with the sweep: either it succeeds and you receive the Target Stable, or nothing moves and the funds stay at the deposit address. There is no custody window.

Is there a fee for the conversion? There is one Vault platform fee: 1%. After a successful conversion it is charged from the realized Target Stable output, after the deBridge route's 6 bps affiliate fee; there is no source-token 1% charge on that path. If no conversion succeeds, the 1% is charged from the source token during the sweep and no deBridge affiliate fee is incurred.

Last updated