Use this page when you need more than the quickstart and want the full integration sequence.
Integration sequence
| Step | Action | Failure to handle |
|---|
| 1 | Fetch quote | quote unavailable, unsupported route, expired quote |
| 2 | Generate secret | insecure randomness, secret leakage, secret reuse |
| 3 | Create order | quote consumed, amount mismatch, duplicate commitment |
| 4 | Initiate source side | allowance failure, wrong token, wrong amount, already deployed |
| 5 | Wait for solver | solver delay, destination side missing |
| 6 | Claim destination side | wrong secret, hop payload mismatch, vault missing |
| 7 | Poll completion | watcher lag, bridge pending, expiry, cancel path |
Quote and order rules
The order payload must match the consumed quote exactly:
- source asset
- destination asset
- source amount
- destination amount
- quote ID
If the user edits amount, asset, recipient, or route after quote selection, request a new quote.
Initiation rules
Use the chain registry and order response to choose the right factory and token address. For Avalanche routes, the effective settlement chain may differ from the final destination chain because hop routes settle through a bridge-chain vault first.
Polling rules
Poll GET /orders/{order_id} and read:
source_intent.create_tx_hashdestination_intent.create_tx_hashdestination_intent.claim_tx_hashdestination_intent.bridge_tx_hashsource_intent.claim_tx_hash- any
cancel_tx_hash
Show transaction hashes as soon as they exist. Users trust a pending swap more when they can inspect the chain themselves.
Recommended UI states
| UI state | Order fields |
|---|
| Waiting for source initiation | missing source_intent.create_tx_hash |
| Waiting for solver | source initiated, destination not initiated |
| Ready to claim | destination initiated and not claimed |
| Claim pending | claim submitted, waiting for watcher update |
| Bridge pending | hop route with bridge dispatch not finalized |
| Complete | expected claim fields populated for the route |
| Cancel available | expiry reached and claim missing |
Integration checklist
- Keep the raw secret out of logs, analytics, URLs, and crash reports.
- Treat quote and order amounts as base-unit strings.
- Store
order_id and both swap_id values.
- Read route metadata before deciding what “complete” means.
- Give users a visible cancel path for expired swaps.
