# Token Conversions

Token conversion reallocates balance between compatible USD-equivalent tokens in one subaccount. It does not transfer an ERC-20 token or change the total backed balance. Conversions settle 1:1 in D9 units with no conversion fee.

Use conversion to fund an isolated quote-token pool or return its balance to the concrete backing token before withdrawal.

## Valid Paths

* A concrete token to a synthetic token backed by it.
* A synthetic token to its concrete backing token.
* Two synthetic tokens with the same concrete backing token.

Use `GET /v1/token` to resolve each token's `address` and `backingTokenId`. The `fromToken` balance must cover the conversion after outstanding funding and position fees are applied.

## Submit a Conversion

```http
POST /v1/token/convert
```

Sign a `ConvertToken` EIP-712 message with the owner wallet or an active linked signer:

```json
{
  "data": {
    "sender": "0xSIGNER_ADDRESS",
    "subaccount": "0xBYTES32_SUBACCOUNT",
    "fromToken": "0xSOURCE_TOKEN_ADDRESS",
    "toToken": "0xDESTINATION_TOKEN_ADDRESS",
    "amount": "100.5",
    "nonce": "1785811200000000000",
    "signedAt": 1785811200
  },
  "signature": "0xEIP712_SIGNATURE"
}
```

`amount` is a decimal string with up to 9 decimal places. The EIP-712 message encodes it as a D9 `uint128`. Get the signing domain and `ConvertToken` type from `GET /v1/rpc/config`. See [Message Signing](/developer-guides/trading-api/message-signing).

## Status and Settlement

A successful request returns `201` with the conversion ID, status, subaccount ID, token addresses, amount, fee, and creation time. The initial status is `SUBMITTED`. Track it with:

```http
GET /v1/token/transfer?subaccountId=SUBACCOUNT_UUID&types=CONVERT&orderBy=createdAt&order=desc
```

`COMPLETED` means the smart contracts applied the source debit and destination credit. `REJECTED` means no conversion was applied. Onchain validation covers the signature, expiry, signer authorization, nonce, token relationship, 1:1 output amount, zero fee, and source balance.

See [Supported Tokens](/developer-guides/trading-api/supported-tokens) for token types and backing relationships.