defungiz-swap-widget

A drop-in React / Next.js widget that lets users pay a fixed USD amount on the 0G network using any ERC-20 token (or native OG) in their wallet. The widget handles token discovery, live price fetching, swap routing, transaction signing, and network switching — you just provide a provider and a callback.

Installation

npm install defungiz-swap-widget
# or
yarn add defungiz-swap-widget
# or
pnpm add defungiz-swap-widget

Quick start

import { BrowserProvider } from "ethers";
import { PayWithTokenWidget } from "pay-with-token-widget";

function MyPage() {
  const [provider, setProvider] = useState<BrowserProvider | null>(null);

  const connect = async () => {
    const p = new BrowserProvider(window.ethereum);
    await p.send("eth_requestAccounts", []);
    setProvider(p);
  };

  const handleMint = async () => {
    // call your NFT contract here
  };

  return (
    <>
      <button onClick={connect}>Connect Wallet</button>

      {provider && (
        <PayWithTokenWidget
          provider={provider}
          usdAmount="5"
          allowedTokens="all"
          onExecuteNftAction={handleMint}
          onError={(err) => console.error(err)}
        />
      )}
    </>
  );
}

Props

| Prop | Type | Required | Default | Description | | -------------------- | ------------------------------------ | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | provider | BrowserProvider | ✅ | — | An ethers v6 BrowserProvider connected to the user's wallet. | | usdAmount | string | ✅ | — | The fixed USD amount the user must pay, e.g. "5" or "0.50". | | allowedTokens | "all" | string[] | ✅ | — | Which tokens to show. Pass "all" to show every supported token, or an array of ERC-20 contract addresses to restrict the list. Include the native sentinel address (0xEeee…EEEE) in the array to add the native OG token. | | onExecuteNftAction | () => Promise<void> | ✅ | — | Called after the swap transactions confirm. Use this to mint/buy your NFT or execute whatever action the payment unlocks. | | onError | (err: unknown) => void | — | — | Called whenever an error occurs (wrong network, insufficient funds, rejected transaction, API failure, etc.). | | slippageBps | number | — | 100 | Swap slippage tolerance in basis points. 100 = 1 %. | | partnerFees | { fee: number; recipient: string } | — | — | Optional protocol fee. fee is in basis points; recipient is the fee-receiving address. | | accentColor | string | — | "#ab03b6" | Hex colour used to theme the entire widget — button, borders, focus rings, and card background. Non-hex values (e.g. "royalblue") are applied to the button only. |

allowedTokens examples

// Show every token the API knows about + native OG
<PayWithTokenWidget allowedTokens="all" ... />

// Restrict to two specific ERC-20s
<PayWithTokenWidget
  allowedTokens={[
    "0x7bbc63d01ca42491c3e084c941c3e86e55951404",
    "0xabc123...",
  ]}
  ...
/>

// Native OG only
<PayWithTokenWidget
  allowedTokens={["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]}
  ...
/>

Important — Next.js / inline arrays: If you pass allowedTokens as an inline array literal, wrap it in useMemo (or define it outside the component) so the reference stays stable and avoids re-fetching on every render.

const tokens = useMemo(
  () => ["0x7bbc63d01ca42491c3e084c941c3e86e55951404"],
  [],
);
<PayWithTokenWidget allowedTokens={tokens} ... />

Theming

Pass a single hex colour to accentColor and the widget derives the full palette automatically — button gradient, focus rings, and a dark card background tinted with your colour.

// Purple (default)
<PayWithTokenWidget accentColor="#ab03b6" ... />

// Blue
<PayWithTokenWidget accentColor="#015198" ... />

// Orange
<PayWithTokenWidget accentColor="#e85d04" ... />

The widget is width: 100% by default and adapts to whatever container you place it in. Font is Urbanist (loaded automatically via Google Fonts).

Network

The widget is hardcoded to the 0G Newton network (chain ID 16661). If the user's wallet is on a different network, a "Wrong network" banner appears with a one-click Switch to 0G button. If the network isn't in the wallet yet, the widget calls wallet_addEthereumChain automatically.

Flow

1. Widget loads supported tokens and their USD prices from the Deserialize API.
2. User selects a token — their balance and its USD equivalent are shown.
3. User clicks Pay $X — the widget fetches a swap quote, sends the transaction(s), and waits for confirmation.
4. Once confirmed, onExecuteNftAction is called so you can complete your mint / purchase.
5. Status messages (loading, errors, success) auto-clear after 3 seconds.

Requirements

• React 18+
• ethers v6
• A browser wallet (MetaMask, Rabby, etc.)