401 with UNAUTHORIZED.
Acceptance reserves the capital provider’s capacity, not the user’s funds. The user’s balance, approval, and eligibility must still hold when the order executes, and execution is best effort until the deadline.
Before you start
- A capital provider that takes batch orders for the pair.
GET /v1/swap/pairslists them in each pair’sbatchCapitalProviders. Discovery describes the list. - Open intake and capacity.
GET /v1/batch-orders/inforeturns thebatch, whoseintakeOpensays whether it takes orders now, and each capital provider’sacceptingOrdersandavailablecapacity per token, in whole tokens. Intake closes at 4:30 PM New York and reopens for the next batch at 5:00 PM. Preparation also checks the order against the capacity left, inchecks.capacity.
Response
1. Prepare
Name the swap as you would for an instant swap, with the capital provider’sid. The amount is in whole tokens, with at most 6 decimal places: 1000 is 1,000 USDC.
Response
The order’s bound has no slippage buffer, so if the price moves against it before submission, prepare and sign again.
A failing check does not fail the preparation. When
checks.capacity.sufficient is false, don’t land the approval: submission would answer INSUFFICIENT_CAPACITY. Order at most what available covers, or choose another capital provider.
2. Approve
Whenapproval is not null, land it before you submit the order, and wait until it is confirmed: the order’s signature does not grant the allowance. The approval is complete, with the user’s nonce, gas, and fees filled in, so the wallet signs serialized as returned and sets none of them itself. Then either:
- signs the
transactionwithout broadcasting it, and you submit it alone toPOST /v1/submissionsand wait until it isconfirmed; or - sends it itself, as a wallet that can only broadcast, such as a browser wallet or a custody platform, does.
3. Sign and submit
The wallet signstypedData as it is. Send order exactly as prepared, with the signature. Its inputs name the IDs assetInId, assetOutId, and stablecoinDelegateId, where typedData.message names them assetInID, assetOutID, and stablecoinDelegateID, so an order rebuilt from the typed data is rejected.
201 with the order’s ID and the batch it joins:
Response
typedData is in the eth_signTypedData_v4 form, with EIP712Domain in types. Wallets and custody platforms that take the raw JSON sign it as it is.
On Solana, prepare returns the unsigned transaction in place of typedData and approval. It 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 wallet signs it unchanged with signTransaction and does not send it: the operator signs and sends it after the release. Submit the order with the signedTransaction to POST /v1/batch-orders, never to POST /v1/submissions. Batch orders gives the Solana fields.
4. Track the order
ReadGET /v1/batch-orders/{orderId}?network=evm-mainnet. The list, GET /v1/batch-orders?network=evm-mainnet&user=0x..., returns each order in this shape under orders, newest first, with nextCursor:
Response
Keep reading an order while it is
accepted, processing, or underReview. A deadline falls before the next day’s 5:00 PM release, so an order is past processing by then. On Solana, completed and failed are final. On Ethereum, treat a completed order as final once settlement.blockNumber is finalized.
Cancel an order
The user can cancel an accepted order until the batch’s 4:30 PM cut-off. Prepare the cancellation:Response
nonce is the order’s nonce. The wallet signs typedData. Send the cancellation unchanged, with the signature, before its expiresAt, five minutes after you prepared it (here 1796142000, 16:20:00 UTC):
Response
message in place of typedData, which the wallet signs with signMessage.
When something goes wrong
Batch orders lists every rejection.