RAVN examples

Working code for the RAVN cross-chain swap API — including native Bitcoin, not wrapped BTC.

One integration covers 16 chains (14 EVM + Bitcoin + Solana). Every quote races 12 execution venues in parallel and the best net output wins. RAVN takes 0 bps on every route. Non-custodial: RAVN never holds your funds and writes no smart contracts of its own.

No signup required to start. Every example below runs anonymously.

git clone https://github.com/ravndex/ravn-examples
cd ravn-examples && npm install
npm run health

The examples

The contract

Four calls, always the same order.

POST /quote   → best route + an opaque quoteToken
POST /execute → an execution payload tagged by executionType
                (+ submit-signature, when the type is SIGNATURE)
GET  /status  → pending → processing → success (or refunded / failed)

Everything branches on one field:

switch (execution.executionType) {
  case "TRANSACTION": // sign and broadcast it yourself
  case "SIGNATURE":   // sign typed data; RAVN submits it, no gas
  case "DEPOSIT":     // send the input asset to an address
}

The one thing that trips people up

An ERC-20 swap is really two transactions. Before any contract can move your tokens you must sign a separate on-chain permission — an approve(). TRANSACTION and SIGNATURE payloads carry that ready to send, as approval, whenever it's needed.

if (execution.approval) {
  const hash = await wallet.sendTransaction(execution.approval);
  await client.waitForTransactionReceipt({ hash });   // MINED, not just broadcast
}
// …now send the swap

Broadcasting the swap before the allowance is mined reverts on transferFrom and the user eats the gas. On gasless venues (CoW, Bebop) it's quieter and worse: the order is accepted and simply never fills, with no error. Native-coin sells, already-approved tokens and DEPOSIT routes omit approval entirely.

RAVN doesn't read the chain for you, so approval can appear on a token you've already approved — check the allowance for approval.spender and skip it when it already covers approval.amount.

unlimitedRecommended: true (CoW) means the venue would rather you approve once for a large amount than pay approval gas on every swap. data still encodes the exact amount; raising it is your call.

Amounts

Always strings, always the token's smallest unit — wei, lamports, satoshis. Never floats. toBaseUnits() / fromBaseUnits() in src/ravn.ts convert safely.

Cross-ecosystem swaps

Selling on EVM and receiving BTC or SOL needs a destinationAddress — the payout chain has no idea what your EVM address is.

Rate limits

Pass it as x-api-key. CORS is enabled on every endpoint, so browser-side dapps and wallet widgets can call the API directly with no server-side proxy.

Errors

Branch on the stable code, never the message.

INVALID_REQUEST · UNSUPPORTED_TOKEN · UNSUPPORTED_CHAIN · NO_LIQUIDITY · QUOTE_EXPIRED · QUOTE_INVALID · RATE_LIMITED · UNAUTHORIZED · INTERNAL

Every response carries x-request-id. Quote it if you report a bad quote — it's how we find it.

Links

• Docs — https://docs.ravn.exchange
• App — https://app.ravn.exchange
• MCP server — https://app.ravn.exchange/api/mcp
• OpenAPI spec (Postman / Insomnia import) — https://app.ravn.exchange/openapi.json
• Partnerships — team@ravn.exchange · @ravnexchange

MIT licensed. Issues and PRs welcome.