Skip to main content
A quote prices a swap from chain state, and a build turns the same swap into the unsigned transactions the user’s wallet signs. Both have one shape on every network; an object whose form depends on the network carries runtime, evm or svm.

Quote

GET /v1/swap/quote On Solana, an amount can be at most 264 − 1 of the token’s base units, such as 18446744073709.551615 for a 6-decimal token; a larger one is rejected with details.field naming it. Conventions gives the rules for every amount. The best quote has the most output for an exact-input swap and the least input for an exact-output swap; a tie keeps the listing order.
A quote is a price read from chain state, not a reservation. Nothing is held for the user, and the price can change before a swap lands. A build quotes again at its own block or slot, and the bound the user signs makes the swap revert rather than fill at a worse price. Quote and build responses carry Cache-Control: no-store, so don’t cache them.

Quote response

Fees

fees lists each fee as {type, amount, token, paidBy}, with amount in whole tokens of token, a full token object. paidBy names whose amounts a fee reduces, not the account a transfer debits:
  • user: the fee is already in amountIn and amountOut, so the user receives less or pays more for it.
  • capitalProvider: the fee leaves amountIn and amountOut unchanged and comes out of the capital provider’s side of the swap.
On EVM, a stablecoin-input swap sends the issuer fee to the protocol out of the user’s input, yet the user pays amountIn either way and the capital provider receives that much less, so its paidBy is capitalProvider. An EVM capital provider’s NAV discount on an RWA sale is in the quoted amounts but not in fees, because the swap contract’s quote does not report it.

Price and NAV

Each nav entry has the RWA’s token, its value in USD per whole token as a decimal string, and currency (USD). On EVM, value is the price the swap contract reads for the RWA, and an RWA without a price is left out of nav. On Solana, it is the swap program’s own NAV, the average of the asset’s configured NAV sources.

Why a capital provider cannot fill

A capital provider that cannot fill the swap appears in alternatives, and in NO_QUOTE’s details.providers when none can, with the error its swap would fail with. On EVM, it reports the first of these that applies:
  1. The swap’s own error, such as RWANotWhitelisted.
  2. For $TSY in through the Treasury capital provider, CreditsUnavailable when the $TSY cannot be priced now, or InsufficientCredits when the $TSY is above the user’s Treasury credits, a wallet without credits included. After CreditsUnavailable, retry later, or quote with user if you left it out.
  3. ZeroAmount for an amount whose quote rounds to zero, so quote a larger amount.
  4. ERC20InsufficientBalance or ERC20InsufficientAllowance when the capital provider’s custody cannot pay the output and any protocol fee. $TSY output from the Treasury capital provider is minted, so it never falls short.
On Solana, the error is the swap program’s own, such as InsufficientLiquidity, and a capital provider with Treasury enabled reports TreasuryEnabled.

Build

POST /v1/swap/build takes the quote’s parameters as a JSON body, with user required, and: A request supplies at most one of slippageBps and the explicit bound for its swap type. The bound is derived from the build’s own quote: a minimum output rounds down, amountOut × (10,000 − slippageBps) / 10,000, and a maximum input rounds up, amountIn × (10,000 + slippageBps) / 10,000. The rounding is to the token’s smallest unit. On Solana, a minimum output that rounds to 0 is signed, and returned, as one base unit. An explicit bound that the quote already violates is rejected with 422 and code BOUND_NOT_MET, whose details give the bound’s field, the bound sent, and the quoted amount, in whole tokens. The body is limited to 2 KiB. A build stores and reserves nothing.

Build response

approval, accountCreation, and swap each have a description to show the user and the unsigned transaction. A description gives amounts in whole tokens with the token’s symbol, such as Approve 1 USDC to the USDC delegate of capital provider Uniform Labs or Swap 1 USDC for at least 0.9949005 WTGXX. An approval names its spender as decode labels it: the delegate’s stablecoin and its capital provider, such as the Treasury delegate of capital provider Uniform Labs for $TSY in. A capital provider without a name is named by its id.

Transactions on EVM

  • approval: approve(spender, amount) on the input token, for exactly the most the swap can take: amountIn for exact input, or the signed maxAmountIn for exact output. The spender is the capital provider’s stablecoin delegate. It is null when the user’s allowance to the spender already covers that amount.
  • swap: MultiliquidSwap.swap sent by the user, paying the output to receiver.
Each EVM transaction is a complete, unsigned EIP-1559 transaction, ready to sign. The API reads the sender’s nonce and the current fees from the chain and fills in every field, so the wallet or custody signer signs serialized as it is, or the fields unchanged, and sets no nonce, gas, or fee of its own. The approval that a batch order or redemption preparation returns, and a delegate admin transaction, have the same form. Sign within a few blocks of the build. If the wallet sends another transaction first, the signed one carries a used nonce, and POST /v1/submissions answers 409 with NONCE_ALREADY_USED; build again for current values. A transaction that cannot succeed now, a swap whose simulation reverted or was skipped or an approval whose simulation reverted, keeps its nonce and fees with gas and serialized null: don’t sign it. A swap skipped with approvalRequired can succeed: land the approval, then build again for a swap with its gas.

Transactions on Solana

Each transaction is an unsigned version 0 transaction with the user as fee payer and only signer, so the user pays the fee and the rent of every account it creates.
  • accountCreation: compute-budget instructions, then an idempotent creation of each token account the user lacks. It is null unless creating those accounts in the swap transaction would take it over 1,232 bytes.
  • swap: compute-budget instructions, the idempotent creation of the user’s missing token accounts unless accountCreation creates them, then the swap.
The build sets the swap’s compute-unit limit to its simulated units plus 20%, or to 300,000 when the simulation did not succeed, and the compute-unit price from recent network fees, so the priority fee is between 0.00001 and 0.01 SOL. A swap whose transaction exceeds 1,232 bytes even without account creation cannot be built and answers 422 with code INVALID_BODY. Each Solana transaction is {runtime: "svm", serialized, recentBlockhash, lastValidBlockHeight, signers}: the base64 wire transaction with zeroed signature slots, its blockhash, the last block height at which it can land, and the signing wallets. accountCreation and swap share the blockhash, so a wallet signs both at once and you submit them together. If the blockhash expires first, a new build finds the created accounts and returns accountCreation: null.

Checks

A build never fails because a check fails; you decide whether to proceed.

Eligibility

checks.eligibility reports, for the wallet that receives the output (the EVM receiver or the Solana user) and the output token, a status of eligible, ineligible, or unknown, a reason, and, when the status is not eligible, an action that says in plain words what to do. Show the action to the user before asking for a signature. On EVM the check asks the output RWA’s whitelist adapter about the selected capital provider’s custody, the receiver, and the amount, exactly as the swap contract asks it. When the Treasury capital provider mints the $TSY output, the check reads the receiver’s entries on the $TSY allowlist and blacklist, which minting and every transfer require; an ineligible receiver’s action reads The TSY allowlist does not include 0x2222222222222222222222222222222222222222, or its blacklist does, so the swap would revert. Ask Multiliquid to add the wallet to the TSY allowlist, or receive TSY in another wallet. On Solana it reads the user’s output token account and the output mint’s Token-2022 extensions.

Decode

POST /v1/swap/decode takes a transaction and returns what it does, for you to show the user before they confirm it in their wallet. The wallet stays the source of truth: decoding does not simulate the transaction or check balances, and it never broadcasts or stores it. No API key is needed. Send network and one of: Signed and unsigned transactions both decode, and a signature that is present must verify. An EVM transaction that carries serialized must carry the bytes of its own fields, so the breakdown describes exactly what the wallet signs; one whose serialized does not match, or lacks the nonce, gas, or fees it needs, answers 422 with code INVALID_BODY and details.field transaction.serialized. The body is limited to 20 KiB.
Response

Decode response

The response also carries the transaction’s own fields: chainId, signed, from, to, value (in wei), and data on EVM, and version, feePayer, signers, recentBlockhash, and addressLookupTables on Solana. On EVM, from is the build’s from for a transaction, and null for an unsigned serializedTransaction, whose sender only a signature shows. On Solana, each signers entry is {address, signed}. An account that an address lookup table loads has a null address. Decoding returns no nonce, gas, or fee fields. Each address that Multiliquid lists is labeled with its kind and name: swapContract, stablecoinDelegate (with its capitalProvider), token, program, pair, or capitalProvider. Any other address is unlisted, which says only that Multiliquid does not list it, not that it is unsafe. A transaction that parses is never rejected: an unlisted target or an unknown function or instruction comes back with its raw data. Bytes that do not parse, or a signature that does not verify, answer 422 with code INVALID_TRANSACTION. A body that names an unknown network, sends both or neither of transaction and serializedTransaction, or sends a transaction that is not the network’s or whose fields disagree with its bytes answers 422 with code INVALID_BODY and details.field. Decoding answers for every network, whether or not it is active.

Errors

A request the swap cannot serve fails with a code whose details say what to change: 400 for a quote’s query and 422 for a build’s body. A network that the API does not serve answers 503 with code NETWORK_NOT_ACTIVE and details.network, before any other parameter’s value is checked; a build’s body must still be well-formed JSON with every required field. A Solana build whose accounts cannot be resolved from current chain state, as when an account the swap needs is missing or does not match the pair, answers 409 with code CONFLICT.
When the service is busy, a quote or build waits up to five seconds, then answers 429 with Retry-After while its rate-limit allowance still has requests left, as Rate limits describes. Errors lists every code.