Skip to main content
Batch orders let a user swap at a capital provider’s posted capacity in a daily batch instead of immediately. The user signs an order during the day, Multiliquid checks it and reserves capacity for it, and after the 5:00 PM New York release the capital provider’s operator executes it on-chain within the order’s signed deadline. The user’s wallet signature authorizes orders and cancellations; no credential is needed. A request may still carry an API key, which counts it against the key’s allowances instead of its IP address’s; an invalid, expired, or revoked key answers 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 its batchId, 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’s UnorderedSwapBatchApproval, 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.
The order names the capital provider’s current operator, a random 256-bit nonce, a deadline 24 hours after preparation moved into the batch’s deadline window, and one swap. Its bound equals the quote with no slippage buffer: the minimum output for exact input, the maximum input for exact output. If the price moves against the bound before submission, the order answers 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.
A prepared Solana order for 1 USDC, with its 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
Submit {"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’s checks 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 the details 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, answers 409 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’s cutoffAt. Cancellation is off-chain: it restores the reserved capacity, the order is never released, and the order’s nonce stays unused on-chain.
  1. POST /v1/batch-orders/{orderId}/cancel/prepare takes {"network": "..."} and returns the cancellation to send back, with what to sign: typedData on Ethereum, or on Solana the message for the wallet’s signMessage. The cancellation expires five minutes after it is prepared, or at the cut-off if that is sooner: its expiresAt, in Unix seconds, is exclusive. On Ethereum, its nonce is the order’s nonce.
  2. The wallet signs. On Ethereum the type is CancelOrder(string action,string orderId,uint256 nonce,uint256 expiresAt) under the MultiliquidBatchOrders version 1 domain. On Solana the wallet signs the message’s raw UTF-8 bytes. The message is this text, whose Transaction: line is the user’s signature of the order’s transaction:
    A prepared Solana cancellation carries it in message:
  3. POST /v1/batch-orders/{orderId}/cancel takes the cancellation unchanged with the signature, hex on Ethereum and base58 on Solana, and returns the orderId and canceledAt.
Place a batch order shows a full prepared cancellation. A valid repeat returns the original 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:
  • canceled is final.
  • An underReview order becomes completed or failed.
  • On Solana, completed and failed are final, because results come from finalized blocks only.
  • On Ethereum, completed and failed follow the canonical chain as Multiliquid has verified it. Until settlement.blockNumber is finalized, a chain reorganization can return a completed order to processing, underReview, or failed. Treat it as final once that block is at or below the chain’s finalized block. A failed Ethereum order becomes completed only when Multiliquid verifies an execution at or before its deadline.
A 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.

Capital providers

Capacity, operators, released orders, and reports.

Retries and idempotency

What a repeated order or cancellation returns.