Skip to main content
Races every venue that can serve the pair and returns the best route, plus a quoteToken for /execute.

Request

integer
required
Source chain ID. See chain IDs.
integer
required
Destination chain ID.
string
required
Token address or Solana mint. Native coin: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.
string
required
Token address or Solana mint. Native coin: as above.
string
required
In the input token’s smallest unit. With call.exactAmount, the most your user sends.
string
required
The wallet that pays.
string
Where the output goes. Set it here: without it some routes return only a preview (executable: false), and most won’t accept a different one at /execute.
string
Where the input goes back if the swap fails. Defaults to userAddress. Needed when selling BTC from a userAddress that isn’t a Bitcoin address.
integer
1 to 5000. Omit for Auto: 50 bps, or the venue’s own setting on some routes (shown in slippage.bps). Setting it leaves out venues with no minimum output unless allowNoMinimum is set.
boolean
Let venues with no minimum output (Rift) race even though you set slippageBps. Default false.
string
best_output (default) or fastest, the quickest route within your slippage.
string[]
Venue IDs to leave out, including from RAVN’s multi-step routes. IDs are on Supported chains & venues.
string[]
Race only these venue IDs. A multi-step route races only when every venue in it is listed.
boolean
A private swap: only private venues race.
boolean
Your flow can answer Hinkal’s AUTHORIZE steps. Without it, Hinkal doesn’t race.
string
Your user’s IANA timezone, e.g. Europe/Berlin. Sent only to Houdini Swap. Default UTC.
boolean
You can post signed Solana transactions back to RAVN. Adds more Solana routes: see Bitcoin and Solana.
boolean
With broadcastViaRavn, your app signs RAVN’s Bitcoin PSBTs with the JS SDK’s signBitcoinPsbt handler. Adds Bitcoin routes: see Bitcoin and Solana.
object
End the swap with a call into your registered contract, such as a vault deposit for your user, instead of paying an address. See Call a contract after the swap.
integer
How long the race waits for venues, in ms. Default 6000, from 1,000 to 15,000.
boolean
Stream prices while the race runs. See Streamed response.
boolean
Test the flow without moving funds. See Sandbox mode.

Response

string
Pass it to /execute as is. Never parse it.
object
The winning venue’s id, name and logoUrl (its logo, absent when RAVN has none). RAVN’s own multi-step routes are named RAVN and list their venues in hops.
string
For example CROSS_ECOSYSTEM or EVM_CROSS_CHAIN.
object
The input token and amount.
object
The output token and quoted amount.
string
What RAVN expects the route to deliver. The same as output.amount unless the route has no minimum output. Rank on this if you sort routes yourself.
object
Your integrator fee: bps, amount, token, supported. See Pricing.
boolean
false means a preview only. /execute refuses it with QUOTE_NOT_EXECUTABLE, naming the missing address in details.missing: quote again with it.
object
bps, isFirm, guaranteedMin, noMinimum, expectedShortfallBps, or null. When noMinimum is true there is no guaranteed minimum: the user can get more or less than quoted. Tell them before they send.
object
Native gas the user needs: native, nativeSymbol, usd, estimated. null on gasless routes.
string
USD value of the input. null when it can’t be priced.
string
USD value of the output. Compare with inputUsd to warn about a large loss.
number
Expected time to settle. Can be fractional.
boolean
true when the venue gave no timing, so the estimate is generic.
integer
Epoch ms. Execute before it. Up to 10 minutes later, /execute prices the route again and builds it only if it still meets the minimum this quote showed, else 410 QUOTE_EXPIRED.
array
On RAVN’s multi-step routes, the venues it runs through, in order, each shaped like venue. The user signs only the first.
array
Every other usable route, best first. Each has its own quoteToken (execute it to take that route), inputAmount, expectedOutputAmount, fee, slippage and expiresAt. With call.exactAmount, compare them on inputAmount. Skip any with pickable: false.
The response is abbreviated: tokens carry full metadata, and alternatives carry every field above. Returns 404 NO_LIQUIDITY when no venue can serve the pair or amount. See Errors.

Streamed response

With "stream": true the answer is newline-delimited JSON (application/x-ndjson), one event per line. The first prices usually arrive within a second.
  • venues: the venues racing.
  • settled: one venue answered. Show its prices, but don’t execute them (they have no quoteToken). quotes is empty when it had nothing usable.
  • preview: an early price from RAVN’s own multi-step route, before its settled. Show it like settled; that route’s next preview or its settled replaces it.
  • done: the final answer, always the last line. Execute only this one. A failed race carries status (such as 404) and error here, because the HTTP status was already 200.
A request refused before the race starts gets a normal JSON error. A stream that ends without done failed: request it again.

Call a contract after the swap

Set call and the output goes into your contract instead of to an address: a vault, perps or privacy-pool deposit for your user, from any supported chain, Bitcoin included, in one step. Not to or from Ink yet.
  1. Ask RAVN to register your contract and its function on your key, for each chain. Any other call gets 400 INVALID_REQUEST.
  2. Set outputToken to the ERC-20 your contract takes, and destinationAddress to your user’s EVM address.
  3. Fill in call:
    • target: your contract on the output chain.
    • data: the calldata, selector included.
    • amountAt: the byte offset in data, selector included, where RAVN writes the amount as a uint256: 4 for deposit(uint256 assets, address receiver). Leave it out only when data already holds exactAmount.
    • exactAmount: put exactly this much of outputToken into the call, in its smallest unit. Your user then sends only what that takes (input.amount). Without it, the call gets output.amount, what the swap of inputAmount guarantees.
    • leftoverTo: where anything the call doesn’t spend goes. Defaults to destinationAddress.
The venue’s contract makes the call, not your user’s wallet. data must name your user as the owner of what the call creates (receiver, onBehalfOf): anything credited to the caller can be taken.
This deposits 10 USDC from Arbitrum into a vault on Base for 0x1111…1111. output.amount is what the call receives. RAVN runs the call against the chain before quoting. A call that fails that run comes back as 404 NO_LIQUIDITY: check data, that your contract credits your user and, with exactAmount, that inputAmount covers it. If the call fails when the swap lands, your user gets the input back on the source chain, or the output token at destinationAddress. An expired call quote isn’t priced again at /execute: quote again. Your fee on top (0 to 1%, 60% of it yours) works as on any swap. From Bitcoin, the call lands on Ethereum, Base, Arbitrum, Optimism, Polygon, Avalanche or Monad; into Avalanche or Monad, set exactAmount. Your user sends deposit.amount in one plain transfer: your fee is taken inside the route in outputToken, so there’s no fee output to add. With exactAmount, deposit.amount carries a margin so the price can move while the BTC confirms. For a vault, ask RAVN to register your contract for a leftover: all of it is then swapped, the call gets exactly exactAmount, and the rest goes to leftoverTo in outputToken in the same transaction. The margin is about 3% at the default slippageBps, so set inputAmount to cover it; above a slippageBps of 3% the leftover isn’t offered. Otherwise, as for a privacy pool, nothing is paid beside the deposit: what the swap didn’t use goes back to their Bitcoin refund address minus a refund fee (currently about 1,900 sats), so a smaller surplus isn’t returned. A call that fails when the swap lands is refunded at destinationAddress, not in BTC.