Add cross-chain swaps to your app without building a router

Quick answer

Skip the wallet plumbing, raw HTTP and Bitcoin UTXO code. We ship four ready-made layers over the same quote, execute, submit-signature and status calls. A hosted widget you embed in an iframe. A typed SDK for JS or TypeScript. A typed Python client. And React hooks for your own UI. Same fields, same 0 bps default fee, same routes as the raw API.

The widget is fastest

One iframe, pointed at your own origin:

<iframe
  src="https://app.ravn.exchange/widget/v1?origin=https://your-site.example"
  sandbox="allow-scripts allow-same-origin allow-forms"
></iframe>

That alone is a working swap UI. To use the wallet already connected on your page, install the connector and hand it your wallet's send and sign functions:

npm install @ravnexchange/widget-connector

Now users never see a second connect prompt. Native BTC deposits need no wallet code: the widget shows the address, a QR code and a status tracker itself. Wiring guide for EVM and Solana wallets: docs.ravn.exchange/sdks/widget. To match your brand, see theming the widget and the live theme playground.

Build your own UI with the SDK

npm install @ravnexchange/sdk

import { RavnClient } from "@ravnexchange/sdk";

const client = new RavnClient(); // omit apiKey for the anonymous tier

const quote = await client.getQuote({
  inputChainId: 1,
  outputChainId: -2,
  inputToken: "0xEeee...EEeE",
  outputToken: "So1111...1112",
  inputAmount: "1000000000000000000",
  userAddress: "0xYourUser",
  destinationAddress: "SoYourUser",
});

const execution = await client.execute({ quoteToken: quote.quoteToken });
// branch on execution.executionType: TRANSACTION, SIGNATURE, or DEPOSIT

The raw API, typed. You catch one error, RavnApiError, instead of parsing status codes. Reference: docs.ravn.exchange/sdks/core.

Python backends and bots

pip install ravnexchange

from ravnexchange import RavnClient

client = RavnClient()  # omit api_key for the anonymous tier

quote = client.get_quote({
    "inputChainId": 1,
    "outputChainId": 8453,
    "inputToken": "0xEeee...EEeE",
    "outputToken": "0x8335...02913",
    "inputAmount": "1000000000000000000",
    "userAddress": "0xYourAddress",
    "destinationAddress": "0xYourAddress",
})
execution = client.execute({"quoteToken": quote["quoteToken"]})
# branch on execution["executionType"]: TRANSACTION, SIGNATURE, or DEPOSIT

Built on the stdlib urllib.request, so it adds no dependencies. Same scope as the JS SDK, snake_cased. Reference: docs.ravn.exchange/sdks/python.

Hooks for React apps

npm install @ravnexchange/react @ravnexchange/sdk

const { quote, isExpired, refetch } = useRavnQuote(client, params);
const { execute } = useRavnExecute(client);
const { status } = useRavnStatus(client, statusRef ? { quoteToken, ref: statusRef } : null);

useRavnQuote refetches when your params change. It flips isExpired when the quote runs out, with no loop to write. useRavnStatus polls until the swap is done. None of the hooks sign or send. That stays with your wallet. Reference: docs.ravn.exchange/sdks/react.

Test it without real funds

Set sandbox: true on the quote, on any path above. The whole flow runs end to end with no funds moved and nothing billed. The contract matches live, so the code you test is the code you ship. Details: docs.ravn.exchange/sandbox-mode.

Open source

All four packages and the examples above are MIT-licensed at github.com/ravndex/ravn-sdk. Each one publishes to npm or PyPI via GitHub Actions with OIDC trusted publishing, so no registry token is stored.

The live playground at ravndex.github.io/ravn-sdk lets you watch the bridge work before you install anything. The routing engine and the widget's iframe page stay closed. What you embed is open.