> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Swap instantly

> Quote a swap, show it to the user, build and sign its transactions, and track it until it is final.

Use an instant swap when the user wants the output now, at the current price. It settles in one swap transaction; on Ethereum, the wallet may first have to approve the input token. For a swap that settles in the next daily batch, place a [batch order](https://docs.multiliquid.xyz/api-reference/swap/place-batch-order.md) instead.

## Before you start

* **A listed pair.** Read token addresses from `GET /v1/swap/pairs` instead of hardcoding them. [Discovery](https://docs.multiliquid.xyz/api-reference/swap/discovery.md) describes the list.
* **A wallet that signs without broadcasting**, so Multiliquid can check each transaction before broadcasting it. A wallet that can only broadcast, such as a browser wallet or a custody platform, sends the transactions itself, as [If the wallet can only broadcast](#if-the-wallet-can-only-broadcast) describes.
* **Network fees.** The user's wallet pays them, in ETH or SOL.

## 1. Quote

Fix one amount, in whole tokens with at most 6 decimal places: `amountIn` for what the user pays, or `amountOut` for what they receive. Pass the wallet as `user`, because an Ethereum price can depend on it.

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/swap/quote?network=evm-mainnet&inputToken=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&outputToken=0x1fecf3d9d4fee7f2c02917a66028a48c6706c179&amountIn=1&user=0x2222222222222222222222222222222222222222"
```

```json Response expandable theme={null}
{
  "network": "evm-mainnet",
  "swapType": "exactIn",
  "inputToken": {
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "kind": "stablecoin",
    "issuer": "Circle"
  },
  "outputToken": {
    "address": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
    "symbol": "WTGXX",
    "name": "WisdomTree Government Money Market Digital Fund",
    "decimals": 18,
    "kind": "rwa",
    "issuer": "WisdomTree"
  },
  "amountIn": "1",
  "amountOut": "0.9999",
  "price": "0.9999",
  "nav": [
    {
      "token": {
        "address": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
        "symbol": "WTGXX",
        "name": "WisdomTree Government Money Market Digital Fund",
        "decimals": 18,
        "kind": "rwa",
        "issuer": "WisdomTree"
      },
      "value": "1",
      "currency": "USD"
    }
  ],
  "fees": [
    {
      "type": "issuer",
      "amount": "0",
      "token": {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "kind": "stablecoin",
        "issuer": "Circle"
      },
      "paidBy": "capitalProvider"
    },
    {
      "type": "spread",
      "amount": "0.0001",
      "token": {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "kind": "stablecoin",
        "issuer": "Circle"
      },
      "paidBy": "user"
    },
    {
      "type": "capitalProvider",
      "amount": "0",
      "token": {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "kind": "stablecoin",
        "issuer": "Circle"
      },
      "paidBy": "user"
    }
  ],
  "capitalProvider": {
    "id": "0x58e27f2731863499e6a23a1662ebeed9041d6b40996ea9ca7f4ebc54201823b4",
    "name": "Uniform Labs",
    "address": "0x0630582db5a1949509f21b315677c40b9aeb7bda"
  },
  "indicative": false,
  "alternatives": [
    {
      "capitalProvider": {
        "id": "0xfd07a2f44bab2d27f5af4a5a579abfc543010ce2f97597a5e0d9e13be6b1fb26",
        "name": "Uniform Labs",
        "address": "0x8a982edc1578394ed03f8b24d3b78a924fcf3abc"
      },
      "amountIn": "1",
      "amountOut": "0.9999"
    },
    {
      "capitalProvider": {
        "id": "0x2f5c040b301a61f7770bc3ba613522e8d8d60a9f2cecf6721d3870fe6627de8b",
        "name": null,
        "address": "0xd49499321f771e18c5aa0d93152d7e2b20da5b48"
      },
      "amountIn": "1",
      "amountOut": "0.9999"
    }
  ]
}
```

Show the user:

* **What they receive:** `amountOut`, in whole tokens of `outputToken`. Here 0.9999 WTGXX.
* **The price:** `price`, the output per input in whole tokens.
* **Their fees:** the entries of `fees` with `paidBy: "user"`. They are already in the amounts.
* **Who fills the swap:** `capitalProvider.name`. It is `null` when the capital provider has no name, and a name need not be unique, so key your records on `capitalProvider.id`.

A quote reserves nothing. The build quotes again, and the bound the user signs protects them if the price moves.

## 2. Build

Send the same swap with the `user`. `slippageBps` sets how far the price may move, from 0 to 5,000 basis points, with a default of 50 (0.5%). The build turns it into the bound the user signs: a minimum output when you fix `amountIn`, or a maximum input when you fix `amountOut`.

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/swap/build" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "evm-mainnet",
    "inputToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "outputToken": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
    "amountIn": "1",
    "user": "0x2222222222222222222222222222222222222222",
    "slippageBps": 50
  }'
```

```json Response expandable theme={null}
{
  "quote": {
    "swapType": "exactIn",
    "inputToken": {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "kind": "stablecoin",
      "issuer": "Circle"
    },
    "outputToken": {
      "address": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
      "symbol": "WTGXX",
      "name": "WisdomTree Government Money Market Digital Fund",
      "decimals": 18,
      "kind": "rwa",
      "issuer": "WisdomTree"
    },
    "amountIn": "1",
    "amountOut": "0.9999",
    "price": "0.9999",
    "fees": [
      {
        "type": "issuer",
        "amount": "0",
        "token": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "kind": "stablecoin",
          "issuer": "Circle"
        },
        "paidBy": "capitalProvider"
      },
      {
        "type": "spread",
        "amount": "0.0001",
        "token": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "kind": "stablecoin",
          "issuer": "Circle"
        },
        "paidBy": "user"
      },
      {
        "type": "capitalProvider",
        "amount": "0",
        "token": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "kind": "stablecoin",
          "issuer": "Circle"
        },
        "paidBy": "user"
      }
    ],
    "capitalProvider": {
      "id": "0x58e27f2731863499e6a23a1662ebeed9041d6b40996ea9ca7f4ebc54201823b4",
      "name": "Uniform Labs",
      "address": "0x0630582db5a1949509f21b315677c40b9aeb7bda"
    }
  },
  "bound": {
    "minAmountOut": "0.9949005"
  },
  "approval": {
    "description": "Approve 1 USDC to the USDC delegate of capital provider Uniform Labs",
    "transaction": {
      "runtime": "evm",
      "chainId": 1,
      "from": "0x2222222222222222222222222222222222222222",
      "to": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "data": "0x095ea7b30000000000000000000000000630582db5a1949509f21b315677c40b9aeb7bda00000000000000000000000000000000000000000000000000000000000f4240",
      "value": "0",
      "nonce": "42",
      "gas": "67134",
      "maxFeePerGas": "21500000000",
      "maxPriorityFeePerGas": "1500000000",
      "serialized": "0x02f86e012a8459682f008505017ff7008301063e94a0b86991c6218b36c1d19d4a2e9eb0ce3606eb4880b844095ea7b30000000000000000000000000630582db5a1949509f21b315677c40b9aeb7bda00000000000000000000000000000000000000000000000000000000000f4240c0"
    }
  },
  "swap": {
    "description": "Swap 1 USDC for at least 0.9949005 WTGXX",
    "transaction": {
      "runtime": "evm",
      "chainId": 1,
      "from": "0x2222222222222222222222222222222222222222",
      "to": "0xd66211cf522ba23b59789fff6524c1f03e13e20c",
      "data": "0xdeead6b5…",
      "value": "0",
      "nonce": "43",
      "gas": "277944",
      "maxFeePerGas": "21500000000",
      "maxPriorityFeePerGas": "1500000000",
      "serialized": "0x02f9018f012b8459682f008505017ff70083043db894d66211cf522ba23b59789fff6524c1f03e13e20c80b90164deead6b5…"
    }
  },
  "checks": {
    "balance": {
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "required": "1",
      "available": "48.984469",
      "sufficient": true
    },
    "eligibility": {
      "wallet": "0x2222222222222222222222222222222222222222",
      "token": "0x1fecf3d9d4fee7f2c02917a66028a48c6706c179",
      "status": "eligible",
      "reason": "allowlisted"
    },
    "allowance": {
      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "spender": "0x0630582db5a1949509f21b315677c40b9aeb7bda",
      "required": "1",
      "available": "0",
      "sufficient": false
    },
    "simulation": {
      "status": "succeeded",
      "gasUsed": "211520"
    }
  }
}
```

The user signs at most two transactions, in this order:

* **`approval`, on Ethereum:** lets the capital provider's delegate take exactly the most this swap can take of the input token. It is `null` when the wallet has already approved enough. A swap uses up its approval, so the next swap usually needs a new one. This example has one, because the wallet has approved nothing.
* **`swap`:** the swap itself.

On Ethereum, each `transaction` is complete and ready to sign. The API reads the wallet's nonce and the current fees from the chain and fills in `nonce`, `gas`, `maxFeePerGas`, and `maxPriorityFeePerGas`; `serialized` is the unsigned transaction. The approval takes the wallet's next nonce and the swap the one after, and the build simulates the swap after the approval, so the swap has its own `gas`.

On Solana, `accountCreation` takes the place of `approval`. It creates a token account the wallet lacks, and it is `null` unless creating that account inside the swap transaction would make the transaction too large.

Before asking for a signature, read `checks`:

| Check | When it fails | What to do |
| - | - | - |
| `balance` | The wallet holds less than `required` | Ask the user to fund the wallet |
| `allowance` | The allowance is below `required` | Nothing: the build adds an `approval` for exactly that amount |
| `eligibility` | `status` is `ineligible` or `unknown` | Show the user `action`, which says in plain words what to do. See below for `unknown`. |
| `simulation` | `status` is `reverted` | Show `error.message`: the swap would fail as built |

A failed check never fails the build. `simulation` is `skipped` when the balance falls short, on Ethereum when the swap can be simulated only after its approval lands (`approvalRequired`) or the approval would revert (`approvalReverts`), or on Solana while an account creation still has to land. On Ethereum, a swap that cannot succeed now, because its simulation reverted or was skipped, has `gas` and `serialized` set to `null`: don't ask the user to sign it.

Some RWAs apply transfer rules that the API can read only by simulating the swap, so `eligibility` stays `unknown` while `simulation` is `skipped`. Fund the wallet and build again: the new build simulates the swap and reports `eligible` or `ineligible`. If you go ahead instead, a swap that the RWA refuses reverts, and the wallet still pays its network fee.

## 3. Sign and submit

To show the user what a transaction does before they sign it, send it to `POST /v1/swap/decode`; see [Decode](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md#decode).

The wallet signs the `approval`, when it is not `null`, and the `swap`, without broadcasting either. On Ethereum, sign each transaction's `serialized` as returned, or, with a signer that takes fields, its fields unchanged. Don't set the nonce, gas, or fees yourself:

* **Nonce.** The approval carries the wallet's next nonce and the swap the one after, so both can be signed before either is sent. If the wallet sends another transaction first, the signed ones are stale: `POST /v1/submissions` answers `409` with `NONCE_ALREADY_USED`, and you build again.
* **Fees.** `maxFeePerGas` covers the base fee for at least six full blocks. Sign within a few blocks, or build again for current fees.
* **Gas.** `gas` is the simulated gas plus 20%, the swap's simulated after the approval.

Send both to `POST /v1/submissions` in one request, in signing order:

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{ "network": "evm-mainnet", "signedTransactions": ["0x02f8…", "0x02f8…"] }'
```

Multiliquid checks both, then simulates and broadcasts the approval. It stores the swap as `queued` and sends it once the approval is `confirmed`. The response lists a submission for each transaction, in the same order. When `approval` is `null`, send the swap alone.

On Solana, each transaction is a base64 version 0 transaction with the user as the only signer. The wallet signs it as is, and you submit the signed bytes in base64. An `accountCreation` goes first, as an approval does. [Swap on Solana](#swap-on-solana) shows the whole flow.

If the request fails with `SERVICE_UNAVAILABLE`, send the same request again rather than signing new transactions. It returns the same submissions, with `replayed: true` for each one the first request stored. A newly signed transaction is a different submission, and both could land.

### If the wallet can only broadcast

A wallet that cannot sign without sending, such as a browser wallet or a custody platform, sends the transactions itself:

1. Send the `approval`, when it is not `null`, as returned, and wait until it is confirmed.
2. Send the `swap` as returned. Its nonce follows the approval's. If more than a few blocks have passed, build again first: the new build has `approval: null` and current fees.

Multiliquid then has no submission to track, so follow the swap's transaction on the chain.

## 4. Track until final

Track the swap's submission. `GET /v1/submissions/{submissionId}` returns its `state`. Polling faster than this returns the same answer:

| State | Meaning | Next |
| - | - | - |
| `queued` | Waiting for the approval or account creation before it to be `confirmed` | Poll every 4 seconds on Ethereum, 2 on Solana |
| `pending` | Broadcast, not yet included | Poll every 4 seconds on Ethereum, 2 on Solana |
| `confirmed` | Included and successful | Poll every 12 seconds on Ethereum, 4 on Solana |
| `finalized` | Final | Stop. `settlement` holds the realized amounts. |
| `failed` | Reverted, or never sent | Show `error.message`. `error.code` is `TRANSACTION_FAILED` when it was included and failed (on Ethereum, `error` is `null` when the revert cannot be recovered); `PREVIOUS_TRANSACTION_FAILED` when the approval or account creation before it failed or expired; and `SIMULATION_FAILED` or `TRANSACTION_REJECTED` when it was never sent because it failed in simulation or the node refused it when its turn came. Stop once `finalizedAt` is set, or at once without an `inclusion`. |
| `expired` | Never included | Build and sign again |

Record a swap as complete only at `finalized`. A chain reorganization can return a `confirmed` swap to `pending`.

## Swap on Solana

The flow is the same on Solana, without an approval. This example swaps 1 `MOCK_USDC` for `MOCK_RWA` on `svm-devnet`, where the tokens have no value; `GET /v1/networks` says which networks are active.

**1. Quote**

Name the tokens by their mints and the wallet as `user`:

```bash theme={null}
curl "https://api.multiliquid.xyz/v1/swap/quote?network=svm-devnet&inputToken=AeQz4qPhAFxZshmv9gE3dbxyph2uaqyM4JnWk4DeH8Jo&outputToken=9fBsNQ3rL2FdAYKXptwJ9nbarCDh57Xqzbsr68p9Te6j&amountIn=1&user=9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
```

The response has the same fields as on Ethereum. Here `amountOut` is `0.41625` `MOCK_RWA`, and `fees` lists the Solana fee types, `protocol`, `spread`, and `discount`.

**2. Build**

Send the same swap. Solana takes no `receiver`: the user receives the output.

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/swap/build" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "svm-devnet",
    "inputToken": "AeQz4qPhAFxZshmv9gE3dbxyph2uaqyM4JnWk4DeH8Jo",
    "outputToken": "9fBsNQ3rL2FdAYKXptwJ9nbarCDh57Xqzbsr68p9Te6j",
    "amountIn": "1",
    "user": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "slippageBps": 50
  }'
```

This wallet has neither token account yet, so the `swap` transaction creates both, and `accountCreation` is `null`. It holds no `MOCK_USDC`, so `checks.balance` fails and the swap is not simulated. The response also repeats the quote under `quote`, left out here.

```json Response (quote omitted) expandable theme={null}
{
  "bound": {
    "minAmountOut": "0.41416875"
  },
  "accountCreation": null,
  "swap": {
    "description": "Create the MOCK_USDC token account, create the MOCK_RWA token account, swap 1 MOCK_USDC for at least 0.41416875 MOCK_RWA",
    "transaction": {
      "runtime": "svm",
      "serialized": "AQAAAAAAAAAAAAAAAAAAAAAA…",
      "recentBlockhash": "FMazjEC2NZBFbEodasCfAy6Gx7zfDHAThWBgbkCaCSAv",
      "lastValidBlockHeight": "509069577",
      "signers": [
        "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
      ]
    }
  },
  "checks": {
    "balance": {
      "token": "AeQz4qPhAFxZshmv9gE3dbxyph2uaqyM4JnWk4DeH8Jo",
      "required": "1",
      "available": "0",
      "sufficient": false
    },
    "eligibility": {
      "wallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "token": "9fBsNQ3rL2FdAYKXptwJ9nbarCDh57Xqzbsr68p9Te6j",
      "status": "eligible",
      "reason": "notRestricted"
    },
    "simulation": {
      "status": "skipped",
      "reason": "insufficientBalance"
    }
  }
}
```

**3. Sign**

`serialized` is the unsigned transaction in base64, a version 0 transaction whose only signer and fee payer is the user. The wallet signs it as it is, without sending it, before the network passes `lastValidBlockHeight`. When `accountCreation` is not `null`, the wallet signs it too: both share `recentBlockhash`.

**4. Submit and track**

Send the signed transaction as base64, after the signed `accountCreation` when there is one:

```bash theme={null}
curl -X POST "https://api.multiliquid.xyz/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{ "network": "svm-devnet", "signedTransactions": ["AVJ1…"] }'
```

The response lists a submission for each transaction, as on Ethereum, without a `nonce`. Read the swap's submission every 2 seconds until it is `confirmed`, then every 4 seconds until it is `finalized`, about 13 seconds later. If the blockhash expires first, the submission becomes `expired`: build and sign again.

## When something goes wrong

| Code | What happened | What to do |
| - | - | - |
| `INVALID_REQUEST` on a quote, `INVALID_BODY` on a build | A value is malformed, such as an amount with more than 6 decimal places or more than the token's decimals, or a JSON number; `details.field` names it | Send the amount as a decimal string in whole tokens, such as `"1.5"` |
| `UNSUPPORTED_PAIR` | No listed capital provider swaps the pair, or the pair does not list the `capitalProvider` you named | Offer only pairs from `GET /v1/swap/pairs`, and name only a capital provider the pair lists |
| `NO_QUOTE` | Every capital provider rejected the swap | Show the reasons in `details.providers`, such as custody that holds too little of the output. Try a smaller amount or another pair. |
| `BOUND_NOT_MET` | The price already moved past the bound you sent | Quote again, and let the user accept the new price |
| `CONFLICT` | On Solana, the swap's accounts do not match current chain state | Build again later |
| `SIMULATION_FAILED` | The signed transaction would revert now | Show the message, which names the revert, and build again |
| `TRANSACTION_REJECTED` | The network's node refused the first transaction; the message gives the node's reason | Show the message, then build and sign again |
| `NONCE_ALREADY_USED` | Another transaction used the wallet's nonce after the build | Build and sign again |
| `INVALID_TRANSACTION` | On Solana, usually an expired blockhash. `details.field` names the transaction, such as `signedTransactions[1]`. | Build and sign again |
| `UNSUPPORTED_TRANSACTION` | A transaction is not a Multiliquid swap or approval, or two transactions are not one build's pair | Submit only the transactions a build returns, in signing order, or a preparation's `approval` alone |
| `SERVICE_UNAVAILABLE` on submit | The broadcast may or may not have reached the network | Send the same request again. Never sign new transactions: both could land. |
| `NETWORK_NOT_ACTIVE` | The API does not serve the network now | Don't retry. Offer only networks that `GET /v1/networks` lists as active. |
| `429` | Too many requests, or the service is busy | Wait for `Retry-After` |

[Errors](https://docs.multiliquid.xyz/api-reference/guides/errors.md) lists every code, and [Quotes and builds](https://docs.multiliquid.xyz/api-reference/swap/quote-and-build.md) every field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.