quoteToken for
/execute.
Request
Source chain ID. See chain IDs.
Token address or Solana mint. Native coin:
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.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.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.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.Let venues with no minimum output (Rift) race even though you set
slippageBps. Default false.Venue IDs to leave out, including from RAVN’s multi-step routes. IDs are on Supported chains & venues.
A private swap: only private venues race.
Your flow can answer Hinkal’s
AUTHORIZE steps. Without it, Hinkal doesn’t race.You can post signed Solana transactions back to RAVN. Adds more Solana routes: see Bitcoin and Solana.
With
broadcastViaRavn, your app signs RAVN’s Bitcoin PSBTs with the JS SDK’s signBitcoinPsbt handler. Adds Bitcoin routes: see Bitcoin and Solana.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.
Stream prices while the race runs. See Streamed response.
Test the flow without moving funds. See Sandbox mode.
Response
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.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.false means a preview only. /execute refuses it with QUOTE_NOT_EXECUTABLE, naming the missing address in details.missing: quote again with it.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.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.On RAVN’s multi-step routes, the venues it runs through, in order, each shaped like
venue. The user signs only the first.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.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 noquoteToken).quotesis empty when it had nothing usable.preview: an early price from RAVN’s own multi-step route, before itssettled. Show it likesettled; that route’s nextpreviewor itssettledreplaces it.done: the final answer, always the last line. Execute only this one. A failed race carriesstatus(such as404) anderrorhere, because the HTTP status was already200.
done failed: request it again.
Call a contract after the swap
Setcall 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.
- Ask RAVN to register your contract and its function on your key, for each chain. Any other call
gets
400 INVALID_REQUEST. - Set
outputTokento the ERC-20 your contract takes, anddestinationAddressto your user’s EVM address. - Fill in
call:target: your contract on the output chain.data: the calldata, selector included.amountAt: the byte offset indata, selector included, where RAVN writes the amount as a uint256:4fordeposit(uint256 assets, address receiver). Leave it out only whendataalready holdsexactAmount.exactAmount: put exactly this much ofoutputTokeninto the call, in its smallest unit. Your user then sends only what that takes (input.amount). Without it, the call getsoutput.amount, what the swap ofinputAmountguarantees.leftoverTo: where anything the call doesn’t spend goes. Defaults todestinationAddress.
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.
