# POST /execute
Source: https://docs.ravn.exchange/api-reference/execute

Turn a quote into an actionable execution payload.

Takes the opaque `quoteToken` from [`/quote`](/api-reference/quote) and returns one of three
shapes tagged by `executionType`. See [Execution Types](/execution-types) for the branch logic.

## Request

<ParamField type="string">The opaque token from `/quote`.</ParamField>
<ParamField type="string">Recipient, if not supplied at quote time.</ParamField>
<ParamField type="string">Refund address, if not supplied at quote time.</ParamField>

```bash theme={null}
curl -s -X POST https://app.ravn.exchange/api/v1/execute \
  -H 'x-api-key: <your key>' \
  -H 'content-type: application/json' \
  -d '{ "quoteToken": "<from /quote>" }'
```

## Response

One of three payloads:

<CodeGroup>
  ```json TRANSACTION theme={null}
  { "executionType": "TRANSACTION",
    "transaction": { "to": "0x…", "data": "0x…", "value": "0", "chainId": 1 } }
  ```

  ```json SIGNATURE theme={null}
  { "executionType": "SIGNATURE",
    "typedData": { }, "approvalData": { },
    "submit": { "url": "/api/v1/submit-signature" } }
  ```

  ```json DEPOSIT theme={null}
  { "executionType": "DEPOSIT",
    "deposit": { "address": "0x…", "amount": "1000000000000000000", "chainId": 1 },
    "statusRef": "0x…" }
  ```
</CodeGroup>

<Warning>
  Returns `410 QUOTE_EXPIRED` if the quote has expired, or `400 QUOTE_INVALID` if the token is
  malformed or tampered with. Request a fresh quote and retry.
</Warning>


# GET /health
Source: https://docs.ravn.exchange/api-reference/health

Per-venue liveness.

Reports overall status plus each venue's health, so you can surface degraded routing. It always
returns `200`, so read the `status` field rather than the HTTP code to gate. This endpoint is
public and needs no key.

```bash theme={null}
curl -s https://app.ravn.exchange/api/v1/health
```

## Response

<ResponseField name="status" type="string">Either `ok` or `degraded`.</ResponseField>
<ResponseField name="venues" type="array">An array of `{ id, name, healthy }`, one per venue.</ResponseField>

```json theme={null}
{
  "data": {
    "status": "ok",
    "venues": [
      { "id": "cow", "name": "CoW Protocol", "healthy": true },
      { "id": "near_intents", "name": "NEAR Intents", "healthy": true }
    ]
  }
}
```


# Overview
Source: https://docs.ravn.exchange/api-reference/overview

The RAVN Integrator API surface.

Base URL: `https://app.ravn.exchange/api/v1`

<CardGroup>
  <Card title="POST /quote" href="/api-reference/quote">Best-priced route + an opaque quoteToken.</Card>
  <Card title="POST /execute" href="/api-reference/execute">Turn a quoteToken into an execution payload.</Card>
  <Card title="POST /submit-signature" href="/api-reference/submit-signature">Submit a signed order for SIGNATURE venues.</Card>
  <Card title="GET /status" href="/api-reference/status">Normalized swap status.</Card>
  <Card title="GET /tokens/resolve" href="/api-reference/tokens">Resolve any token address to metadata.</Card>
  <Card title="GET /health" href="/api-reference/health">Per-venue liveness.</Card>
</CardGroup>

## Conventions

* **Envelope:** `{ data, meta }` on success, `{ error: { code, message, details? }, meta }` on failure.
* **Headers:** every response carries `x-request-id` and `ravn-version`.
* **Amounts:** strings, in the token's smallest unit.
* **Native coin:** the sentinel `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` (Solana native SOL: mint `So1111…1112`).

## Chain IDs

| Chain       | ID  | Chain       | ID     |
| ----------- | --- | ----------- | ------ |
| Ethereum    | 1   | Base        | 8453   |
| Optimism    | 10  | Arbitrum    | 42161  |
| BNB Chain   | 56  | Linea       | 59144  |
| Unichain    | 130 | Avalanche   | 43114  |
| Polygon     | 137 | Robinhood   | 4663   |
| zkSync      | 324 | **Bitcoin** | **-1** |
| World Chain | 480 | **Solana**  | **-2** |
| HyperEVM    | 999 |             |        |


# POST /quote
Source: https://docs.ravn.exchange/api-reference/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 type="integer">Origin chain ID.</ParamField>
<ParamField type="integer">Destination chain ID.</ParamField>
<ParamField type="string">Contract address or mint, or the native sentinel.</ParamField>
<ParamField type="string">Contract address or mint, or the native sentinel.</ParamField>
<ParamField type="string">Positive integer in the token's smallest unit.</ParamField>
<ParamField type="string">The sender's address.</ParamField>
<ParamField type="string">Recipient on the destination chain. Required for cross-ecosystem swaps.</ParamField>
<ParamField type="string">Where refunds go on failure.</ParamField>
<ParamField type="integer">1 to 5000. Omit for the venue default.</ParamField>

```bash theme={null}
curl -s -X POST https://app.ravn.exchange/api/v1/quote \
  -H 'x-api-key: <your key>' \
  -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.</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, with `bps`, `amount`, and `token`.</ResponseField>
<ResponseField name="slippage" type="object">The `bps`, `isFirm`, and `guaranteedMin`, or null.</ResponseField>
<ResponseField name="gas" type="object">Native gas the user must hold, or null on gasless venues.</ResponseField>

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

<ResponseField name="expiresAt" type="integer">Epoch milliseconds when the quote expires.</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": 25, "amount": "47462", "token": { } },
    "estimatedTimeSeconds": 42,
    "expiresAt": 1750000000000
  }
}
```

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


# GET /status
Source: https://docs.ravn.exchange/api-reference/status

Normalized swap status.

Poll the progress of a swap. The `ref` is the `statusRef` returned by
[`/execute`](/api-reference/execute) for a DEPOSIT, or by
[`/submit-signature`](/api-reference/submit-signature) for a SIGNATURE.

## Request

<ParamField type="string">The opaque token from `/quote`.</ParamField>
<ParamField type="string">The `statusRef` for this swap.</ParamField>

```bash theme={null}
curl -s "https://app.ravn.exchange/api/v1/status?quoteToken=<token>&ref=<statusRef>" \
  -H 'x-api-key: <your key>'
```

## Response

<ResponseField name="status" type="string">The normalized lifecycle state.</ResponseField>
<ResponseField name="venue" type="string">The venue handling the swap.</ResponseField>
<ResponseField name="venueStatus" type="string">The raw, venue-native status string behind the normalized `status`, for debugging. Present once a venue has been polled.</ResponseField>
<ResponseField name="tracking" type="string">Present as `"unavailable"` only when the venue is not yet wired for tracking (`status` is `unknown`). Absent otherwise.</ResponseField>

| `status`     | Meaning                                                                              |
| ------------ | ------------------------------------------------------------------------------------ |
| `pending`    | Awaiting the deposit, or not yet observed                                            |
| `processing` | Funds received, solver filling                                                       |
| `success`    | Delivered                                                                            |
| `expired`    | The fill deadline passed without a fill; a refund is due but has not yet been issued |
| `refunded`   | Returned to sender                                                                   |
| `failed`     | Terminal failure                                                                     |
| `not_found`  | The `ref` is unknown to the venue                                                    |
| `unknown`    | The venue is not yet wired for tracking                                              |

```json theme={null}
{ "data": { "status": "processing", "venue": "near_intents" } }
```

<Note>
  Status tracking is live for NEAR Intents today, and more venues are being wired. The response
  shape is stable, and venues that are not yet tracked return a `status` of `unknown`.
</Note>

<Warning>
  **Keep polling on `expired`.** It is **not** a terminal state. It means the deal lapsed and a
  refund is owed but has not landed yet — on Across, the deposit is returned to the sender on the
  origin chain roughly 90 minutes later, at which point the status becomes `refunded`. Treat only
  `success`, `refunded`, and `failed` as terminal; stopping at `expired` will miss the refund.
</Warning>


# POST /submit-signature
Source: https://docs.ravn.exchange/api-reference/submit-signature

Submit a signed order for SIGNATURE venues.

Use this for `SIGNATURE`-type venues (0x Gasless, Bebop, CoW). Sign the `typedData` from
[`/execute`](/api-reference/execute), then post the signature here. RAVN routes it to the
correct venue, so you never touch per-venue endpoints.

## Request

<ParamField type="string">The same opaque token from `/quote`.</ParamField>
<ParamField type="string">Your 65-byte hex signature over `typedData`.</ParamField>
<ParamField type="string">A signature over `approvalData`, when `/execute` returned it (0x Gasless).</ParamField>

```bash theme={null}
curl -s -X POST https://app.ravn.exchange/api/v1/submit-signature \
  -H 'x-api-key: <your key>' \
  -H 'content-type: application/json' \
  -d '{ "quoteToken": "<token>", "signature": "0x..." }'
```

## Response

<ResponseField name="statusRef" type="string">The handle to poll [`/status`](/api-reference/status) with.</ResponseField>
<ResponseField name="venue" type="string">The venue the order was submitted to.</ResponseField>

```json theme={null}
{ "data": { "statusRef": "0x...orderUid", "venue": "cow" } }
```


# GET /tokens/resolve
Source: https://docs.ravn.exchange/api-reference/tokens

Resolve any token address to metadata.

Resolve an arbitrary token address to its metadata (symbol, name, decimals) via an on-chain
read. Lets you support paste-any-address flows.

## Request

<ParamField type="integer">The chain to resolve on.</ParamField>
<ParamField type="string">The token contract address / mint.</ParamField>

```bash theme={null}
curl -s "https://app.ravn.exchange/api/v1/tokens/resolve?chainId=1&address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" \
  -H 'x-api-key: <your key>'
```

## Response

```json theme={null}
{
  "data": {
    "token": {
      "symbol": "USDC",
      "name": "USD Coin",
      "address": "0xA0b8…eB48",
      "decimals": 6,
      "chainId": 1,
      "isNative": false
    }
  }
}
```

Returns `400 UNSUPPORTED_TOKEN` if the address isn't a valid token on that chain.


# Authentication
Source: https://docs.ravn.exchange/authentication

API keys, fees, and rate limits.

<Note>
  The API requires a key from your very first call — including during beta. Keys are issued by
  RAVN so we can attribute usage to each partner. See [Requesting access](#requesting-access)
  below to get one before you start testing.
</Note>

Authenticate every request with your API key in the `x-api-key` header:

```
x-api-key: rvn_live_your_key_here
```

* Keys are issued by RAVN. Each key carries your fee rate and your rate limit in requests per
  minute.
* A missing or invalid key returns `401 UNAUTHORIZED`. Exceeding your limit returns
  `429 RATE_LIMITED`, with a `retryAfterSec` value in `details`.
* `GET /health` is always public. All other endpoints require a key once auth is enabled.

## Requesting access

To request a key or a custom fee arrangement, DM [@ravnexchange](https://x.com/ravnexchange)
on X or reach out via [ravn.exchange](https://ravn.exchange). We issue your key manually and
send it back directly — include a word on what you're building so we can set your rate and
rate limit. Enterprise partners can negotiate a flat per-partner rate that overrides the
default route-based pricing.


# Errors
Source: https://docs.ravn.exchange/errors

Predictable, machine-readable error codes.

Failures return `{ error: { code, message, details? }, meta }`. Branch on the stable `code`,
because the human-readable `message` may change.

| Code                | HTTP | Meaning                                                                     |
| ------------------- | ---- | --------------------------------------------------------------------------- |
| `INVALID_REQUEST`   | 400  | The body or params failed validation. The `details` field lists the fields. |
| `UNSUPPORTED_TOKEN` | 400  | The token is not resolvable on that chain.                                  |
| `NO_LIQUIDITY`      | 404  | No venue could quote this pair or amount.                                   |
| `QUOTE_EXPIRED`     | 410  | The `quoteToken` is past expiry. Request a new quote.                       |
| `QUOTE_INVALID`     | 400  | The `quoteToken` is malformed or tampered.                                  |
| `RATE_LIMITED`      | 429  | The per-key rate limit was exceeded.                                        |
| `UNAUTHORIZED`      | 401  | The API key is missing or invalid.                                          |
| `INTERNAL`          | 500  | An unexpected or venue-side error occurred.                                 |

```json theme={null}
{
  "error": {
    "code": "NO_LIQUIDITY",
    "message": "No liquidity available for this pair/amount"
  },
  "meta": { "requestId": "6b50...19e", "version": "2024-01" }
}
```

<Tip>
  Always log the `requestId` from `meta`, which is also in the `x-request-id` header. Include it
  when you contact support and we can trace the exact request.
</Tip>


# Execution Types
Source: https://docs.ravn.exchange/execution-types

The one field your integration branches on.

RAVN spans three settlement models. `POST /execute` returns exactly one of them, tagged by
`executionType`. Your integration reads that single field and branches. Nothing else about the
flow changes.

<CardGroup>
  <Card title="TRANSACTION" icon="signature">
    Sign and broadcast the returned transaction.
    <br />**Across, Relay, Mayan, Jupiter**
  </Card>

  <Card title="SIGNATURE" icon="pen-nib">
    Sign typed data, with no gas and no send. RAVN submits it.
    <br />**0x Gasless, Bebop, CoW**
  </Card>

  <Card title="DEPOSIT" icon="paper-plane">
    Send the origin asset to an address.
    <br />**NEAR Intents, Rift (BTC)**
  </Card>
</CardGroup>

## The payloads

<CodeGroup>
  ```json TRANSACTION theme={null}
  {
    "executionType": "TRANSACTION",
    "transaction": { "to": "0x...", "data": "0x...", "value": "0", "chainId": 1 }
  }
  ```

  ```json SIGNATURE theme={null}
  {
    "executionType": "SIGNATURE",
    "typedData": { },
    "approvalData": { },
    "submit": { "url": "/api/v1/submit-signature" }
  }
  ```

  ```json DEPOSIT theme={null}
  {
    "executionType": "DEPOSIT",
    "deposit": { "address": "0x...", "amount": "1000000000000000000", "chainId": 1 },
    "statusRef": "0x..."
  }
  ```
</CodeGroup>

## Branch logic

```js theme={null}
switch (res.data.executionType) {
  case "TRANSACTION": await wallet.sendTransaction(res.data.transaction); break;
  case "SIGNATURE":   { const sig = await wallet.signTypedData(res.data.typedData);
                        await submitSignature(quoteToken, sig); } break;
  case "DEPOSIT":     await wallet.send(res.data.deposit.address, res.data.deposit.amount); break;
}
```

<Tip>
  A `DEPOSIT` can be fulfilled automatically, by building a wallet transfer to the address as an
  EVM or Solana wallet does, or manually, by showing the address and a QR code as a native-BTC
  send does. Both are the same execution type, so you choose the UX.
</Tip>


# FAQ
Source: https://docs.ravn.exchange/faq

Common questions about the RAVN Integrator API.

<AccordionGroup>
  <Accordion title="Does RAVN use bridges?">
    No. RAVN routes only through RFQ market makers, intent networks, and solver and relayer
    networks that settle in the canonical asset. There is never a lock-and-mint bridge, wrapped
    token, or synthetic.
  </Accordion>

  <Accordion title="Is RAVN custodial?">
    No. The user signs or sends directly to the venue, and RAVN never holds funds. See the
    [Security Model](/security).
  </Accordion>

  <Accordion title="Do I need an API key to start?">
    Yes — a key is required from your first call, including during beta. Keys are issued by RAVN
    and carry your per-partner fee and rate limit. Request one by DMing
    [@ravnexchange](https://x.com/ravnexchange) on X or via [ravn.exchange](https://ravn.exchange).
    See [Authentication](/authentication).
  </Accordion>

  <Accordion title="How do fees work?">
    A small integrator fee scales with the route. It is 0 bps on commodity same-chain swaps and
    a premium on cross-chain, cross-ecosystem, and native-BTC routes. It is shown transparently
    in every quote and is invisible to your end users. See [Pricing](/pricing).
  </Accordion>

  <Accordion title="What is a quoteToken?">
    An opaque, signed handle returned by `/quote`. Pass it back to `/execute` verbatim, and
    never parse it. It is tamper-evident and it expires.
  </Accordion>

  <Accordion title="How do I handle the different execution types?">
    Branch on the `executionType` field from `/execute`. The values are `TRANSACTION` (sign and
    broadcast), `SIGNATURE` (sign typed data, then RAVN submits it), and `DEPOSIT` (send the
    origin asset to an address). That single field is the whole client contract. See
    [Execution Types](/execution-types).
  </Accordion>

  <Accordion title="Can users swap without holding gas?">
    Yes. On RFQ and gasless venues, the user signs an off-chain message and a solver covers gas.
    They only need the asset they are selling.
  </Accordion>

  <Accordion title="Which chains and assets are supported?">
    EVM chains, Solana, and native Bitcoin. See
    [Supported Chains & Venues](/supported). The `/health` endpoint reports the live venue set.
  </Accordion>

  <Accordion title="How do I track a swap to completion?">
    Poll [`GET /status`](/api-reference/status) with the `statusRef` from `/execute` or
    `/submit-signature`. It returns a normalized lifecycle of `pending`, `processing`, then
    `success`. Stop only on a terminal state — `success`, `refunded`, or `failed`. A lapsed deal
    reports `expired` first (a refund is owed but not yet issued), so keep polling until it
    becomes `refunded`.
  </Accordion>

  <Accordion title="Something failed. How do I get help?">
    Every response includes a `requestId`, which is also in the `x-request-id` header. Include it
    when you reach out via [ravn.exchange](https://ravn.exchange), and we can trace the exact
    request.
  </Accordion>
</AccordionGroup>


# How It Works
Source: https://docs.ravn.exchange/how-it-works

One quote across every venue, delivered as the canonical asset, with no bridges.

RAVN is a **cross-chain execution layer**. You send one request, RAVN finds the best route
across every connected venue, and it returns exactly what your user needs to sign or send. The
user always receives the **canonical asset** on the destination. There is never a wrapped or
synthetic token, and never a lock-and-mint bridge.

## The flow

<Steps>
  <Step title="Smart order routing">
    On every quote, RAVN queries all eligible venues in parallel (RFQ market makers, intent
    networks, and cross-chain solvers) and picks the best real output for the pair, amount, and
    route.
  </Step>

  <Step title="One normalized response">
    The winning quote comes back in a single shape, with an opaque `quoteToken`. You never deal
    with per-venue formats.
  </Step>

  <Step title="One field to act on">
    Execution resolves to one of three values of `executionType`: `TRANSACTION`, `SIGNATURE`, or
    `DEPOSIT`. Your integration branches on that one field. See
    [Execution Types](/execution-types).
  </Step>

  <Step title="Non-custodial settlement">
    The user signs or sends directly to the venue. RAVN never takes custody of funds. Solvers
    fill and deliver the canonical asset on the destination chain.
  </Step>
</Steps>

## Why there are no bridges

Traditional cross-chain routes lock your asset on one chain and mint a wrapped copy on another,
which introduces custody, wrapping, and synthetic-asset risk. RAVN routes only through RFQ
market makers, intent networks, and solver and relayer networks that settle in the canonical
asset. That is what lets RAVN promise no bridges, no wrapping, no synthetics, and no custodians,
and it is why "bridge" never appears in a RAVN route.

## What you integrate once

<CardGroup>
  <Card title="Every chain" icon="link">EVM, Solana, and native Bitcoin through one API.</Card>
  <Card title="Every venue type" icon="layer-group">RFQ, intents, and solvers behind one contract.</Card>
  <Card title="Every execution model" icon="code-branch">Three execution types, one branch.</Card>
  <Card title="Best price" icon="trophy">Parallel routing picks the best real output.</Card>
</CardGroup>


# RAVN Integrator API
Source: https://docs.ravn.exchange/introduction

One integration to swap any asset across any chain. EVM, Solana, and native Bitcoin.

RAVN aggregates RFQ market makers, intent networks, and cross-chain solvers behind a single,
uniform interface. You can quote, execute, and track a swap across EVM, Solana, and **native
Bitcoin**, without ever touching a bridge, a wrapped asset, or a synthetic.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Swap 1 ETH to SOL end to end in four calls.
  </Card>

  <Card title="Execution types" icon="code-branch" href="/execution-types">
    The one field your integration branches on.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/overview">
    Every endpoint, request, and response.
  </Card>

  <Card title="Pricing" icon="tag" href="/pricing">
    Route-based fees, fully transparent.
  </Card>
</CardGroup>

## Base URL

```
https://app.ravn.exchange/api/v1
```

* **Content type:** `application/json`
* **Amounts:** always strings, in the token's smallest unit (wei, lamports, satoshis).
* **Native coin:** use the sentinel `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. For Solana native SOL, use its mint `So1111...1112`.

<Note>
  RAVN is in beta. An API key is required from your first call — keys are issued by RAVN, so we
  can attribute usage to each partner. Request one by DMing
  [@ravnexchange](https://x.com/ravnexchange) on X or via [ravn.exchange](https://ravn.exchange).
  Fees are shown transparently in every quote and are invisible to your end users.
</Note>

## Why it is different

Most swap APIs do one thing, an EVM transaction, so their whole surface assumes it. RAVN spans
three genuinely different settlement worlds, and every quote resolves to exactly one
`executionType`. Your integration reads that one field and branches. That is the whole contract.

| Model         | What the user does                          | Venues                        |
| ------------- | ------------------------------------------- | ----------------------------- |
| `TRANSACTION` | Sign and broadcast                          | Across, Relay, Mayan, Jupiter |
| `SIGNATURE`   | Sign typed data (no gas), then RAVN submits | 0x Gasless, Bebop, CoW        |
| `DEPOSIT`     | Send the origin asset to an address         | NEAR Intents, Rift (BTC)      |

## The response envelope

Every response has the same shape.

<CodeGroup>
  ```json Success theme={null}
  { "data": { }, "meta": { "requestId": "uuid", "version": "2024-01" } }
  ```

  ```json Failure theme={null}
  { "error": { "code": "NO_LIQUIDITY", "message": "..." },
    "meta": { "requestId": "uuid", "version": "2024-01" } }
  ```
</CodeGroup>

Every response also carries `x-request-id` and `ravn-version` headers. Log the `requestId` and
quote it when you contact support.


# Pricing
Source: https://docs.ravn.exchange/pricing

Route-based fees, fully transparent.

RAVN charges a small integrator fee that scales with the value of the route. It is free where
you would compete on price with zero-fee aggregators, and it applies a premium only where RAVN
is the best or only option. The fee is shown in every quote through the `fee.bps` and
`fee.amount` fields, and it is invisible to your end users.

| Route                              | Fee        |
| ---------------------------------- | ---------- |
| EVM same-chain (ERC-20 and native) | **0 bps**  |
| Solana to Solana                   | **0 bps**  |
| EVM cross-chain                    | **15 bps** |
| Cross-ecosystem (EVM and Solana)   | **25 bps** |
| Native BTC                         | **30 bps** |

## How it is reported

Every quote includes a `fee` object:

```json theme={null}
"fee": { "bps": 25, "amount": "3827250", "token": { "symbol": "USDC" } }
```

* `bps` is the fee applied to this quote, in basis points.
* `amount` is the fee in the output token's smallest unit.
* The figure is always the real, effective fee. It is 0 on free routes and never aspirational.

<Note>
  Enterprise partners can arrange a flat per-partner rate that overrides route-based pricing.
  Direct RAVN users on the consumer app always pay zero. The integrator fee applies only to the
  API.
</Note>


# Quickstart
Source: https://docs.ravn.exchange/quickstart

Swap 1 ETH to SOL end to end.

Four calls, always in the same order: quote, execute, complete, then status.

<Steps>
  <Step title="Get a quote">
    Price the swap. You get back the best route across every venue plus an opaque `quoteToken`.

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

  <Step title="Execute">
    Hand the `quoteToken` back. RAVN returns how to complete the swap, tagged by `executionType`.

    ```bash theme={null}
    curl -s -X POST https://app.ravn.exchange/api/v1/execute \
      -H 'x-api-key: <your key>' \
      -H 'content-type: application/json' \
      -d '{ "quoteToken": "<from step 1>" }'
    # returns { "executionType": "DEPOSIT", "deposit": { "address": "...", "amount": "..." }, "statusRef": "..." }
    ```
  </Step>

  <Step title="Complete it">
    Branch on `executionType`. This is the entire client-side contract.

    ```js theme={null}
    switch (res.data.executionType) {
      case "TRANSACTION": await wallet.sendTransaction(res.data.transaction); break;
      case "SIGNATURE":   { const sig = await wallet.signTypedData(res.data.typedData);
                            await submitSignature(quoteToken, sig); } break;
      case "DEPOSIT":     await wallet.send(res.data.deposit.address, res.data.deposit.amount); break;
    }
    ```
  </Step>

  <Step title="Track it">
    Poll `status` with the `statusRef` from `execute`, or the `statusRef` from `submit-signature`.

    ```bash theme={null}
    curl -s "https://app.ravn.exchange/api/v1/status?quoteToken=<token>&ref=<statusRef>" \
      -H 'x-api-key: <your key>'
    # returns { "status": "pending" | "processing" | "success" | "expired" | "refunded" | "failed" }
    # terminal: success, refunded, failed. Keep polling on expired — a refund is still due.
    ```
  </Step>
</Steps>

<Note>
  Amounts are strings in the token's smallest unit. Native coin uses the sentinel
  `0xEeee...EEeE`. The `quoteToken` is opaque, so never parse it. It expires, so re-quote if it
  goes stale.
</Note>


# Security Model
Source: https://docs.ravn.exchange/security

Non-custodial by design, with no bridges, no wrapping, and no synthetics.

RAVN is an **orchestration layer, not a custodian**. It finds routes and normalizes execution.
It never holds, wraps, or mints user funds.

## Non-custodial

* The user signs or sends directly to the venue. RAVN never takes custody of funds at any point
  in a swap.
* For `DEPOSIT` routes, the user sends the origin asset to a venue-generated address. For
  `SIGNATURE` and `TRANSACTION` routes, the user signs or broadcasts directly.

## No bridges, no wrapping, no synthetics

RAVN routes only through venues that settle in the canonical asset, which are RFQ market makers,
intent networks, and solver and relayer networks. There is no lock-and-mint bridge, no wrapped
token, and no synthetic anywhere in a RAVN route.

## Quote integrity

* Quotes are returned as an opaque, signed `quoteToken`. It is tamper-evident, so any
  modification of the amount, fee, or route invalidates it, and execution rejects it with
  `QUOTE_INVALID`.
* Quotes expire, and execution re-validates the expiry before building the transaction.

## Venue-enforced settlement

Each venue independently validates the economics and signatures of the order it settles. RAVN
never asks a user to sign anything the destination venue will not verify on its own.

## Gasless where it counts

On RFQ and gasless venues, the user needs zero native gas. They sign an off-chain message and a
solver covers execution. The user only ever needs the asset they are selling.

<Note>
  Reliability signal: [`GET /health`](/api-reference/health) reports live per-venue status, so
  integrators can surface degraded routing in real time.
</Note>


# Supported Chains & Venues
Source: https://docs.ravn.exchange/supported

Every chain RAVN swaps across, and the venues it routes through.

## Chains

RAVN spans EVM chains, Solana, and **native Bitcoin**. One integration covers all of them. Use
the chain ID in every request.

### EVM

| Chain       | ID    | Chain     | ID      |
| ----------- | ----- | --------- | ------- |
| Ethereum    | `1`   | Base      | `8453`  |
| Optimism    | `10`  | Arbitrum  | `42161` |
| BNB Chain   | `56`  | Linea     | `59144` |
| Unichain    | `130` | Avalanche | `43114` |
| Polygon     | `137` | Robinhood | `4663`  |
| zkSync Era  | `324` | HyperEVM  | `999`   |
| World Chain | `480` |           |         |

### Non-EVM

| Chain       | ID   | Notes                                                            |
| ----------- | ---- | ---------------------------------------------------------------- |
| **Solana**  | `-2` | SPL and native SOL. Use the mint `So1111...1112` for native SOL. |
| **Bitcoin** | `-1` | Native BTC, with no wrapping and no cbBTC intermediary required. |

<Note>
  Native coin on any EVM chain uses the sentinel address
  `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. Amounts are always strings in the token's smallest
  unit (wei, lamports, satoshis).
</Note>

Not every venue serves every chain. The router automatically selects venues that can serve a
given route, and it returns `NO_LIQUIDITY` if none can.

## Venues

RAVN aggregates nine venues across three settlement models. On every quote, the eligible venues
are queried in parallel and the best real output wins. Each venue maps to one
[execution type](/execution-types).

| Venue             | Type                       | Execution     | Serves                               |
| ----------------- | -------------------------- | ------------- | ------------------------------------ |
| **0x Gasless**    | RFQ market maker           | `SIGNATURE`   | EVM same-chain                       |
| **Bebop**         | RFQ market maker           | `SIGNATURE`   | EVM same-chain                       |
| **CoW Protocol**  | Batch auction and RFQ      | `SIGNATURE`   | EVM same-chain                       |
| **Jupiter Ultra** | On-chain aggregation       | `TRANSACTION` | Solana                               |
| **Across**        | Intent and solver network  | `TRANSACTION` | EVM cross-chain, cross-ecosystem     |
| **Relay**         | Relayer network            | `TRANSACTION` | EVM and Solana, same and cross-chain |
| **Mayan**         | Intent and auction (Swift) | `TRANSACTION` | Cross-chain, cross-ecosystem         |
| **NEAR Intents**  | Intent network (1Click)    | `DEPOSIT`     | Any to any                           |
| **Rift**          | Native BTC orchestration   | `DEPOSIT`     | Native Bitcoin                       |

<Note>
  All venues settle in the **canonical asset**. None of them wrap, mint synthetics, or bridge.
  RFQ and gasless venues let the user swap with zero native gas, because they sign an off-chain
  message and a solver covers the gas.
</Note>

### Settlement models

<CardGroup>
  <Card title="RFQ market makers" icon="handshake">
    Professional market makers quote a firm, signed price. The user signs and a solver settles.
    Zero slippage, zero gas.
  </Card>

  <Card title="Intent networks" icon="wand-magic-sparkles">
    The user expresses an intent, or deposits the origin asset, and solvers compete to fill and
    deliver on the destination.
  </Card>

  <Card title="Solver and relayer networks" icon="bolt">
    Relayers fill on the destination chain and deliver the canonical asset. This gives fast
    cross-chain execution without bridging.
  </Card>
</CardGroup>

Coverage grows over time. The [`/health`](/api-reference/health) endpoint always reports the
current live venue set.


# Use Cases
Source: https://docs.ravn.exchange/use-cases

What teams build on RAVN.

One integration turns any app into a cross-chain swap surface, including the routes most
aggregators cannot do, such as native Bitcoin and cross-ecosystem swaps.

<CardGroup>
  <Card title="Wallet swap widgets" icon="wallet">
    Let wallet users swap any asset to any chain in-app across EVM, Solana, and native BTC,
    without leaving the wallet. Gasless on RFQ routes.
  </Card>

  <Card title="DAO and treasury tools" icon="building-columns">
    Rebalance a multi-chain treasury (for example ETH to BTC, or stables across chains) in one
    call, non-custodially, with the canonical asset delivered.
  </Card>

  <Card title="DeFi dashboards" icon="chart-line">
    Add a swap action to a portfolio tracker so users act on positions without leaving the
    dashboard.
  </Card>

  <Card title="Trading bots and agents" icon="robot">
    Run programmatic cross-chain execution with a normalized quote, execute, and status loop,
    plus firm RFQ pricing.
  </Card>

  <Card title="BTC-native apps" icon="bitcoin-sign">
    Move value in and out of native Bitcoin without cbBTC, wrapping, or a bridge. This is a
    route most aggregators cannot offer at all.
  </Card>

  <Card title="Payments and ramps" icon="arrow-right-arrow-left">
    Settle a user's asset into the exact token and chain a downstream flow expects, in one hop.
  </Card>
</CardGroup>

<Note>
  Every route is non-custodial and settles in the canonical asset. Your users never touch a
  bridge, a wrapped token, or a synthetic.
</Note>