React Component

The <DepositOSWidget /> component renders the deposit widget inline in your page. Use this approach when you want full control over positioning and layout — for example, embedding the widget directly in a checkout page or dashboard panel.

Basic Usage

import { DepositOSWidget } from "@gizmolab/depositos";

function DepositPage() {
  return (
    <div className="max-w-sm mx-auto mt-10">
      <DepositOSWidget
        config={{
          apiKey: "dos_live_…",
          destChain: 42161,
          destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
          destAddress: "0xYourTreasuryAddress",
          enableWallet: true,
          enablePrivateMode: true,
        }}
        onClose={() => console.log("Widget closed")}
        onSuccess={(txHash) => console.log("Deposit complete:", txHash)}
      />
    </div>
  );
}

The widget renders as a self-contained card with its own header, content area, and footer. It manages all internal state — chain selection, token selection, approvals, execution progress, and error handling.

Props

| Prop | Type | Required | Description | |---|---|---|---| | config | DepositOSConfig | Yes | Widget configuration object (see below) | | onClose | () => void | No | Called when the user clicks the close button in the widget header | | onSuccess | (txHash?: string) => void | No | Called when a deposit completes successfully |

Required Config Fields

Every config object must include these four fields. Without them, the widget will not render.

| Field | Type | Description | |---|---|---| | integratorId | string | Your unique integrator identifier. Used for fee routing and event tracking. | | destChain | number | The chain ID where funds should arrive (e.g., 42161 for Arbitrum, 8453 for Base). | | destToken | string | The token contract address on the destination chain. | | destAddress | string | The recipient wallet address. This is locked — users cannot change it. |

Handling Close

The onClose callback fires when the user clicks the X button in the widget header. A common pattern is to toggle the widget's visibility:

import { useState } from "react";
import { DepositOSWidget } from "@gizmolab/depositos";

function Checkout() {
  const [showWidget, setShowWidget] = useState(false);

  return (
    <div>
      <button onClick={() => setShowWidget(true)}>
        Pay with Crypto
      </button>

      {showWidget && (
        <DepositOSWidget
          config={{
            apiKey: "dos_live_…",
            destChain: 42161,
            destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
            destAddress: "0xYourTreasuryAddress",
          }}
          onClose={() => setShowWidget(false)}
          onSuccess={(txHash) => {
            setShowWidget(false);
            alert(`Payment received! TX: ${txHash}`);
          }}
        />
      )}
    </div>
  );
}

Handling Success

The onSuccess callback receives an optional txHash parameter. Depending on route/provider behavior, this hash may be unavailable at callback time.

<DepositOSWidget
  config={config}
  onSuccess={(txHash) => {
    if (txHash) {
      // Redirect to a confirmation page with the transaction hash
      window.location.href = `/confirmation?tx=${txHash}`;
    } else {
      // Show a generic success message
      window.location.href = "/confirmation";
    }
  }}
/>

Enabling Funding Sources

By default, only the wallet funding source is enabled. Toggle additional methods via config flags:

const config = {
  apiKey: "dos_live_…",
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourTreasuryAddress",

  enableWallet: true,         // Wallet-based cross-chain swap (default: true)
  enablePrivateMode: true,    // Private deposit with enhanced privacy
};

Theming

Pass a depositOSTheme object to customize the widget's appearance:

<DepositOSWidget
  config={{
    ...config,
    depositOSTheme: {
      mode: "dark",
      colors: {
        background: "#1a1a2e",
        accent: "#7C3AED",
        card: "#16213e",
        textPrimary: "#ffffff",
      },
      borderRadius: "1rem",
      fontFamily: "Inter, system-ui, sans-serif",
    },
  }}
/>

See the Theme Reference for the full list of customizable properties.