Skip to main content
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 instead.

Before you start

  • A listed pair. Read token addresses from GET /v1/swap/pairs instead 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
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.
Response
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: 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. 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:
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 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: 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:
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.
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.
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 accountCreation when there is one:
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

Errors lists every code, and Quotes and builds every field.