Skip to main content
Poll the progress of a swap. The ref depends on the execution type: POST with a JSON body, or GET with the same fields as query parameters. Prefer POST: a quoteToken can run to tens of kilobytes (two-hop and Relay routes), and in a query string a large one fails before it reaches RAVN (414 URI Too Long above about 32 KB, or a dropped connection).

​
Request

​
string
required
The quoteToken returned by /execute, not the one from /quote.
​
string
required
The statusRef or transaction hash for this swap.
​
string
An EVM transaction hash (0x and 64 hex characters; anything else is refused with 400 INVALID_REQUEST): the transaction that paid a fee your swap carries, where RAVN can’t find it otherwise; every other venue proves its fee itself. A two-hop route: the hop-1 transaction (not needed when hop 1 was submitted via /submit-signature); without it RAVN looks for hop 1 itself, among the payments into its fee wallet and its Bebop trades, usually within minutes of delivery; sending it books the fee on your poll instead. A fee RAVN collects beside the swap on an EVM chain (the execution’s fee.transaction: Rift, private swaps, Eco Routes, Layerswap, Mayan routes paying no referrer): the on-chain hash of the transaction that carried that payment, on its own or inside a wallet batch or relay (not an EIP-5792 batch id or a 4337 userOpHash); not needed when it rode in the swap’s own transaction and you poll with that hash. Simplest: send it on every poll; RAVN keeps it once confirmed. Until RAVN can read that transaction, a delivered swap is answered processing for up to 15 minutes after /execute, so keep polling to a terminal status, even when the venue’s own tracker already says delivered. Without this hash RAVN looks for the fee payment itself among what its fee wallet received in the 6 hours after /execute (and, on a two-hop route, for hop 1); a fee it can’t find is owed nothing (RAVN stops waiting for it a day after /execute). Its status is reported either way.
No API key required (see Authentication for the optional higher-limit tiers).

​
Response

​
string
The normalized lifecycle state.
​
string
The venue handling the swap.
​
string
The raw, venue-native status string behind the normalized status, for debugging. Present once a venue has been polled.
​
string
Present as "unavailable" whenever status is unknown. Absent otherwise.
​
string
The actual delivered output, in the output token’s smallest unit, when the venue exposes it. Null or absent otherwise, this is best-effort per venue, not every venue reports it.
​
string
The destination-chain transaction that paid the user out, when the venue names one. Only populated once status is terminal, not while a swap is still in flight.
Once terminal, a venue that reports it adds the delivery fields:
Status tracking is live for every venue on /health. Cross-chain and orderbook venues (CoW, 0x Gasless, Bebop, NEAR Intents, Relay, Across, Mayan, Eco Routes, Chainflip, THORChain, Layerswap, Rift, Houdini Swap, Hinkal) are resolved against the venue’s own tracker. Same-chain venues (0x Swap, 0x Solana, Nordstern, Fly Trade, KyberSwap, OKX DEX, Jupiter, Mayan same-chain) are resolved against the chain itself, see below.
Hinkal (ref is the statusRef from its TRANSACTION, Hinkal’s order id): a payout that fails is failed, never refunded, with venueStatus ending (needs recovery). Nothing comes back on its own: the funds wait at Hinkal until the paying wallet recovers them with POST /recover. deliveredAmount is read from LI.FI, which makes the payout, and only in the token asked for: a payout LI.FI made in another token (its swap on arrival failed) is success without it. RAVN keeps the swap’s record for 7 days; after that its status is unknown.
If quoteToken came from a sandbox quote, this always returns an immediate synthetic success with the quoted output as deliveredAmount. ref isn’t validated in that case, so any placeholder string works. Sandbox swaps are never metered and never earn a payout.

​
Settlement

Polling this endpoint is not just for your UI. It is how a swap reaches settled in RAVN’s ledger, and settled is the only state a fee payout is ever made on (see Pricing). RAVN runs a server-side backstop every few minutes. It resolves swaps whose ref RAVN already knew at /execute time (a NEAR Intents deposit address, a Relay request, a Chainflip deposit channel, a Rift, Houdini Swap or Hinkal order) and, on a swap made with your API key, finds the rest itself: a TRANSACTION swap without a statusRef (same-chain venues, Across, Eco Routes, Mayan, THORChain, RAVN’s stablecoin route) is looked for among the transactions your user’s wallet (userAddress) sends in the two hours after /execute, and the one carrying the exact transaction RAVN built is settled like a reported one. It can miss a swap sent from somewhere else (a relayer, a smart account selling the chain’s native coin) or later, and it doesn’t cover a fee-bearing Across or self-executed Bebop swap, whose fee only your poll can prove. So report every swap here anyway: your poll settles it at once, and your txHash names for certain an EVM transaction that paid a fee beside the swap on its own (RAVN also looks for one among what its fee wallet received in the 6 hours after /execute). On a same-chain venue (0x Swap, 0x Solana, Nordstern, Fly Trade, KyberSwap, OKX DEX, Jupiter, Mayan same-chain) that transaction is the settlement, so RAVN checks the chain, not your word, before marking the swap settled:
  1. the transaction at ref is mined on the quote’s chain and did not revert;
  2. it moved the quote’s full input amount of the quote’s input token;
  3. when the quote carried a fee in an ERC-20, that fee actually arrived in a RAVN fee recipient. The on-chain amount is what gets booked, not the quote-time estimate.
Anything short of that leaves the swap non-terminal and nothing is owed. Call this once for every TRANSACTION swap after the hash confirms, even if your integration has no other use for the answer: it doesn’t depend on RAVN finding the swap, and a keyless swap is never looked for. executeAndTrack in the JS SDK already does this. Two more rules that follow from the same design:
  • One ref settles exactly one swap. A hash or deposit that already settled another quote is rejected, and a ref that /execute already pinned to a swap (a deposit address, an order id) can’t be swapped for a different one.
  • A swap belongs to the key that requested the quote. That identity is signed into the quoteToken, so /execute and /status credit it to you even when the process calling them doesn’t hold your key. A second report on an already-terminal swap is a no-op.
Keep polling on expired. It is not a terminal state. It means the deal lapsed and a refund is owed but has not landed yet. On Across, the deposit is returned to the sender on the origin chain in a later settlement bundle, which per Across’s own docs can take several hours, at which point the status becomes refunded. Treat only success, refunded, and failed as terminal; stopping at expired will miss the refund.