Widget Integration

The Hypermid Widget embeds the full Hypermid experience into any website — swap, bridge, gas refuel, and buy crypto with card. It uses the same production app at hypermid.io, loaded as an iframe.

The widget includes full wallet connection (550+ wallets via Reown/WalletConnect) supporting EVM, Solana, Bitcoin, TON, TRON, and SUI — no additional setup needed.

Features

Cross-chain swap & bridge — 90+ chains, best route comparison
On-ramp — Buy crypto with card via RampNow (USD, EUR, GBP, and more)
Gas refuel — Top up gas on any chain
Wallet connection — MetaMask, WalletConnect, Coinbase, Trust Wallet, Binance, and 550+ more
Full theme customization — Colors, borders, radius, fonts, shadows
Event callbacks — Quote, execute, status, error events via postMessage
Auto-resize — Iframe height adjusts to content
Mode toggle — Users can switch between Swap, Gas, and Fund modes

Quick Start

Script Tag (Any Website)

<div id="hypermid-widget"></div>

<script src="https://widget.hypermid.io/v1/embed.js"></script>
<script>
  HypermidWidget.init({
    containerId: "hypermid-widget",
    apiKey: "your-api-key",
    theme: "dark",
    defaultFromChain: 1,
    defaultToChain: 42161,
  });
</script>

Data Attribute (Zero JS)

For even simpler integration — no JavaScript needed:

<div
  id="hypermid-widget"
  data-hypermid-widget
  data-api-key="your-api-key"
  data-theme="dark"
  data-from-chain="1"
  data-to-chain="42161"
></div>

<script src="https://widget.hypermid.io/v1/embed.js"></script>

Direct Iframe

If you prefer full control, embed the iframe directly:

<iframe
  src="https://app.hypermid.io/widget?apiKey=your-api-key&theme=dark&fromChain=1&toChain=42161&embed=1"
  width="420"
  height="700"
  frameborder="0"
  allow="clipboard-write; payment; web-share"
  style="border: none; border-radius: 16px; box-shadow: 0 4px 24px rgba(0,0,0,0.15);"
></iframe>

Do NOT add the sandbox attribute to the iframe — it will break wallet connections.

Configuration Options

Display

Option	Type	Default	Description
`containerId`	`string`	required	DOM element ID to mount into
`apiKey`	`string`	—	Your API key. Optional — attributes swaps to your account for fee tracking
`theme`	`"dark" \| "light"`	`"dark"`	Widget color theme
`mode`	`"swap" \| "gas" \| "fund"`	`"swap"`	Initial active mode
`width`	`string`	`"420px"`	Widget width
`height`	`string`	`"700px"`	Widget height
`hideOnramp`	`boolean`	`false`	Hide the mode toggle (swap/gas/fund)
`hidePoweredBy`	`boolean`	`false`	Hide “Powered by Hypermid”

Presets

Option	Type	Default	Description
`defaultFromChain`	`number`	`1`	Default source chain ID
`defaultToChain`	`number`	—	Default destination chain ID
`defaultFromToken`	`string`	—	Default source token address
`defaultToToken`	`string`	—	Default destination token address
`defaultFromAmount`	`string`	—	Default input amount
`walletAddress`	`string`	—	Pre-fill wallet address
`lockFromChain`	`boolean`	`false`	Lock source chain selector
`lockToChain`	`boolean`	`false`	Lock destination chain selector

Theme Customization

Override any visual aspect of the widget to match your brand:

Option	Type	Default	Description
`accentColor`	`string`	`"#44E1AA"`	CTA button & highlight color
`accentHoverColor`	`string`	—	Accent hover state color
`bgPrimary`	`string`	—	Page background color
`bgCard`	`string`	—	Card background color
`bgCardInner`	`string`	—	Inner card / token area background
`bgInput`	`string`	—	Input field background
`textPrimary`	`string`	—	Primary text color
`textSecondary`	`string`	—	Secondary text color
`borderColor`	`string`	—	Border color (format: `"hex:opacity"` e.g. `"6C63FF:15"`)
`borderRadius`	`number`	`16`	Card corner radius in px
`buttonRadius`	`number`	`12`	Button corner radius in px
`fontFamily`	`string`	`"Sora"`	Font family name
`shadow`	`string`	—	Card shadow CSS value (or `"none"`)

Example — fully branded widget:

HypermidWidget.init({
  containerId: "swap",
  apiKey: "sk_live_your_key",
  theme: "dark",
  defaultFromChain: 1,
  defaultToChain: 42161,
  // Brand customization
  accentColor: "#FF6B35",
  bgPrimary: "#1A1A2E",
  bgCard: "#252540",
  borderRadius: 20,
  buttonRadius: 8,
  fontFamily: "Inter",
});

Wallet Connection

The widget includes built-in wallet connection via Reown AppKit — the same wallet infrastructure used by the main Hypermid app. No additional configuration needed. Supported wallet ecosystems:

Ecosystem	Wallets
EVM	MetaMask, WalletConnect QR, Coinbase, Trust Wallet, Binance, SafePal, Rainbow, and 500+ more
Solana	Phantom, Solflare, Backpack
Bitcoin	Xverse, Leather, UniSat
TON	Tonkeeper, MyTonWallet
TRON	TronLink
SUI	Sui Wallet

When users click “Connect Wallet”, a modal appears with all supported wallets for the selected chain ecosystem. After connecting, the widget displays token balances and enables transaction signing.

On-Ramp (Buy Crypto)

The widget includes a built-in “Buy Crypto” tab powered by RampNow. Users can purchase crypto with their credit/debit card directly within the widget. To open the widget in on-ramp mode by default:

HypermidWidget.init({
  containerId: "hypermid-widget",
  apiKey: "your-api-key",
  mode: "fund",  // Opens Buy Crypto tab
});

The on-ramp supports:

Fiat currencies: USD, EUR, GBP, and more
Crypto tokens: ETH, USDC, USDT, BTC, and 50+ tokens
Payment methods: Credit card, debit card, Apple Pay, Google Pay
KYC: Handled by RampNow within the flow

To hide the mode toggle and show only the swap UI, set hideOnramp: true. This removes the swap/gas/fund toggle at the top.

Event Callbacks

Listen for events from the widget:

HypermidWidget.init({
  containerId: "hypermid-widget",
  apiKey: "your-api-key",

  onReady: function () {
    console.log("Widget loaded and ready");
  },

  onQuote: function (quote) {
    console.log("Quote received:", quote);
    // { fromToken, toToken, fromAmount, toAmount, provider, fee }
  },

  onExecute: function (result) {
    console.log("Swap executed:", result);
    // { txHash, provider, fromChain, toChain, status }
  },

  onStatusChange: function (status) {
    console.log("Status update:", status);
    // { status: "PENDING" | "PROCESSING" | "DONE" | "FAILED", txHash }
  },

  onError: function (error) {
    console.error("Widget error:", error);
    // { code, message }
  },
});

Events are communicated via window.postMessage from the iframe. The embed script handles the plumbing automatically.

Programmatic Control

After initialization, control the widget dynamically:

// Update configuration (rebuilds iframe)
HypermidWidget.update({
  theme: "light",
  defaultFromChain: 42161,
});

// Set swap parameters
HypermidWidget.setSwap({
  fromChain: 1,
  toChain: 137,
  fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  fromAmount: "100",
});

// Change theme at runtime
HypermidWidget.postMessage("setTheme", { theme: "light" });

// Override CSS variables at runtime
HypermidWidget.postMessage("setStyle", {
  "--bg-card": "#1a1a2e",
  "--accent-cyan": "#ff6b35",
});

// Remove the widget
HypermidWidget.destroy();

React Integration

Wrap the embed script in a React component:

import { useEffect, useRef } from "react";

declare global {
  interface Window {
    HypermidWidget: any;
  }
}

interface HypermidWidgetProps {
  apiKey?: string;
  theme?: "dark" | "light";
  mode?: "swap" | "gas" | "fund";
  defaultFromChain?: number;
  defaultToChain?: number;
  accentColor?: string;
  onSwapComplete?: (result: any) => void;
  onError?: (error: any) => void;
}

export function HypermidWidget(props: HypermidWidgetProps) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://widget.hypermid.io/v1/embed.js";
    script.onload = () => {
      window.HypermidWidget.init({
        containerId: "hypermid-react-widget",
        apiKey: props.apiKey,
        theme: props.theme || "dark",
        mode: props.mode || "swap",
        defaultFromChain: props.defaultFromChain,
        defaultToChain: props.defaultToChain,
        accentColor: props.accentColor,
        onExecute: props.onSwapComplete,
        onError: props.onError,
      });
    };
    document.body.appendChild(script);

    return () => {
      window.HypermidWidget?.destroy();
      document.body.removeChild(script);
    };
  }, []);

  return <div id="hypermid-react-widget" ref={containerRef} />;
}

Usage:

<HypermidWidget
  apiKey="your-api-key"
  theme="dark"
  mode="swap"
  defaultFromChain={1}
  defaultToChain={42161}
  accentColor="#FF6B35"
  onSwapComplete={(result) => console.log("Done!", result)}
/>

Supported Chains

The widget supports all chains available in the Hypermid app:

EVM: Ethereum, Arbitrum, Base, Polygon, Optimism, BSC, Avalanche, and 50+ more
Non-EVM: Solana, Bitcoin, TON, TRON, NEAR, XRP, Dogecoin, Litecoin, and more
On-ramp: Buy crypto with card on any supported chain

See Chain Support for the full list.

Best Practices

Set default chains — Pre-select the most common pair for your users to reduce friction
Use apiKey — Ensures fee tracking and higher rate limits for your integration
Handle callbacks — Implement onExecute and onError to update your app state
Don’t use sandbox — The iframe sandbox attribute breaks wallet connections
Set height: 700px — The widget needs at least 700px height for the on-ramp form
Lock chains if needed — Use lockFromChain/lockToChain for focused use cases
Test in incognito — Your existing Hypermid session may auto-connect the wallet

​Features

​Quick Start

​Script Tag (Any Website)

​Data Attribute (Zero JS)

​Direct Iframe

​Configuration Options

​Display

​Presets

​Theme Customization

​Wallet Connection

​On-Ramp (Buy Crypto)

​Event Callbacks

​Programmatic Control

​React Integration

​Supported Chains

​Best Practices

Features

Quick Start

Script Tag (Any Website)

Data Attribute (Zero JS)

Direct Iframe

Configuration Options

Display

Presets

Theme Customization

Wallet Connection

On-Ramp (Buy Crypto)

Event Callbacks

Programmatic Control

React Integration

Supported Chains

Best Practices