> ## 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.

# x402 Payments

> Pay-per-call access to RAVN's quote and execute endpoints, no API key, no signup, priced in USDC.

RAVN's quote and execute endpoints are also available over
[x402](https://www.x402.org): pay a small amount of USDC per request instead of managing an
API key. This is a second, parallel door into the same swap logic as the
[free REST API](/api-reference/overview); it doesn't replace the free tier, which still requires no
payment at all.

If you're building on Claude, Cursor, or another MCP client, the [MCP server](/ai-agents/mcp-server)
is free and simpler; there's no reason to pay for the same tool call. x402 is for agents that
can't or don't want to hold a long-lived credential at all:

* **No key to provision, rotate, or leak.** Nothing to store server-side; a compromised agent
  process has no standing secret to revoke.
* **Spend is capped per call, not per key.** Each payment authorizes exactly one request for
  exactly the price quoted; there's no API key that, once leaked, keeps working until someone
  notices and rotates it.
* **The payment itself is the audit trail.** Every call settles on-chain (Base or Solana), so
  usage is independently verifiable without RAVN-side logging or an API dashboard.
* **Discoverable by other agents, not just yours.** RAVN's x402 routes are indexed in Coinbase's
  x402 Bazaar catalog (the search and merchant-lookup API behind [agentic.market](https://agentic.market))
  and listed on [x402scan.com](https://x402scan.com), so agents that discover services by
  querying that catalog directly can find and call RAVN without being told about it in advance.
  Whether RAVN also appears in agentic.market's own curated marketplace UI is a separate,
  usage-driven decision on their end, not something indexing alone guarantees. The free REST/MCP
  doors aren't part of the Bazaar catalog at all.

If none of that matters for your use case, the free REST API or MCP server does the same swap
logic for nothing.

## Endpoints

| Endpoint                                             | Price   | Same contract as                             |
| ---------------------------------------------------- | ------- | -------------------------------------------- |
| `POST https://app.ravn.exchange/api/v1/x402/quote`   | \$0.001 | [`POST /v1/quote`](/api-reference/quote)     |
| `POST https://app.ravn.exchange/api/v1/x402/execute` | \$0.01  | [`POST /v1/execute`](/api-reference/execute) |

Only quote and execute are metered over x402. `status` and `health` aren't priced endpoints and
have no `/x402/` counterpart — call [`GET /v1/status`](/api-reference/status) and
[`GET /v1/health`](/api-reference/health) directly (free, no key) once you've paid to execute.

Request and response bodies are identical to the free endpoints: same fields, same DTOs, same
error codes. The `quoteToken` from `/v1/x402/quote` works interchangeably with either
`/v1/execute` or `/v1/x402/execute`: you can get a free quote and only pay to execute, if you
want.

The price is a flat access fee for the API call itself; it is **not** RAVN's swap fee, which
stays 0% on every route regardless of which door you come through.

## Accepted payment

| Network          | Asset |
| ---------------- | ----- |
| Base (mainnet)   | USDC  |
| Solana (mainnet) | USDC  |

## How it works

x402 repurposes the HTTP `402 Payment Required` status code:

1. Call the endpoint with no payment attached.
2. RAVN responds `402` with a `payment-required` header describing accepted payment options
   (network, asset, amount, recipient).
3. Your x402 client signs a payment (an EIP-3009 USDC authorization on Base, or a Solana USDC
   transfer) and retries the request with a `payment-signature`-style header attached.
4. RAVN verifies and settles the payment via its facilitator, then executes your original
   request and returns the normal response.

Most x402 client libraries handle steps 2 and 3 automatically once wrapped around `fetch`.

<Tip>
  Debugging step 2 by hand? The `402` response body is an empty `{}` — that's correct, not a
  bug. The actual payment terms are in the `payment-required` response header (base64-encoded),
  not the body. Decode that header to see accepted networks, assets, and amounts.
</Tip>

## Example

```javascript theme={null}
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";

const core = new x402Client();
core.register("eip155:*", new ExactEvmScheme(toClientEvmSigner(yourEvmWalletClient)));

const x402Fetch = wrapFetchWithPayment(fetch, core);

const res = await x402Fetch("https://app.ravn.exchange/api/v1/x402/quote", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    inputChainId: 1,
    outputChainId: 8453,
    inputToken: "0xEeeeeEeeeEeEeeEeEeEeeeEEeeeeEeeeeeeeEEeE",
    outputToken: "0xEeeeeEeeeEeEeeEeEeEeeeEEeeeeEeeeeeeeEEeE",
    inputAmount: "1000000000000000000",
    userAddress: "0xYourAddress",
  }),
});

const { data } = await res.json(); // includes quoteToken
```

Swap in a Solana signer (`@x402/svm`) to pay from a Solana wallet instead.

## Errors

Same [error envelope](/errors) as the rest of the Integrator API. One addition:

| Code             | HTTP status | Meaning                                                                                               |
| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| `NOT_CONFIGURED` | 503         | x402 payments aren't currently enabled; use the [free endpoints](/api-reference/overview) instead     |
| `NOT_FOUND`      | 404         | No such route — only `/x402/quote` and `/x402/execute` exist; everything else is REST-only, see above |