> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/guides/vault-auto-conversion.md).

# 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](https://docs.makapay.io/guides/vault.md) 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](#when-a-conversion-cant-complete-the-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](#webhook-the-conversion-object)):

| `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:

```json
{
  "autoConversion": {
    "enabled": true,
    "targetStable": "USDT"
  }
}
```

* `enabled` — whether new deposit addresses are created conversion-capable.
* `targetStable` — `"USDT"` or `"USDC"`; resolved per-chain according to the [resolution table](#your-target-stable) 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](https://docs.makapay.io/developers/api-reference.md).

## 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](https://docs.makapay.io/guides/vault.md#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](https://docs.makapay.io/guides/vault.md#webhook-signature-verification)).

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

```json
{
  "event": "deposit.completed",
  "data": {
    "depositId": "abc123",
    "externalUserId": "user_123",
    "amount": "500000000000000000",
    "fee": "0",
    "netAmount": "500000000000000000",
    "tokenSymbol": "ETH",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "chainId": 1,
    "depositAddress": "0x...",
    "status": "completed",
    "depositTxHash": "0x...",
    "processTxHash": "0x...",
    "conversion": {
      "targetToken": "0x...",
      "targetTokenSymbol": "USDT",
      "grossOut": "1250000000",
      "feeAmount": "12500000",
      "netOut": "1237500000",
      "realizedOut": "1237500000",
      "affiliateFeeBps": 6,
      "outcome": "converted",
      "attempts": 1
    },
    "timestamp": 1704067260000
  },
  "timestamp": 1704067260000
}
```

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

```json
{
  "event": "deposit.completed",
  "data": {
    "depositId": "def456",
    "externalUserId": "user_123",
    "amount": "500000000000000000",
    "fee": "5000000000000000",
    "netAmount": "495000000000000000",
    "tokenSymbol": "ETH",
    "tokenAddress": "0x0000000000000000000000000000000000000000",
    "chainId": 1,
    "depositAddress": "0x...",
    "status": "completed",
    "depositTxHash": "0x...",
    "processTxHash": "0x...",
    "conversion": {
      "targetToken": "0x...",
      "targetTokenSymbol": "USDT",
      "realizedOut": null,
      "affiliateFeeBps": 6,
      "outcome": "degraded_passthrough",
      "attempts": 4
    },
    "timestamp": 1704067260000
  },
  "timestamp": 1704067260000
}
```

**`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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.makapay.io/guides/vault-auto-conversion.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
