x402 Payments

RAVN’s quote and execute endpoints are also available over x402: 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; 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 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) and listed on 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`
`POST https://app.ravn.exchange/api/v1/x402/execute`	$0.01	`POST /v1/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 and GET /v1/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. Want to test the swap logic without moving real funds? sandbox: true on /v1/x402/quote works the same as on the free endpoint. Note this only skips RAVN’s own swap accounting, not the x402 access fee: the USDC payment for the call itself is a separate gate and is charged as normal either way. See Sandbox Mode. The price is a flat access fee for the API call itself; it is not RAVN’s swap fee. Without a key, x402 calls quote at the 0% default. If you also hold a self-serve key with a fee set (see PATCH /v1/keys), send it as x-api-key alongside the payment: the quote then carries your fee, and swaps executed from that quoteToken, through either /v1/x402/execute or /v1/execute, are credited to you like any other keyed swap. A key you send is checked, so an invalid one is a 401, not a silent downgrade to 0%. See Pricing.

Accepted payment

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

How it works

x402 repurposes the HTTP 402 Payment Required status code:

Call the endpoint with no payment attached.
RAVN responds 402 with a payment-required header describing accepted payment options (network, asset, amount, recipient).
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.
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.

Debugging step 2 by hand? The 402 response body is an empty {}, which is 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.

Example

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 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 instead
`NOT_FOUND`	404	No such route: only `/x402/quote` and `/x402/execute` exist; everything else is REST-only, see above

​Endpoints

​Accepted payment

​How it works

​Example

​Errors

Endpoints

Accepted payment

How it works

Example

Errors