/networks, /quote, /sources, /destinations) are public — they work without a key. Send the key anyway so the environment and your app attribution are right.
If auth fails: an invalid key returns 403 with {"error": {"code": "API_KEY_FORBIDDEN", "message": "Api key forbidden"}}. A missing key silently gives you public mainnet access — don’t mistake it for a working testnet setup.
1
Check the route and limits
ETHEREUM_MAINNET — enumerate them with GET /networks, or use GET /sources / GET /destinations to see what’s routable from where.If the route doesn’t exist: 404 — {"error": {"code": "ROUTE_NOT_FOUND_ERROR", "message": "Route not found"}}. The pair isn’t currently supported; there is no partial success.If a parameter is malformed (bad enum value, missing required param): the API returns 400 with an empty body — no JSON. Treat empty-body 400s as validation failures and re-check parameter names and casing.2
Get a quote
data. Fee semantics live in Fees; avg_completion_time is a .NET-style duration string.Request a quote to preview the transfer. Swap creation calculates a new quote; use the quote returned with the created swap for its amounts and slippage. Refresh the preview when the route, amount, or options change.If the amount is out of range: compare against the /limits response from step 1 — quotes for amounts outside min/max fail.3
Create the swap
data.swap.id) and data.deposit_actions — the instructions for funding it. Store the id; it’s your handle for tracking.Provide a valid source-network refund_address. It is required for routes involving a swap provider unless use_deposit_address is enabled. A missing required address returns REFUND_ADDRESS_MISSING. See Refunds.Use reference_id to correlate a swap with an action in your application. Reusing it can replace an unfunded swap or reject creation, depending on the existing swap’s status. See Reference IDs and repeated requests before retrying swap creation.4
Fund the swap
Each entry in
deposit_actions tells you where and how to send the funds — to_address, amount, amount_in_base_units, and for contract interactions call_data. For this direct transfer, have the user’s wallet send the exact amount to to_address on the source network.Other funding methods use the same swap object with different flags: Depository contract calls (use_depository) and gasless signatures (use_gasless).If the user sends an invalid amount: inspect fail_reason; the swap may enter the refund flow. If the user never sends: the swap moves to expired after six hours. See Swap lifecycle & statuses instead of inferring recovery behavior.5
Track to completion
data.swap.status walks the lifecycle: user_transfer_pending → deposit detected → ls_transfer_pending → completed. Terminal failure states are failed, expired, and refunded. The full state machine is in Swap lifecycle & statuses; the separate PascalCase query vocabulary is in Track swaps.You can also look a swap up by its funding transaction: GET /swaps/by_transaction_hash/{hash}.For push notifications, configure Webhooks in the Partner Dashboard. Make receivers safe to process duplicate events and check the current swap status before fulfillment.Next steps
- Understand what you used: Routes, quotes & limits and Swap lifecycle & statuses
- Implement source-network actions: Fund by transfer, Depository, or Gasless deposits
- Prepare for launch with the Production checklist