> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /quote

> Get the best-priced route for a swap.

Shops every eligible venue and returns the best price plus an opaque `quoteToken` to pass to
[`/execute`](/api-reference/execute).

## Request

<ParamField body="inputChainId" type="integer" required>Origin chain ID.</ParamField>
<ParamField body="outputChainId" type="integer" required>Destination chain ID.</ParamField>
<ParamField body="inputToken" type="string" required>Contract address or mint, or the native sentinel.</ParamField>
<ParamField body="outputToken" type="string" required>Contract address or mint, or the native sentinel.</ParamField>
<ParamField body="inputAmount" type="string" required>Positive integer in the token's smallest unit.</ParamField>
<ParamField body="userAddress" type="string" required>The sender's address.</ParamField>
<ParamField body="destinationAddress" type="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`. Supply the real address here whenever you have it.</ParamField>
<ParamField body="refundAddress" type="string">Where the input asset is refunded if the swap fails. A Bitcoin-source Relay or THORChain quote both require this here, at quote time, for the same reason as `destinationAddress` above. Chainflip and Rift accept it as a late addition on `/execute` instead.</ParamField>
<ParamField body="slippageBps" type="integer">1 to 5000. Quotes that would slip more than this are dropped. 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.</ParamField>
<ParamField body="rankingMode" type="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.</ParamField>
<ParamField body="excludeVenues" type="string[]">Venue IDs to drop from this race entirely, for example if `/health` shows one degraded or you have a standing risk objection to it. See [Supported Chains & Venues](/supported) for the ID of each venue.</ParamField>
<ParamField body="confidential" type="boolean">Settle privately, so the on-chain deposit and payout can't be linked. The race narrows to NEAR Intents (Confidential Intents) and Houdini Swap, best output wins, and you get `404 NO_LIQUIDITY` rather than a public fill if neither 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. Read `estimatedTimeSeconds` before executing. 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. See [Private swaps](/supported#private-swaps).</ParamField>
<ParamField body="clientTimezone" type="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`.</ParamField>
<ParamField body="sandbox" type="boolean">Test `/execute`, `/submit-signature`, 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](/sandbox-mode).</ParamField>

No API key required (see [Authentication](/authentication) for the optional higher-limit tiers).

```bash theme={null}
curl -s -X POST https://app.ravn.exchange/api/v1/quote \
  -H 'content-type: application/json' -d '{
    "inputChainId": -2, "outputChainId": 1,
    "inputToken": "So11111111111111111111111111111111111111112",
    "outputToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "inputAmount": "100000000000",
    "userAddress": "SoYourUser",
    "destinationAddress": "0xYourUser"
  }'
```

## Response

<ResponseField name="quoteToken" type="string">Opaque handle. Pass it to `/execute` verbatim and do not parse it. It expires.</ResponseField>
<ResponseField name="venue" type="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.</ResponseField>
<ResponseField name="routeType" type="string">For example, `CROSS_ECOSYSTEM` or `EVM_CROSS_CHAIN`.</ResponseField>
<ResponseField name="input" type="object">The input `token` and `amount`.</ResponseField>
<ResponseField name="output" type="object">The output `token` and expected `amount`.</ResponseField>

<ResponseField name="fee" type="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
  deduct the fee from the input token. `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 this venue has no fee
  mechanism at all (Eco Routes, Houdini Swap, Layerswap, Rift), regardless of what fee your key has set. See
  [Pricing](/pricing#the-fee-object-on-every-quote) for the full breakdown.
</ResponseField>

<ResponseField name="executable" type="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`. Request a fresh quote with the missing address instead of retrying `/execute`.</ResponseField>

<ResponseField name="slippage" type="object">
  The `bps`, `isFirm`, `guaranteedMin`, and `noMinimum`, 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.
</ResponseField>

<ResponseField name="gas" type="object">Native gas the user must hold: `native`, `nativeSymbol`, `usd`, and `estimated`. Null on gasless venues.</ResponseField>
<ResponseField name="inputUsd" type="string">USD value of the input amount, same price source as `gas.usd`. Null when the token can't be priced.</ResponseField>
<ResponseField name="outputUsd" type="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.</ResponseField>

<ResponseField name="estimatedTimeSeconds" type="integer" />

<ResponseField name="estimatedTimeIsGuess" type="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.</ResponseField>
<ResponseField name="expiresAt" type="integer">Epoch milliseconds when the quote expires.</ResponseField>
<ResponseField name="hops" type="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.</ResponseField>
<ResponseField name="alternatives" type="array">Every other venue that raced and produced a usable quote, best output first, 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 `fee` with the same `bps`, `amount`, `token`, and `supported` fields as above (`amount` is in `fee.token`'s smallest unit: the output token, except on Fly Trade and Mayan, which take it from the input token); its own `slippage`, same shape as above or null, so check `noMinimum` on an alternative too; and an optional `hops`, as above. Empty when no other venue could serve this pair.</ResponseField>

```json theme={null}
{
  "data": {
    "quoteToken": "...opaque...",
    "venue": { "id": "near_intents", "name": "NEAR Intents" },
    "routeType": "CROSS_ECOSYSTEM",
    "input":  { "token": { }, "amount": "100000000000" },
    "output": { "token": { }, "amount": "18985000" },
    "fee":    { "bps": 20, "amount": "37970", "token": { }, "supported": true },
    "executable": true,
    "slippage": { "bps": 50, "isFirm": false, "guaranteedMin": "18890075", "noMinimum": false },
    "inputUsd": "203.41",
    "outputUsd": "202.98",
    "estimatedTimeSeconds": 42,
    "estimatedTimeIsGuess": false,
    "expiresAt": 1750000000000,
    "alternatives": [
      {
        "venue": { "id": "relay", "name": "Relay" },
        "routeType": "CROSS_ECOSYSTEM",
        "quoteToken": "...opaque...",
        "outputAmount": "18930000",
        "fee": { "bps": 20, "amount": "37860", "token": { }, "supported": true },
        "executable": true,
        "estimatedTimeSeconds": 15,
        "estimatedTimeIsGuess": false,
        "slippage": { "bps": 50, "isFirm": false, "guaranteedMin": "18835350", "noMinimum": false }
      }
    ]
  }
}
```

Returns `404 NO_LIQUIDITY` when no venue can serve the pair or amount.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.