Rath Widget

Embeddable cross-chain swap widget by Rath Finance.

Install

npm install @rathfi/widget

When imported into a React app (import RathWidget from "@rathfi/widget", see External wallet management below), these peer dependencies must also be installed: react, react-dom, wagmi, viem, @tanstack/react-query. If you're only using the CDN/<script> embed, none of this applies — it bundles everything itself.

The default and named React imports are equivalent. The API key can be passed directly or as part of config:

import RathWidget from "@rathfi/widget";
// Also supported: import { RathWidget } from "@rathfi/widget";

<RathWidget apiKey="YOUR_RATH_API_KEY" />;
// Equivalent: <RathWidget config={{ apiKey: "YOUR_RATH_API_KEY" }} />;

Or load it straight from a CDN:

<link rel="stylesheet" href="https://unpkg.com/@rathfi/widget/dist/widget.css" />
<script src="https://unpkg.com/@rathfi/widget/dist/widget.js"></script>

Usage

The widget auto-mounts into an element with id rath-widget-root. Pass your API key from the host page — it is never bundled into the widget:

<div id="rath-widget-root" data-rath-api-key="YOUR_RATH_API_KEY"></div>
<link rel="stylesheet" href="https://unpkg.com/@rathfi/widget/dist/widget.css" />
<script src="https://unpkg.com/@rathfi/widget/dist/widget.js"></script>

Or mount manually into any element:

<div id="swap-container"></div>
<script>
  window.RathWidget.mount(document.getElementById("swap-container"), {
    apiKey: "YOUR_RATH_API_KEY",
    theme: { accent: "#0536A0" },
  });
</script>

Note: like any key shipped to the browser, the API key is visible to end users. Use a publishable key and restrict it server-side (e.g. by allowed origins/domains).

External wallet management (host-provided wagmi)

When the widget component is rendered inside a React host app that already has a wagmi setup, the widget detects the surrounding WagmiContext and reuses it instead of creating a second WagmiProvider. The wallet the user connected in the host app is picked up automatically — no duplicate connections, no second connect prompt.

import { WagmiProvider, createConfig, http } from "wagmi";
import { mainnet, base } from "wagmi/chains";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import RathWidget from "@rathfi/widget"; // the widget React component

const wagmiConfig = createConfig({
  chains: [mainnet, base],
  transports: { [mainnet.id]: http(), [base.id]: http() },
});
const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        {/* your app… */}
        <RathWidget
          config={{
            apiKey: "YOUR_RATH_API_KEY",
            walletConfig: {
              // Open your own wallet modal (RainbowKit, ConnectKit, AppKit, …)
              // when the user clicks the widget's connect button.
              onConnect: () => openMyWalletModal(),
            },
          }}
        />
      </QueryClientProvider>
    </WagmiProvider>
  );
}

walletConfig options

| Option | Effect | | --- | --- | | onConnect?: () => void | Called when the user clicks the widget's connect button, so the host opens its own wallet modal. Without it the widget opens its internal connector menu. | | forceInternalWalletManagement?: boolean | Always use the widget's internal wallet UI, even when onConnect is provided. | | usePartialWalletManagement?: boolean | Keep the widget's internal wallet menu reachable (e.g. via the rath-wallet-open event) alongside onConnect, so the widget can still connect wallets the host does not manage. |

Connect-button behaviour:

1. If walletConfig.onConnect is set and forceInternalWalletManagement is not true, the widget calls onConnect() and the host shows its modal.
2. Otherwise the widget opens its internal wallet/connector selection UI (or auto-connects when only one connector is available).

Inside the widget, useWallet() exposes the unified wallet state regardless of who manages the connection: address, chainId, isConnected, the active connector (id, name, icon), the installed connectors, and connect(connectorId) / disconnect(). usesExternalWagmi reports whether a host context was detected.

Requirements & caveats:

• Context detection only works when the widget renders in the same React tree as the host's WagmiProvider, with wagmi deduped to a single package instance (a second copy of wagmi has its own React context and won't be detected).
• The CDN/IIFE embed (window.RathWidget.mount) creates its own React root, so it cannot see a host React context — it always falls back to the widget's internal wallet management. walletConfig.onConnect still works there via the mount config.
• Without a surrounding wagmi context, the widget keeps its existing behaviour: it creates its own WagmiProvider (or uses the wagmiConfig prop passed to RathWalletProvider) and manages wallets internally.

Development

cp .env.example .env   # add your dev API key (used only by npm run dev)
npm install
npm run dev

Publishing

npm publish

prepublishOnly rebuilds dist/ and runs scripts/check-publish-safety.mjs, which blocks the publish if the output contains source maps, VITE_ env references, or any secret value from local .env files. Only dist/ is included in the package (files allowlist in package.json).