Skip to main content
Ratio does not currently provide webhook callbacks. Track swap execution and settlement using the GET /v1/executions endpoint.
1

Submit on-chain transaction

After receiving a firm quote, send the commitFirmQuote transaction to the FxEngine contract. Record the tx_hash from the transaction receipt.
2

Poll for confirmation

Call GET /v1/executions?quote=0x{quote_id} or GET /v1/executions?tx=0x{tx_hash} to check settlement status. If the response is 404, the indexer hasn’t caught up — retry after 3–5 seconds.
3

Confirm settlement

When status returns SETTLED, the swap is confirmed on-chain. Record the filled_rate, destination_amount, total_fee_usd, and settled_at for your records.

​
Lookup methods

You can look up an execution by any one of these identifiers: Only one lookup parameter at a time. Combining them returns 400.

​
Polling best practices

  • Start polling 2–3 seconds after the on-chain transaction confirms
  • Use exponential backoff: 3s → 5s → 10s → 15s
  • Give up after 10 attempts — at that point, verify the transaction on Kaiascan (mainnet, Kairos testnet) using the tx_hash
  • For batch reconciliation, use GET /v1/reports/daily-summary instead of polling individual executions

​
Execution history

For bulk queries or end-of-day reconciliation, use the history mode of GET /v1/executions without a lookup parameter. This returns cursor-paginated results filtered by pair, status, and date range. See the Executions API reference for query parameters.