401 with code UNAUTHORIZED.
Acceptance reserves the capital provider’s capacity but does not escrow or lock the user’s funds. The user’s balance, allowance, and eligibility must still hold when the capital provider executes, and execution is best effort until the order’s deadline.
Endpoints
Networks. A route with a JSON body takes
network in the body, and a GET route takes it in the query string: evm-mainnet, evm-sepolia, svm-mainnet, or svm-devnet. On a network where batch orders are not active, POST /v1/batch-orders/prepare and POST /v1/batch-orders answer 503 with code NETWORK_NOT_ACTIVE, as does GET /v1/batch-orders/info on Solana when it would list a capital provider. The routes that read stored orders answer for every network.
Capital providers. Every route names a capital provider with the same object as a swap pair and a quote: id, name, and address. A request takes its id. GET /v1/swap/pairs lists the capital providers that take batch orders for each pair in batchCapitalProviders.
The batch calendar
A batch is named by itsbatchId, the New York calendar date of its 5:00 PM release. Batches run every day, including weekends and holidays, and follow America/New_York daylight saving time. A response that describes a batch gives these times in its batch object, in UTC with whole seconds:
An order’s signed deadline falls at or after
executionTargetAt and before the next day’s 5:00 PM release. An order can execute from its release until its deadline.
Between 4:30 and 5:00 PM, batch info returns the batch that was just cut off, with intakeOpen false, and preparation answers INTAKE_CLOSED, whose details.opensAt is the 5:00 PM release.
Batch info
GET /v1/batch-orders/info?network= returns the batch now taking orders and every capital provider whose batch orders are on for the network, whether or not it takes orders now. It needs no credential.
Each entry of
capitalProviders has the capitalProvider, acceptingOrders, and capacity. acceptingOrders is true while the capital provider has an operator and, on Ethereum, its delegate is swappable, or on Solana it has no Treasury enabled. An order also needs open intake and enough capacity. To find who takes an order for a pair now, match the pair’s batchCapitalProviders with the entries whose acceptingOrders is true. capacity has one entry per token the capital provider swaps: the token object and available, the most a new order can pay out in it, in whole tokens.
Place a batch order shows a full response.
Ethereum orders
An Ethereum order is the swap contract’sUnorderedSwapBatchApproval, signed by the user under the MultiliquidSwap version 2 EIP-712 domain.
1
Prepare
POST /v1/batch-orders/prepare takes the swap by token address, as the Swap API does: network, inputToken, outputToken, exactly one of amountIn and amountOut in whole tokens, with at most 6 decimal places and no more than the token’s decimals, capitalProvider, user, and an optional receiver that defaults to user. An amount sent as a JSON number, or with a sign or exponent, or a zero amount, answers 422 with INVALID_BODY.The response has runtime (evm), the order to send back, the typedData to sign, the approval to land first or null, the checks, the current quote, and the batch. The order and typedData are what the user signs, so their assetInAmt and assetOutAmt are in base units: 1000000000 is 1,000 USDC. The checks and quote are in whole tokens.2
Approve
approval is a transaction to sign, with a description, like a swap build’s. It approves the capital provider’s stablecoin delegate for this order’s input plus the input of the user’s other open orders that spend the same token through it, because an approval replaces the allowance instead of adding to it. It is null when the allowance already covers them. It is complete, with the user’s nonce, gas, and fees filled in: the wallet signs it as returned. Submit it alone to POST /v1/submissions, or let a wallet that can only broadcast send it, and wait until it is confirmed before you submit the order.3
Sign
The wallet signs
typedData. It is in the eth_signTypedData_v4 form, with types.EIP712Domain listing one entry per domain field, so wallets and custody platforms that take the raw JSON sign it as it is. ethers rejects EIP712Domain in types, so with ethers, delete types.EIP712Domain before signing; the signature is the same.4
Submit
POST /v1/batch-orders takes {"order": ..., "signature": "0x..."}, with the prepared order unchanged. Its inputs name the IDs assetInId, assetOutId, and stablecoinDelegateId, where typedData.message names them assetInID, assetOutID, and stablecoinDelegateID. A 201 response returns the orderId, acceptedAt, and the batch.BOUND_NOT_MET, and the wallet prepares and signs again. Preparation reserves and stores nothing, and needs a capital provider with batch orders on, an operator, and open intake.
Place a batch order shows a full prepared order.
Solana orders
A Solana order is a swap transaction that the user signs at intake and the capital provider’s operator signs and sends after the release, through one of the operator’s durable nonce accounts.1
Prepare
POST /v1/batch-orders/prepare takes the same fields as on Ethereum, without receiver: on Solana the user receives the output, and receiver answers 422 with code UNSUPPORTED_FIELD, whose details give the field and network. Both of the user’s associated token accounts for the pair must already exist, under each mint’s token program, SPL Token or Token-2022. Preparation answers 422 with code TOKEN_ACCOUNT_MISSING when one is missing, and its details give the mint as token, the missing account, and the tokenProgram that creates it. Create the account, for example with the associated token account program’s idempotent create instruction, then prepare again. Submission answers the same if the account was closed since preparation.The response has runtime (svm), the order, the unsigned transaction in base64 with both signature slots empty, the checks, the current quote, and the batch. The transaction is a version 1 transaction, which only a client that supports version 1 decodes, such as @solana/kit; @solana/web3.js 1.x cannot. The order names the capitalProvider, the operator that pays the fee and executes the order, the tokens, swapType, the fixed amount and its bound, the deadline, and the nonceAccount and its nonceValue. The signed transaction must match the order, so its amounts are in base units, while the request, checks, and quote are in whole tokens.2
Sign
The wallet signs
transaction unchanged with signTransaction, as a signer that does not pay the fee, and does not send it. The operator’s slot stays empty until execution. The transaction never goes to POST /v1/submissions.3
Submit
POST /v1/batch-orders takes {"order": ..., "signedTransaction": "..."}, with the prepared order unchanged and the signed transaction in base64. Multiliquid runs the transaction, stores the order and its reservation, and returns the same 201 body as on Ethereum.transaction shortened here; the full value is about 1,900 base64 characters. The order’s amountIn of 1000000 is the same 1 USDC in base units:
Response
{"order": ..., "signedTransaction": "..."} with that order unchanged and the wallet-signed transaction in base64.
Preparation answers 409 with OPERATOR_NOT_SELECTED when the capital provider has no operator and NONCE_ACCOUNT_UNAVAILABLE when its operator has no free nonce account. A capital provider with Treasury enabled takes no batch orders, and preparation answers 422 with UNSUPPORTED_ROUTE. The capital provider’s vaults need not hold the output yet: it funds them before the batch executes. Submission answers 409 with PREPARED_ORDER_STALE when the nonce account was taken or advanced, the signed transaction differs from the one the order now builds, or the transaction limits or fee bounds changed; the wallet then prepares and signs again.
Checks
A prepared order’schecks say what would keep intake from accepting it now. A failing check does not fail the preparation, so the user learns of it before landing an approval.
checks.capacity compares what the order would reserve with what the capital provider has left in the batch:
Rejections
Every rejection has a specific code. A code carries thedetails in parentheses, and a code without parentheses carries none:
A malformed request answers
400 with INVALID_REQUEST, an invalid API key 401 with UNAUTHORIZED, a body over the route’s limit 413 with PAYLOAD_TOO_LARGE (limitBytes), and a spent allowance 429 with RATE_LIMITED, as Errors describes.
Before it quotes, preparation answers 422 for a swap the capital provider cannot fill:
A quote that rejects the amount answers
NO_QUOTE. On preparation, details.providers names the capital provider and the decoded error its quote failed with, and the message reads as a swap quote’s: no capital provider can quote this swap: {capitalProvider.id}: {error.message} ({error.name}). On Ethereum, $TSY in above the user’s Treasury credits reports InsufficientCredits, and an amount whose quote rounds to zero reports ZeroAmount. Errors gives each code’s remedy.
Duplicate orders
An order is never accepted twice. A submission whose nonce an accepted order already holds, or on Solana whose signed transaction an accepted order already holds, answers409 with code DUPLICATE_ORDER and the accepted order’s ID:
DUPLICATE_ORDER always carries details.orderId. If the accepted order cannot be read back at that moment, the submission answers 503 instead, and a retry returns the order ID.
Multiliquid checks for the duplicate before the other checks that need chain or batch state, so a retry finds its order even after the order executed, the cut-off or release passed, or the quote or operator changed. After a timeout or a 503, send the same submission again: if the first was accepted, it answers DUPLICATE_ORDER with details.orderId, which you read with GET /v1/batch-orders/{orderId}. To place another order, prepare and sign a new one. A nonce that the swap contract already used without an accepted order answers NONCE_ALREADY_USED.
Cancellation
A user can cancel an accepted order until its batch’scutoffAt. Cancellation is off-chain: it restores the reserved capacity, the order is never released, and the order’s nonce stays unused on-chain.
-
POST /v1/batch-orders/{orderId}/cancel/preparetakes{"network": "..."}and returns thecancellationto send back, with what to sign:typedDataon Ethereum, or on Solana themessagefor the wallet’ssignMessage. The cancellation expires five minutes after it is prepared, or at the cut-off if that is sooner: itsexpiresAt, in Unix seconds, is exclusive. On Ethereum, itsnonceis the order’s nonce. -
The wallet signs. On Ethereum the type is
CancelOrder(string action,string orderId,uint256 nonce,uint256 expiresAt)under theMultiliquidBatchOrdersversion1domain. On Solana the wallet signs the message’s raw UTF-8 bytes. The message is this text, whoseTransaction:line is the user’s signature of the order’s transaction:A prepared Solana cancellation carries it inmessage: -
POST /v1/batch-orders/{orderId}/canceltakes thecancellationunchanged with thesignature, hex on Ethereum and base58 on Solana, and returns theorderIdandcanceledAt.
canceledAt. Preparing a cancellation at or after the cut-off answers 409 with CANCELLATION_CLOSED, which also covers an order that is already processing or final. A cancellation sent at or after its expiresAt answers 422 with CANCELLATION_EXPIRED. A prepared cancellation expires at the cut-off at the latest, so one sent at or after the cut-off answers CANCELLATION_EXPIRED.
Tracking an order
GET /v1/batch-orders/{orderId}?network= returns one order, and GET /v1/batch-orders?network=&user= lists a wallet’s orders, newest first. orderId is a lowercase UUID. The list also filters by capitalProvider, takes limit from 1 to 100, defaulting to 50, and continues with nextCursor; it has no state filter. A cursor continues only the list it was issued for, with the same network, user, and capitalProvider; another answers 400 with INVALID_REQUEST and details.field cursor. Both need no credential.
Place a batch order shows a full order.
Every order carries one
state, from Multiliquid’s records and on-chain evidence only, never from a capital provider’s report alone:
Keep reading an order that is
accepted, processing, or underReview:
canceledis final.- An
underRevieworder becomescompletedorfailed. - On Solana,
completedandfailedare final, because results come from finalized blocks only. - On Ethereum,
completedandfailedfollow the canonical chain as Multiliquid has verified it. Untilsettlement.blockNumberis finalized, a chain reorganization can return acompletedorder toprocessing,underReview, orfailed. Treat it as final once that block is at or below the chain’s finalized block. AfailedEthereum order becomescompletedonly when Multiliquid verifies an execution at or before its deadline.
completed order’s settlement reports what changed hands, in one shape on both networks, as a submission’s does:
A leg’s
fees lists each fee as {type, amount, token, paidBy}, as a swap quote does. On Ethereum it holds the issuer, spread, and capitalProvider fees of the leg’s swap event, in the capital provider’s stablecoin. On Solana it holds one protocol fee in the swap program’s fee token, which the capital provider’s fee account paid. When the network no longer lists a leg’s token, its inputToken or outputToken is null, and so is the leg’s amountIn or amountOut in it, because its decimals are unknown; fees is null when the network no longer lists the token the fees are paid in. The transaction evidence stays.
Limits
Order bodies are limited to 8 KiB, preparation bodies to 1 KiB, cancellation bodies to 3 KiB, and cancellation preparation bodies to 128 bytes. Order intake, preparation, and cancellation are in the anonymous write allowance, and the reads in the read allowance, of Rate limits.Related
Capital providers
Capacity, operators, released orders, and reports.
Retries and idempotency
What a repeated order or cancellation returns.