Get a cross-chain swap quote (pay-per-call)
Request
- Base URL: https://app.ravn.exchange
- URL: https://app.ravn.exchange/api/v1/x402/quote
- Auth: none declared
Request body
Token contract address, or the native-token sentinel 0xEeee...EEeE
Positive integer string, in the input token's smallest unit
Where output should land. Required at quote time for a real (executable) quote from Relay (Bitcoin as source or dest), THORChain (Bitcoin either direction), Across (Solana-touching), Eco (cross-ecosystem), or compose (RAVN two-hop routes). Omit it there and you get a preview (QuoteDTO.executable=false). Validated here, not only at execute: a malformed address, an address from the wrong ecosystem for the output chain, or a known non-wallet address (any RAVN-listed token's mint/contract, this swap's own tokens, the native-coin sentinel, burn addresses, Solana core programs — funds sent there are unrecoverable) is rejected with INVALID_REQUEST. A Solana address is also looked up on chain: a token account (the message names the wallet that owns it) or a program is rejected; this lookup fails open, so an RPC outage never blocks a quote. An empty string means not supplied.
Where to refund the input asset 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); with any other userAddress, supply it. Well-known sample addresses (e.g. bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh) count as no address: supply the real refund. For a Bitcoin-source Relay or THORChain quote, the refund must be known here, at quote time — neither has an execute-time re-bind, so without one it returns a priced-but-unexecutable preview and supplying it later on execute is refused. Other BTC-source venues (Garden, Chainflip, Rift, NEAR Intents) support binding this at execute time instead. Validated against the INPUT chain (refunds are paid back on the origin), including the token's-own-address check described on destinationAddress.
Max slippage in basis points. Omitted means Auto: 50, wider where a route needs it (slippage.bps reports the figure used). Setting it drops venues that enforce no minimum (slippage.noMinimum: true, today Rift) from the race, since your figure is a protection they can't give — unless allowNoMinimum is true.
Let venues that enforce no minimum (today Rift) race even though slippageBps is set. Such a quote fills at the venue's own rate once the deposit lands: it carries slippage.noMinimum: true, slippage.guaranteedMin null, and your slippageBps does not protect it. Without slippageBps they already race. Defaults to false.
Defaults to best_output.
Drop specific venues — e.g. a risk objection to one of them. An excluded venue is used nowhere in the route, including the steps of RAVN's own multi-step routes (venue.id "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). Naming a venue that was never eligible for this pair is a no-op, not an error.
Race only these venues — e.g. ["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 — e.g. ["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). Same-chain venues (Bebop, 0x, Kyber, OKX…) only quote same-chain pairs; when none of the named venues can quote, you get NO_LIQUIDITY with every left-out venue in excludedVenues. An empty list is rejected rather than read as no restriction.
Settle privately: the on-chain deposit and payout cannot be linked to each other. The race narrows to the private venues — NEAR Intents' Confidential Intents and Houdini Swap's two-hop exchange route — and the best output wins; you get NO_LIQUIDITY rather than a public fill if neither can quote. Measured cost: NEAR ~0.3 bps more on EVM-to-EVM and ~5-8 bps more when Bitcoin or Solana is a leg; Houdini ~3% below spot on its fixed-rate quote, which is not a guaranteed minimum (so it wins only where NEAR can't quote). Both can settle slower than a public swap (NEAR Bitcoin-source 43 min; Houdini a few minutes to about an hour), so read estimatedTimeSeconds before executing. A Houdini quote is valid until expiresAt (Houdini holds each price for 60 seconds from when RAVN fetched it). Neither venue takes your integrator fee itself: from an EVM chain or Solana (and NEAR from Bitcoin) RAVN collects it beside the deposit (the execution's fee) — from Solana as a transfer to RAVN inside the same transaction that pays the deposit. Houdini is sent your request's IP and user-agent (plus clientTimezone) for its compliance screening, and its terms bar US persons and sanctioned jurisdictions: Houdini is left out of the race when this request arrives from such a country, and you are responsible for your end users' eligibility — pass excludeVenues: ["houdini"] where that cannot be met. Confidentiality is the venue's, not RAVN's, and remains subject to its screening.
Your end user's IANA timezone (e.g. Europe/Berlin), forwarded only to venues whose API requires the user's details on every call (Houdini). Defaults to UTC.
Test the full quote -> execute -> status flow with no real funds and no live venue settlement. The quote itself is still priced live. On /v1/execute nothing is opened at a venue: where building would open an order, a deposit address or channel, or spend real money (NEAR Intents, Rift, Garden, Layerswap, Houdini Swap, Chainflip, RAVN two-hop routes, THORChain from Bitcoin) you get a stand-in DEPOSIT of the input to your user's own wallet (the refund address, else userAddress; selling Bitcoin needs one of them to be a Bitcoin address), even where the live route is a transaction; every other venue returns its real payload, built live: a transaction or typed data that swaps for real if you send it or submit it to the venue yourself, and Relay from Bitcoin the live deposit address it opened when it quoted. Every sandbox execution carries sandbox: true: never send it. /v1/submit-signature and /v1/submit-transaction skip the real submission. /v1/status always reports an immediate synthetic success. Sandbox swaps are never metered or billed.
The race's time limit in milliseconds, counted from when it starts. Once it has passed and some venue has priced the swap, venues still silent are left out (they aren't in alternatives) and the best of the rest is returned. If none has priced by then, the race waits for the first price (up to each venue's own limit, 10 s for most) and then leaves out the rest. A quote with slippage.noMinimum counts as a price only 2000 ms past the limit, so venues that hold a minimum get that long to answer. Defaults to 6000, the limit RAVN's app uses; a positive integer, clamped to 1000–15000. RAVN's own route gets 2000 more on pairs where its cross-chain WBTC plan races. Lower it to answer sooner, raise it to wait for slower venues.
Response
Quote produced
Changes
No recorded changes to this operation across all 1 revision of this API.