Before you start
- A listed pair. Read token addresses from
GET /v1/swap/pairsinstead of hardcoding them. Discovery 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 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.
Response
- What they receive:
amountOut, in whole tokens ofoutputToken. Here 0.9999 WTGXX. - The price:
price, the output per input in whole tokens. - Their fees: the entries of
feeswithpaidBy: "user". They are already in the amounts. - Who fills the swap:
capitalProvider.name. It isnullwhen the capital provider has no name, and a name need not be unique, so key your records oncapitalProvider.id.
2. Build
Send the same swap with theuser. 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.
Response
approval, on Ethereum: lets the capital provider’s delegate take exactly the most this swap can take of the input token. It isnullwhen 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.
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:
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 toPOST /v1/swap/decode; see 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/submissionsanswers409withNONCE_ALREADY_USED, and you build again. - Fees.
maxFeePerGascovers the base fee for at least six full blocks. Sign within a few blocks, or build again for current fees. - Gas.
gasis the simulated gas plus 20%, the swap’s simulated after the approval.
POST /v1/submissions in one request, in signing order:
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 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:- Send the
approval, when it is notnull, as returned, and wait until it is confirmed. - Send the
swapas returned. Its nonce follows the approval’s. If more than a few blocks have passed, build again first: the new build hasapproval: nulland current fees.
4. Track until final
Track the swap’s submission.GET /v1/submissions/{submissionId} returns its state. Polling faster than this returns the same answer:
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 1MOCK_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 The response has the same fields as on Ethereum. Here
user: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 This wallet has neither token account yet, so the
receiver: the user receives the output.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.Response (quote omitted)
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 The response lists a submission for each transaction, as on Ethereum, without a
accountCreation when there is one: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
Errors lists every code, and Quotes and builds every field.