Quick Start

Get depositOS running in your React app in under five minutes. This guide uses the React hook approach, which is the recommended integration for most applications.

1. Install the Package

pnpm add @gizmolab/depositos

Or with npm:

npm install @gizmolab/depositos

2. Wrap Your App with the Provider

Add DepositOSDepositProvider at the top of your component tree. Pass your deposit configuration — at minimum, the destination chain, token, address, and your API key.

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

const depositConfig = {
  apiKey: "dos_live_…",
  destChain: 42161,                                    // Arbitrum
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum
  destAddress: "0xYourTreasuryAddress",
  enableWallet: true,
  enablePrivateMode: true,
};

export default function App() {
  return (
    <DepositOSDepositProvider
      config={depositConfig}
      onSuccess={(txHash) => {
        console.log("Deposit complete!", txHash);
      }}
    >
      <YourApp />
    </DepositOSDepositProvider>
  );
}

3. Open the Widget from Any Component

Use the useDepositOS() hook in any child component to get a function that opens the widget as a full-screen modal overlay.

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

function DepositButton() {
  const { openDepositOS } = useDepositOS();

  return (
    <button onClick={() => openDepositOS()}>
      Deposit Funds
    </button>
  );
}

That's it. Clicking the button opens the depositOS widget. The user selects a funding method, completes the deposit, and your onSuccess callback fires with the transaction hash.

Configuration Reference

Here are the required and commonly used config fields:

| Property | Type | Required | Description | |---|---|---|---| | destChain | number | Yes | Destination chain ID (e.g., 42161 for Arbitrum) | | destToken | string | Yes | Token contract address on the destination chain | | destAddress | string | Yes | Recipient address where funds will be sent | | apiKey | string | Yes | Your dos_live_… key from the portal | | userId | string | No | Your id for the end user — the same id always gets the same deposit address | | mode | "deposit" \| "transfer" \| "withdraw" | No | Direction of the flow (default: "deposit") | | enableWallet | boolean | No | Enable wallet-based deposits (default: true) | | enableDepositAnywhere | boolean | No | Enable the persistent deposit-address flow | | enablePrivateMode | boolean | No | Enable private deposit mode | | theme | "light" \| "dark" | No | Widget color scheme (default: "dark") |

See the full Configuration reference for all available options.

What's Next

• Installation — Detailed setup including peer dependencies and monorepo configuration
• React Component — Embed the widget inline instead of as a modal
• React Hook — Full details on the provider and hook API
• Iframe Embed — Integrate without React
• Script Tag — Zero-dependency integration for static sites