Overview
Multi-swap lets partners create multiple independent swap orders in a single API call, grouped under a sharedmultiId. Each order is individually priced and executed, but they can all be tracked together via a single status endpoint.
Best For: Platforms distributing payouts to multiple recipients, batch airdrop tools, or any use case requiring several simultaneous swaps from the same source token.
Key Features
Single Request, Multiple Orders
Create up to many orders in one request, all linked by a shared
multiIdCEX & Anonymous Routing
Supports standard (CEX) and private (anonymous) routing per order
Per-Order Status
Track all orders in the group with a single
GET /exchanges/multi/{multiId} callHow It Works
Create Multi-Swap
Call
POST /exchanges/multi with an array of orders. Each order specifies token IDs, amount, destination address, and optional routing flags.Generate Batch Transaction (Solana only)
For Solana source tokens, call
GET /exchanges/multi/{multiId}/tx?sender={senderAddress} to get pre-built batched transactions. Each transaction covers up to 10 deposit addresses — if your batch has more than 10 orders, the response returns multiple transactions to submit separately.Integration Guide
Step 1: Get Tokens
Use token IDs (not symbols) when building your orders. Fetch and cache the token list from/tokens:
- Bulk Fetch + Cache
- Token Search
Step 2: Create Multi-Swap
CallPOST /exchanges/multi with an orders array. Each order is independent — different token pairs, amounts, and destination addresses are all supported in the same batch. Set anonymous: true on any order to enable private routing for that order.
Create Multi-Swap Response
multiId: Shared identifier for the batch — use this to poll status for all ordersorders[].order: Full order object for successfully created orders (see Order Lifecycle)orders[].error: Per-order error if creation failed — the rest of the batch is unaffecteddepositAddress: Each order has its own unique deposit addressstatusLabel: Starts asNEW— orders are initialized asynchronously
Order Fields Reference
| Field | Description |
|---|---|
from | Token ID of input token (24-char MongoDB ObjectId) |
to | Token ID of output token |
amount | Input swap amount |
addressTo | Destination wallet address for output funds |
anonymous | true to enable private multi-hop routing |
destinationTag | Memo/tag for chains that require it (e.g. XRP, XLM) — max 64 chars |
useXmr | true to force XMR as the anonymous bridge layer |
walletInfo | Additional wallet metadata — max 256 chars |
Step 3: Monitor Multi-Swap Status
PollGET /exchanges/multi/{multiId} to retrieve status for all orders in the group at once:
Multi-Status Response
Step 4: Generate Solana Batch Transaction
For Solana source tokens, you can fund all deposit addresses with pre-built transactions instead of sending separate transfers. CallGET /exchanges/multi/{multiId}/tx?sender={senderAddress}:
Batch Transaction Response
chain: Always"solana"— only Solana is supported for batch transactionstransactions: Array ofTxBatchobjects — each covers up to 10 orders. Batches with more than 10 orders return multiple items; submit each transaction separatelyhoudiniIds: The order IDs funded by this specific transactiontxData.data: Base64-encoded serialized Solana transaction — deserialize, sign, and submit
Best Practices
Handle Per-Order Errors
Handle Per-Order Errors
The multi-swap endpoint returns a partial success response — some orders may fail while others succeed. Always check each item in
orders[] for an error field before proceeding, and handle failed orders independently without canceling the batch.Wait for INITIALIZING to Resolve
Wait for INITIALIZING to Resolve
Orders returned with
statusLabel: "INITIALIZING" are still being set up. Poll GET /exchanges/multi/{multiId} until all orders reach NEW or WAITING before sending deposits.Expiry Windows
Expiry Windows
Each order has its own
expires timestamp (typically 30 minutes from creation). For Solana batch transactions, sign and submit all transactions promptly — if any order expires before confirmation, that order will not be funded.Submitting Multiple Batch Transactions
Submitting Multiple Batch Transactions
If your multi-swap has more than 10 Solana orders, the
transactions array will contain multiple items. Submit each transaction independently — they are not dependent on each other and can be submitted in parallel.Security
Security
Never expose API keys in frontend code. Validate all
addressTo values before submission. Store multiId and each houdiniId for audit trails and support lookups.Common Issues
Some Orders Return Errors
Some Orders Return Errors
Cause: Individual orders can fail validation (unsupported pair, amount out of range, invalid address) while the rest of the batch succeeds.Solution: Check each
orders[].error in the response. Re-submit failed orders individually with corrected parameters. The valid orders in the batch are unaffected.Batch Transaction Not Available
Batch Transaction Not Available
Cause: Batch transactions require all orders to share the same Solana source token.Solution: Use separate individual deposits for non-Solana source tokens.
Order Expired Before Deposit
Order Expired Before Deposit
Cause: The 30-minute deposit window elapsed before funds were sent.Solution: Re-create the expired orders with a new multi-swap request. Deposit promptly after creation.
Orders Stuck at INITIALIZING
Orders Stuck at INITIALIZING
Cause: Order setup is asynchronous and may take a few seconds.Solution: Poll
GET /exchanges/multi/{multiId} every 5–10 seconds until all orders leave the INITIALIZING state before proceeding.Anonymous Order Taking Longer
Anonymous Order Taking Longer
Cause: Private routing passes through an additional
ANONYMIZING stage.Solution: This is expected. Monitor statusLabel per order — anonymous orders typically complete in 15–45 minutes.Next Steps
Standard Swap
Single-order CEX swaps
Private Swap
Multi-hop anonymous swaps
Order Lifecycle
Understand all order statuses
Error Handling
Handle errors and edge cases