Embedding the widget

The widget is a hosted swap UI. It never asks the user to connect a second wallet: @ravnexchange/widget-connector lets it use the wallet already connected on your page.

Embed the iframe

Set ?origin= to your page’s exact origin.

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

Keep allow-same-origin: without it the widget can’t talk to your page. It needs no allow-popups or allow-top-navigation. v1 stays stable; a breaking change ships as v2.

Wrap your wallet

npm install @ravnexchange/widget-connector

import type { RavnWallet, RavnSolanaWallet } from "@ravnexchange/widget-connector";

const evmWallet: RavnWallet = {
  address: account.address ?? null,
  chainId: account.chainId ?? null,
  sendTransaction: (req) => wagmiSendTransaction(req),
  signTypedData: (req) => wagmiSignTypedData(req.typedData),
  signMessage: (req) => wagmiSignMessage(req.message),
  switchChain: (req) => wagmiSwitchChain(req.chainId).then(() => ({ ok: true })),
};

const solanaWallet: RavnSolanaWallet = {
  address: solanaAccount?.address ?? null,
  signTransaction: (req) => adapter.signTransaction(req.transaction),
};

These call your wallet, which shows the user what they’re signing. Never wire them to a signer with no confirmation step.

Connect the bridge

import { createRavnWidgetBridge } from "@ravnexchange/widget-connector";

const bridge = createRavnWidgetBridge({
  iframe: iframeRef.current,
  widgetOrigin: "https://app.ravn.exchange",
  getWallet: () => (isEvmConnected ? evmWallet : null),
  getSolanaWallet: () => (isSolanaConnected ? solanaWallet : null),
  config: { primaryColor: "#7C3AED" }, // optional: see Theming
});

bridge.updateWallet(isEvmConnected ? { address, chainId } : null);   // on every EVM wallet change
bridge.updateSolanaWallet(isSolanaConnected ? { address: solanaAddress } : null); // on every Solana change
bridge.destroy(); // on unmount

Native BTC deposits need nothing from you: the widget shows the deposit address, a QR code and live status itself. If the bridge never answers, the widget falls back to its own wallet-connect UI. For tighter framing, set your page’s CSP frame-src to https://app.ravn.exchange. To match your brand, see Theming.

Reference

HTMLIFrameElement

required

The embedded iframe.

https://app.ravn.exchange. Never *.

() => RavnWallet | null

required

Your EVM wallet, or null when none is connected.

() => RavnSolanaWallet | null

Your Solana wallet, or null. signTransaction gets an unsigned base64 versioned transaction and returns it signed.

object

The widget’s theme. Other keys are ignored: an API key here does nothing, so the widget doesn’t carry your fee.

A wallet request while no wallet is connected fails in the widget with WALLET_NOT_CONNECTED or SOLANA_WALLET_NOT_CONNECTED.

​Reference

Reference