Skip to main content
Shops every eligible venue and returns the best price plus an opaque quoteToken to pass to /execute.

​
Request

​
integer
required
Origin chain ID.
​
integer
required
Destination chain ID.
​
string
required
Contract address or mint, or the native sentinel.
​
string
required
Contract address or mint, or the native sentinel.
​
string
required
Positive integer in the token’s smallest unit.
​
string
required
The sender’s address.
​
string
Recipient on the destination chain. Some venues need this here, at quote time, to return a firm, executable quote at all: notably Relay when Bitcoin is either side, THORChain on a Bitcoin route either direction, Across on a Solana-touching route, and Eco on a cross-ecosystem route. Omit it on those and you get back a priced but unexecutable preview instead (see executable below), not an error. Only Chainflip, Houdini Swap, Layerswap, Mayan, NEAR Intents, and Rift accept a different recipient later on /execute; every other venue fixes it here, and /execute rejects a different one with 400 INVALID_REQUEST. Hinkal (a private venue) fixes the payout when it prices, and doesn’t quote at all without this. Supply the real address here whenever you have it.
​
string
Where the input asset is refunded if the swap fails. Selling native Bitcoin with userAddress set to a Bitcoin address and no refundAddress refunds to userAddress, the address the BTC is sent from; when selling BTC from any other userAddress, supply it. A Bitcoin-source Relay or THORChain quote needs the refund known here, at quote time, for the same reason as destinationAddress above, and a different one on /execute is refused with 400 INVALID_REQUEST. Chainflip, Houdini Swap, NEAR Intents, and Rift accept it as a late addition on /execute instead. Hinkal never refunds on its own, here or anywhere: what a failed Hinkal swap leaves waits at Hinkal until the paying wallet (userAddress) recovers it to itself with POST /recover. So a refundAddress other than userAddress leaves Hinkal out of the race.
​
integer
1 to 5000. Quotes that would slip more than this are dropped (Rift, with allowNoMinimum, is the exception: it has no minimum to measure). Omit it for Auto, RAVN’s default of 50 bps (0.5%). On Auto, THORChain, NEAR Intents, and Relay use 1% on Bitcoin-source swaps, which fill only after a Bitcoin confirmation, and Chainflip uses its own recommended tolerance; those quotes show the limit they apply in slippage.bps. A two-hop RAVN route (venue.id is compose) uses 1% on Auto, because the tolerance has to cover both legs; it shows that in slippage.bps too. A value you set is used as is, on those venues too. Rift, which enforces no minimum output, races only on Auto unless you set allowNoMinimum.
​
boolean
Let venues that enforce no minimum output (today Rift) race even though you set slippageBps. Without it, a request with its own slippage never gets a Rift quote; on Auto, Rift races either way. Such a quote fills at the venue’s own rate once the deposit lands: it carries slippage.noMinimum: true and slippage.guaranteedMin: null, and your slippageBps does not protect it, so show that to the user before they send. Defaults to false.
​
string
best_output (default) or fastest. best_output is the literal highest net output, full stop. fastest picks the quickest-settling quote among quotes within slippageBps, even at a real output cost.
​
string[]
Venue IDs to leave out, for example if /health shows one degraded or you have a standing risk objection to it. An excluded venue is used nowhere in the route, including the steps of RAVN’s multi-step routes (compose, and relay quotes that carry hops); a multi-step route that needs it isn’t offered. Venues that swap for you may route through other venues of their own choosing, which this can’t reach: Layerswap (a Solana token often goes through Jupiter first), Relay, Rift, Across (when it swaps before or after bridging) and Mayan (Jupiter on Solana, other DEXs such as Nordstern on EVM). See Supported Chains & Venues for the ID of each venue.
​
string[]
Race only these venue IDs, for example ["bebop"] for an RFQ-only race. Every other venue is left out, including any RAVN adds later, and excludeVenues still applies on top. It covers every venue RAVN routes your funds through: a multi-step route is offered only when its own venue.id and every venue in its hops are listed, for example ["compose", "jupiter", "relay"] for RAVN’s routes through Jupiter and Relay, or ["relay", "kyberswap"] for a Relay quote that buys through KyberSwap on arrival. RAVN’s stablecoin route also needs 0x_swap beside its hops: it sweeps the leftover. Venues that swap for you may route through other venues of their own choosing, which this can’t reach: Layerswap (a Solana token often goes through Jupiter first), Relay, Rift, Across (when it swaps before or after bridging) and Mayan (Jupiter on Solana, other DEXs such as Nordstern on EVM). Houdini Swap and Hinkal race only on a confidential request, which races only the private venues (near_intents, houdini, hinkal); naming hinkal also says your flow answers its AUTHORIZE steps, as authorizeSteps does. Same-chain venues only quote same-chain pairs; if none of the venues you name can quote, you get 404 NO_LIQUIDITY. An empty list is rejected with 400 INVALID_REQUEST.
​
boolean
Settle through a private venue, so the deposit and the payout aren’t directly linked on-chain; how strongly depends on the venue. The race narrows to NEAR Intents (Confidential Intents), Houdini Swap and Hinkal, best output wins, and you get 404 NO_LIQUIDITY rather than a public fill if none can quote. It costs more and can settle slower than a public swap: NEAR adds about 0.3 bps EVM to EVM and 5 to 8 bps when Bitcoin or Solana is a leg; Houdini prices about 3% below spot and takes a few minutes to about an hour; Hinkal delivers about 0.3 to 0.45% less than NEAR (its own and LI.FI’s fees, and a deposit of 450k to 670k gas) and pays out 5 to 30 seconds after the deposit, then bridges. Read estimatedTimeSeconds before executing. Hinkal races only with authorizeSteps: true (or onlyVenues naming hinkal), from Ethereum, Base, Arbitrum, Polygon, BNB Chain or Robinhood Chain, up to $10,000, with destinationAddress set here. /execute then builds it in steps: two AUTHORIZE answers (signatures from the paying wallet that move no funds), then the TRANSACTION that pays the deposit, to send within 10 minutes of receiving the second AUTHORIZE. A failed Hinkal payout is not refunded on its own: the paying wallet recovers it with POST /recover, an ordinary on-chain payment back to that wallet, which can link it to the wallet it was paying. Hinkal’s privacy is thinner than NEAR’s: it has few users and pays out seconds after the deposit, so timing can still link the two wallets. Its minimum isn’t guaranteed: RAVN refuses to build below the minimum the quote shows, but LI.FI makes the payout. Houdini is sent the request’s IP and user-agent, plus clientTimezone, for its compliance screening, and its terms bar US persons and sanctioned jurisdictions: RAVN leaves Houdini out when your request comes from such a country, and you are responsible for your end users’ eligibility. Pass excludeVenues: ["houdini"] where you can’t meet that. Hinkal’s terms bar Cuba, Iran, North Korea, Syria, and Crimea, Sevastopol, Donetsk and Luhansk: RAVN leaves Hinkal out when your request comes from one, and the same responsibility applies (excludeVenues: ["hinkal"]). Confidentiality is the venue’s, not RAVN’s, and remains subject to its screening. See Private swaps.
​
boolean
Set it when your execute flow can answer AUTHORIZE steps: collect the paying wallet’s two signatures and call /execute again with each (see AUTHORIZE steps). SDK 0.4.1 or later types it, and its executeAndTrack answers the steps given signMessage and signTypedData; the Python client types it from 0.1.7. Without it, or onlyVenues naming hinkal, a confidential race leaves Hinkal out, so a flow that can’t sign never gets a Hinkal quote. /x402/quote and the MCP server never race Hinkal. Default false.
​
string
Your end user’s IANA timezone, for example Europe/Berlin. Forwarded only to Houdini Swap, whose API requires it on every call. Defaults to UTC.
​
boolean
Test /execute, /submit-signature, /submit-transaction, and /status with no real funds and no live venue settlement. Doesn’t affect pricing, the quote is still live. Rides through the quoteToken automatically, no other flag needed. See Sandbox Mode.
​
integer
The race’s time limit in milliseconds, counted from when it starts. Default 6000, the limit RAVN’s own app uses; a positive integer, clamped to 1,000 to 15,000 (0 or a negative number is 400 INVALID_REQUEST). Once the limit has passed and some venue has priced the swap, venues still silent are left out, so they aren’t in alternatives either, and the best of the rest is returned. If none has priced by then, the race waits for the first price and then leaves out the rest. A quote with slippage.noMinimum counts as a price only 2 seconds past the limit, so venues that hold a minimum get that long to answer, and RAVN’s own route gets 2 seconds more on pairs where its cross-chain WBTC plan races. Lower it to answer sooner, raise it to wait for slower venues.
​
boolean
Set it if you can post a signed Solana transaction back to RAVN instead of broadcasting it yourself. It adds routes that only work when RAVN checks or lands the signed transaction. Layerswap’s memo payments, which sell a Solana wallet’s own USDC into native BTC or its USDG into a Robinhood Chain stock with no account rent, often the best price under about $200; RAVN’s Jupiter → Layerswap route for other Solana tokens then pays Layerswap this way too, when that leaves the user more. And Jupiter’s market-maker (JupiterZ) and gas-sponsored orders, which a market maker or Jupiter signs too, inside Jupiter’s own landing (a long-tail Solana token can price 7 to 33 bp better). Without it, Jupiter quotes only orders your user signs alone, and one that needs Jupiter’s gas sponsor (a wallet short of SOL) is a preview (executable: false). When /execute then returns a TRANSACTION with submit, sign transaction.serialized and post it to /submit-transaction instead of broadcasting it; broadcast any transaction without submit yourself, as usual. A Jupiter order carrying your fee under Jupiter’s 50 bps minimum comes without submit: RAVN’s fee transfer is added to it, which Jupiter’s landing doesn’t take, so your user signs it alone and you broadcast it. /execute simulates a memo payment when it builds it, so the wallet must already hold the amount and SOL for fees. /x402/quote ignores this field, and the MCP server can’t execute a quote whose winning route needs it.
​
boolean
Answer while the race runs instead of once at its end: see Streamed response. Default false. /x402/quote ignores it.
No API key required (see Authentication for the optional higher-limit tiers).

​
Response

​
string
Opaque handle. Pass it to /execute verbatim and do not parse it. Usually a short id (rq_…) for the quote RAVN keeps until at least 10 minutes past expiresAt; now and then the whole signed quote, which works the same. Once RAVN no longer holds it, /execute returns 410 QUOTE_EXPIRED.
​
object
The id and name of the winning venue. RAVN’s own multi-step routes, which it plans, checks before signing, and holds to the minimum shown, are named RAVN: two-hop and stablecoin-route quotes (venue.id is compose) and Relay with a DEX on arrival (venue.id is relay). Their hops list the venues they run through.
​
string
For example, CROSS_ECOSYSTEM or EVM_CROSS_CHAIN.
​
object
The input token and amount.
​
object
The output token and expected amount.
​
string
What RAVN counts on this route delivering, in the output token’s smallest unit. The same as output.amount for every quote that holds a minimum. For one that doesn’t (slippage.noMinimum, today Rift) it is output.amount less slippage.expectedShortfallBps. RAVN ranks routes on this figure less gas. alternatives already arrive in RAVN’s order, so the simplest way to keep it is not to re-sort. If you do sort routes yourself, sort on this rather than the raw amount (a no-minimum route can quote a little more and still rank, and usually deliver, less), and skip alternatives with pickable: false. Every alternative and streamed price carries it too.
​
object
The applied integrator fee: bps, amount, token, and supported. amount is in token’s smallest unit, and token is the output token on every venue except Fly Trade and Mayan, which take the fee from the input token, and the routes where RAVN collects it beside the swap, also in the input token: Rift, Eco Routes, Layerswap, Mayan routes paying no referrer, Fly Trade’s coin sells outside Ethereum, Base and Polygon, and private swaps (see Pricing). A Fly Trade coin sell on Robinhood Chain or Arbitrum is the exception: there token is the chain’s WETH, which RAVN’s fee is minted as. Some venues switch to the input token on certain pairs (KyberSwap, 0x Swap, 0x Gasless and OKX DEX when the output is a native coin; OKX DEX and 0x Solana on some Solana pairs), so read it from each quote. amount is the gross fee (the quoted output is already net of it), the same figure RAVN’s ledger pays you on. supported: false means no fee can apply on this route (Eco Routes from Solana or Bitcoin, Layerswap and Houdini Swap from Bitcoin), regardless of what fee your key has set. On NEAR Intents, bps and amount include 1Click’s own fee, which it takes from the input on every swap whether or not you set one (20 bps, or 1 bp when both tokens are USDC, USDT or DAI, or the same asset; keyless calls included), so a NEAR quote never shows bps: 0; the quoted output already reflects it. See Pricing for the full breakdown.
​
boolean
False means this is a preview only, priced against a placeholder destination or refund address rather than the ones you supplied (or didn’t). Posting quoteToken to /execute in that state fails with 400 QUOTE_NOT_EXECUTABLE, whose error.details.missing names the address it was priced without. Request a fresh quote with the missing address instead of retrying /execute.
​
object
The bps, isFirm, guaranteedMin, noMinimum, and expectedShortfallBps, or null. noMinimum: true means the venue enforces no minimum output at all (Rift fills at its own best rate once the deposit lands), so bps is not a protection and the user can receive more or less than quoted. Show that to the user before they send funds. expectedShortfallBps is how far under its output RAVN counts on such a route delivering, from what these routes have delivered: by swap size and whether both tokens are on RAVN’s list (memes count as unlisted), from 5 bps (a swap of $1,000 or more in listed tokens) to 100 bps (under $100). It is 0 when noMinimum is false, and expectedOutputAmount already has it taken off.
​
object
Native gas the user must hold: native, nativeSymbol, usd, and estimated. Null on gasless venues.
​
string
USD value of the input amount, same price source as gas.usd. Null when the token can’t be priced.
​
string
USD value of the output amount. Compare against inputUsd for price impact, or flag a large loss to the user before they sign. Null when the token can’t be priced.
​
number
Seconds until the swap is expected to settle. Not always a whole number (Chainflip’s, for example, can read 162.4), so round it yourself for display.
​
boolean
True when the venue didn’t report a timing figure for this quote, so estimatedTimeSeconds is a generic placeholder rather than a venue-reported number.
​
integer
Epoch milliseconds, always a real time (never 0). Post quoteToken to /execute before this, and request a new quote after it. RAVN never refuses a quote for age before expiresAt. For up to 10 minutes past it, /execute prices the same route again (same venue, amount, addresses and fee, at half the slippage the quote carried; this can add up to about 6 seconds) and builds that if what it guarantees still meets the minimum this quote showed: the output itself when slippage.isFirm, else slippage.guaranteedMin, else outputAmount less slippage.bps. The swap built that way can deliver less than this outputAmount, never less than that minimum, and the /execute answer doesn’t restate the new price. Otherwise it returns 410 QUOTE_EXPIRED: when the new price misses the minimum, the venue doesn’t answer, it’s more than 10 minutes late, or the quote has slippage.noMinimum or no slippage, which are never re-priced. It already sits 5 seconds ahead of the venue’s own deadline, leaving room for the wallet to sign, so compare it to the clock as is. Two-hop routes (venue.id is compose) and venues that set no deadline are never refused for age: for them expiresAt is 60 seconds from the response, the point to re-quote, not a price held for 60 seconds. /execute re-prices both hops of a two-hop route and returns BUILD_FAILED if the minimum shown can no longer be met.
​
array
Optional { id, name }[], the venues a RAVN route runs through, in order. Present when venue.name is RAVN: two-hop and stablecoin-route quotes (venue.id is compose) and Relay quotes with a destination call. The user signs hop 1 only: hop 1 pays hop 2 directly, so there is no second wallet transaction. The stablecoin route also sweeps its leftover through 0x (0x_swap), which isn’t listed here.
​
array
Every other venue that raced and produced a usable quote, ranked by what the user nets: expectedOutputAmount less the gas they’d pay (a first-time approval included), so a gasless or cheaper-to-send quote can sit above one with a larger outputAmount, and a quote with slippage.noMinimum counts 0.05–1% under its outputAmount (its slippage.expectedShortfallBps). That order holds under rankingMode: "fastest" too, where the winner is picked by speed instead. A noMinimum quote whose quoted output is more than 1% above the best quote that holds a minimum is listed here but never picked as the winner, as nothing holds that figure, so it can sit above the winner; with no quote holding a minimum in the race it can still win. Same input token and amount as the primary quote above. Each entry has its own quoteToken, pass it to /execute to run that route instead; its own expectedOutputAmount, same meaning as above; pickable, false when RAVN would never pick this route as its quote (a preview-only price while an executable route exists, or a noMinimum quote more than 1% above every quote that holds a minimum), so choose among pickable routes on expectedOutputAmount if you pick one yourself; its own fee with the same bps, amount, token, and supported fields as above (amount is in fee.token’s smallest unit: usually the output token, but the input token on Fly Trade, Mayan, the routes where RAVN collects it beside the swap, and the pairs listed under fee above); its own slippage, same shape as above or null, so check noMinimum on an alternative too; its own expiresAt, same meaning as above, which differs by venue (0x Solana and OKX quotes allow less time than most), so check it before executing an alternative; and an optional hops, as above. Empty when no other venue could serve this pair.
Returns 404 NO_LIQUIDITY when no venue can serve the pair or amount.

​
Streamed response

With "stream": true the answer is newline-delimited JSON (Content-Type: application/x-ndjson), one object per line, sent while the race runs. The first prices usually arrive within a second, while the race waits on its slowest venue.
  • venues: the venues racing this pair.
  • settled: one venue answered. Each quote has the fields of an alternatives entry except quoteToken and pickable. Show it, but don’t execute it. quotes is empty when the venue had nothing usable.
  • done: the result, the last line. data is the body the plain response carries, its quoteTokens included. The winner is chosen here, net of gas, so a venue that led mid-stream may not be it. When the race fails, done carries status (such as 404) and error instead, because the HTTP status was already 200 when the first line went out.
A request RAVN refuses before the race starts (malformed JSON or fields, unknown token, key, rate limit) gets the usual JSON error and HTTP status, not a stream. An address the race refuses (a bad userAddress, destinationAddress or refundAddress) comes in done as status: 400 INVALID_REQUEST. A stream that ends without a done line is a failed quote: request it again.