Configuration Reference

Complete reference for the DepositOSConfig object. This is the primary configuration interface for the depositOS widget.

Required Properties

| Property | Type | Description | |---|---|---| | destChain | number | Destination chain ID. For example, 42161 for Arbitrum, 1 for Ethereum, 137 for Polygon. | | destToken | string | Token contract address on the destination chain. Use the full checksummed address. | | destAddress | string | Recipient wallet address where deposited funds will be sent. | | apiKey | string | Your dos_live_… key from the portal. Sent as x-api-key; required by the hosted API. |

Minimal example

const config: DepositOSConfig = {
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourRecipientAddress",
  apiKey: "dos_live_…",
};

Optional Properties

Identity

| Property | Type | Default | Description | |---|---|---|---| | userId | string | per-browser id | A stable id for your end user. The same userId always gets back the same deposit address for a given route. Omitted, the address is tied to an id in localStorage, which does not follow the user across devices. See Funding Sources. | | integratorId | string | — | Deprecated and ignored. The integrator is fixed on the backend; use apiKey to attribute events. |

Refunds

| Property | Type | Default | Description | |---|---|---|---| | refundAddresses | { evm?: string; svm?: string } | — | Per-VM refund/sender defaults. A refund must land on the source chain's own network, so supply one per VM (e.g. your app's embedded wallets) and the user is never prompted. Falls back to destAddress when it lives on that VM, then to asking the user. |

Direction

| Property | Type | Default | Description | |---|---|---|---| | mode | "deposit" \| "transfer" \| "withdraw" | "deposit" | Where the funds land. deposit locks the recipient to destAddress; transfer lets the user enter a recipient; withdraw lets the user enter a recipient and hands the deposit address to your app to send, via onWithdrawReady. |

Token Display

| Property | Type | Default | Description | |---|---|---|---| | destTokenSymbol | string | auto-detected | Token symbol displayed in the UI (e.g., "USDC"). Detected automatically from chain data if not set. | | destTokenIcon | string | — | URL to a custom token logo image. |

Fees

| Property | Type | Default | Description | |---|---|---|---| | gizmoFeeBps | number | 0 | Platform fee in basis points (1 bps = 0.01%). | | integratorFeeBps | number | 0 | Your integrator fee in basis points. | | feeRecipient | string | — | Wallet address to receive collected fees. Required if either fee is non-zero. |

Tracking

| Property | Type | Default | Description | |---|---|---|---| | orderRef | string | — | Order reference string for correlating widget events with your internal records. |

Theming

| Property | Type | Default | Description | |---|---|---|---| | theme | "light" \| "dark" | — | Simple theme mode. Sets light or dark palette with default colors. | | primaryColor | string | — | Brand accent color as a hex value (e.g., "#7C3AED"). | | depositOSTheme | DepositOSTheme | — | Full theme object for granular control. Overrides theme and primaryColor. See Theming. |

Chain & Token Restrictions

| Property | Type | Default | Description | |---|---|---|---| | allowedChains | number[] | all chains | Restrict which source chains are available. Pass an array of chain IDs. | | allowedTokens | Record<number, string[]> | all tokens | Per-chain token allowlist. Keys are chain IDs, values are arrays of token addresses. |

Funding Methods

| Property | Type | Default | Description | |---|---|---|---| | enableWallet | boolean | true | Show the wallet-based funding option. | | enableDepositAnywhere | boolean | false | Show "deposit from anywhere" — a persistent deposit address, no wallet connection needed. | | enablePrivateMode | boolean | false | Show the private deposit funding option. | | defaultMode | "standard" \| "private" | "standard" | Which funding method is pre-selected when the widget opens. |

Footer & Branding

| Property | Type | Default | Description | |---|---|---|---| | hideFooter | boolean | false | Hide the entire widget footer. | | hideBranding | boolean | false | Hide the branding text in the footer. | | brandingUrl | string | https://deposit-os.com | Where the footer branding links to. Set it alongside customLabels.footerBranding when you rebrand the footer. | | hideTerms | boolean | false | Hide the terms of service link. | | hideSupport | boolean | false | Hide the support link. | | termsUrl | string | hosted depositOS terms | URL for the terms page linked in the footer. | | supportUrl | string | hosted depositOS support | URL for the support page linked in the footer. |

Labels & Layout

| Property | Type | Default | Description | |---|---|---|---| | customLabels | DepositOSCustomLabels | — | Custom text overrides for all widget labels. See Custom Labels. | | compactMode | boolean | false | Render a smaller widget variant for constrained layouts. |

Wallet Provider

Wallet provider environment is app-managed and not part of DepositOSConfig. Set it via frontend environment variables (for example NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID or VITE_DYNAMIC_ENVIRONMENT_ID).

Full Example

const config: DepositOSConfig = {
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xRecipientAddress",
  apiKey: "dos_live_…",
  destTokenSymbol: "USDC",
  gizmoFeeBps: 0,
  integratorFeeBps: 30,
  feeRecipient: "0xFeeAddress",
  orderRef: "order-123",
  enableWallet: true,
  enablePrivateMode: false,
  defaultMode: "standard",
  theme: "dark",
  primaryColor: "#3B82F6",
  allowedChains: [1, 42161, 10, 137, 8453],
  hideFooter: false,
  hideBranding: false,
  termsUrl: "https://yourapp.com/terms",
  supportUrl: "https://yourapp.com/support",
  compactMode: false,
  customLabels: {
    headerTitle: "Fund Your Account",
    depositButtonText: "Pay Now",
  },
};
Previous← Script TagNextFunding Sources →