Skip to main content
Store data.swap.id after creation. It is the primary identifier for tracking a swap through funding, execution, completion, failure, or refund.

Read one swap

Use data.swap.status for control flow and data.swap.transactions for input, output, refuel, and refund transaction details. See Swap lifecycle & statuses.

Reference IDs and repeated requests

Pass reference_id when creating a swap to correlate it with an action in your application. References are scoped to your app. Reusing a reference does not always return the original swap: Prevent concurrent submissions for the same user action. Store the returned swap ID and check whether a timed-out creation request succeeded before submitting another request. Reusing a reference can expire an unfunded swap whose deposit instructions you already displayed.

List swaps by address

GET /swaps requires address and accepts repeatable statuses filters:
Status filters are case-sensitive PascalCase values and are not the snake_case values returned on swap objects: Sending a response value such as completed or user_transfer_pending can return an empty-body 400. Preserve the exact casing above. Other filters include page, repeatable networks, and include_expired. Pages start at 1, default to page 1, and contain up to 20 swaps ordered by creation date, newest first. When no explicit statuses filter is supplied, expired swaps are excluded unless include_expired=true.

Find by transaction hash

When you know the source transaction hash:
This is useful after a wallet or server-wallet transaction has been submitted but your application lost the swap ID. The API also exposes GET /transaction_status for transaction-level inspection; see its generated reference for the required query shape.

Choose an observation mechanism

For server-side fulfillment, confirm the API status even if the browser already emitted onSwapComplete.