{
  "markdown": "# RAVN examples\n\n[![smithery badge](https://smithery.ai/badge/team-dgp6/ravn)](https://smithery.ai/servers/team-dgp6/ravn)\n\nWorking code for the [RAVN](https://ravn.exchange) cross-chain swap API — including **native\nBitcoin**, not wrapped BTC.\n\nOne integration covers 16 chains (14 EVM + Bitcoin + Solana). Every quote races 12 execution\nvenues in parallel and the best net output wins. **RAVN takes 0 bps on every route.** Non-custodial:\nRAVN never holds your funds and writes no smart contracts of its own.\n\nNo signup required to start. Every example below runs anonymously.\n\n```bash\ngit clone https://github.com/ravndex/ravn-examples\ncd ravn-examples && npm install\nnpm run health\n```\n\n## The examples\n\n| | What it shows |\n| --- | --- |\n| [`src/health.ts`](src/health.ts) | 10-second smoke test — which venues are racing right now. Start here. |\n| [`src/btc-out.ts`](src/btc-out.ts) | **USDC on Base → native BTC**, end to end. The one most swap APIs can't do. Dry-runs without a wallet. |\n| [`src/agent-swap.ts`](src/agent-swap.ts) | Claude tool-calling loop: the model picks the swap, your code keeps the keys. |\n| [`src/x402-client.ts`](src/x402-client.ts) | Pay-per-call over [x402](https://x402.org) — no key, no account. |\n| [`src/ravn.ts`](src/ravn.ts) | The whole client, ~150 lines. There is no SDK because you don't need one — copy this file. |\n| [`MCP.md`](MCP.md) | Point Claude or Cursor at the hosted MCP server. Three lines of config. |\n\n## The contract\n\nFour calls, always the same order.\n\n```\nPOST /quote   → best route + an opaque quoteToken\nPOST /execute → an execution payload tagged by executionType\n                (+ submit-signature, when the type is SIGNATURE)\nGET  /status  → pending → processing → success (or refunded / failed)\n```\n\nEverything branches on **one field**:\n\n```ts\nswitch (execution.executionType) {\n  case \"TRANSACTION\": // sign and broadcast it yourself\n  case \"SIGNATURE\":   // sign typed data; RAVN submits it, no gas\n  case \"DEPOSIT\":     // send the input asset to an address\n}\n```\n\n### The one thing that trips people up\n\nAn ERC-20 swap is really **two** transactions. Before any contract can move your tokens you must\nsign a separate on-chain permission — an `approve()`. `TRANSACTION` and `SIGNATURE` payloads carry\nthat ready to send, as **`approval`**, whenever it's needed.\n\n```ts\nif (execution.approval) {\n  const hash = await wallet.sendTransaction(execution.approval);\n  await client.waitForTransactionReceipt({ hash });   // MINED, not just broadcast\n}\n// …now send the swap\n```\n\nBroadcasting the swap before the allowance is **mined** reverts on `transferFrom` and the user eats\nthe gas. On gasless venues (CoW, Bebop) it's quieter and worse: the order is accepted and simply\n**never fills**, with no error. Native-coin sells, already-approved tokens and `DEPOSIT` routes omit\n`approval` entirely.\n\nRAVN doesn't read the chain for you, so `approval` can appear on a token you've already approved —\ncheck the allowance for `approval.spender` and skip it when it already covers `approval.amount`.\n\n`unlimitedRecommended: true` (CoW) means the venue would rather you approve once for a large amount\nthan pay approval gas on every swap. `data` still encodes the exact amount; raising it is your call.\n\n## Amounts\n\nAlways strings, always the token's smallest unit — wei, lamports, satoshis. Never floats.\n`toBaseUnits()` / `fromBaseUnits()` in [`src/ravn.ts`](src/ravn.ts) convert safely.\n\n## Cross-ecosystem swaps\n\nSelling on EVM and receiving BTC or SOL needs a `destinationAddress` — the payout chain has no\nidea what your EVM address is.\n\n## Rate limits\n\n| | |\n| --- | --- |\n| No key | 30 req/min per IP |\n| [Free key](https://docs.ravn.exchange/tools/get-api-key), instant, no review | 120 req/min |\n\nPass it as `x-api-key`. **CORS is enabled on every endpoint**, so browser-side dapps and wallet\nwidgets can call the API directly with no server-side proxy.\n\n## Errors\n\nBranch on the stable `code`, never the message.\n\n`INVALID_REQUEST` · `UNSUPPORTED_TOKEN` · `UNSUPPORTED_CHAIN` · `NO_LIQUIDITY` · `QUOTE_EXPIRED` ·\n`QUOTE_INVALID` · `RATE_LIMITED` · `UNAUTHORIZED` · `INTERNAL`\n\nEvery response carries `x-request-id`. Quote it if you report a bad quote — it's how we find it.\n\n## Links\n\n- Docs — <https://docs.ravn.exchange>\n- App — <https://app.ravn.exchange>\n- MCP server — `https://app.ravn.exchange/api/mcp`\n- OpenAPI spec (Postman / Insomnia import) — `https://app.ravn.exchange/openapi.json`\n- Partnerships — team@ravn.exchange · [@ravnexchange](https://x.com/ravnexchange)\n\nMIT licensed. Issues and PRs welcome.\n",
  "bytes": 4584,
  "sha": "1b62e3945ddec218fd6dda726bf4277a03bc68522cb2cdc197c13c377d3ff39f",
  "repo_slug": "ravndex/ravn-examples",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_exchange_ravn_ravn_48207c53/readme"
}