Deposit modal

The DepositModal component handles the full deposit flow: wallet connection, source chain and token selection, amount input, and cross-chain bridging. It supports three wallet integration modes depending on how your app manages wallets.

recipient vs dappAddress

Two props look similar but serve different purposes:

recipient (required) — the address that receives the bridged funds on the target chain. This is a pure delivery target.
dappAddress (embedded wallet & QR modes) — the address that owns the deposit. The modal uses it to derive the smart account and, by default, as the delivery target. It is the user’s identity in the flow, not a destination.

In external wallet mode, the connected wallet is the owner, so only recipient is needed. In embedded and QR modes, you must pass dappAddress because the modal has no other way to know who owns the deposit.

Integration modes

External wallet

The user connects their own wallet via Reown (WalletConnect). The modal manages the wallet connection UI internally. Use this when your app doesn’t have existing wallet infrastructure. Pass a reownAppId to enable external wallet connection.

import { DepositModal } from "@rhinestone/deposit-modal";
import "@rhinestone/deposit-modal/styles.css";

<DepositModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  targetChain={8453}
  targetToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  recipient="0xYOUR_RECIPIENT_ADDRESS"
  reownAppId="YOUR_REOWN_PROJECT_ID"
  onDepositComplete={(data) => console.log(data)}
/>

Embedded wallet

Your app manages the wallet (e.g. via Privy, Dynamic, or Turnkey) and passes the owner address to the modal. The modal skips its own wallet connection UI and uses your app’s wallet context. Pass dappAddress with the wallet owner address, and onRequestConnect to trigger your app’s login flow when the modal needs a connected wallet.

import { DepositModal } from "@rhinestone/deposit-modal";
import "@rhinestone/deposit-modal/styles.css";

<DepositModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  targetChain={8453}
  targetToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  recipient="0xYOUR_RECIPIENT_ADDRESS"
  dappAddress={embeddedWalletAddress}
  onRequestConnect={() => login()}
  onDepositComplete={(data) => console.log(data)}
/>

QR code deposit

The modal displays a deposit address and QR code. The user sends funds from any wallet externally — no wallet connection is required inside the modal. Pass dappAddress without onRequestConnect or reownAppId.

import { DepositModal } from "@rhinestone/deposit-modal";
import "@rhinestone/deposit-modal/styles.css";

<DepositModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  targetChain={8453}
  targetToken="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  recipient="0xYOUR_RECIPIENT_ADDRESS"
  dappAddress={ownerAddress}
  onDepositComplete={(data) => console.log(data)}
/>

Transfer configuration

Control the deposit destination and optionally pre-fill source parameters.

Prop	Type	Required	Description
`targetChain`	`Chain \| number`	Yes	Destination chain (viem `Chain` object or chain ID)
`targetToken`	`Address`	Yes	Token address on the destination chain
`recipient`	`Address`	Yes	Where funds are delivered on the target chain
`defaultAmount`	`string`	No	Pre-filled deposit amount
`sourceChain`	`Chain \| number`	No	Pre-selected source chain
`sourceToken`	`Address`	No	Pre-selected source token
`allowedRoutes`	`RouteConfig`	No	Restrict available source chains and tokens

The allowedRoutes prop accepts { sourceChains?: number[], sourceTokens?: string[] } to limit what the user can select. For supported chains and tokens, see supported chains.

Session configuration

Sessions allow the widget to execute bridging on behalf of the user’s smart account. These props control session behavior.

Prop	Type	Default	Description
`sessionChainIds`	`number[]`	All supported chains	Restrict which chains get session keys
`forceRegister`	`boolean`	`false`	Force session re-creation even if the account is already registered
`waitForFinalTx`	`boolean`	`true`	Wait for destination chain confirmation before firing `onDepositComplete`. When `false`, resolves after the bridge is submitted.

Post-bridge actions

Execute actions on the destination chain after bridging completes. Use this for automated swaps into vault tokens or other DeFi positions.

<DepositModal
  // ...required props
  postBridgeActions={[
    {
      type: "orderbook-swap",
      contract: "0xSWAP_CONTRACT_ADDRESS",
      outputToken: "0xVAULT_TOKEN_ADDRESS",
    },
  ]}
/>

The flow becomes: deposit on source chain → bridge to target chain → swap into the output token → deliver to the recipient.

Display modes

By default, the component renders as a centered modal overlay with a backdrop. Set inline={true} to render it without the overlay, fitting into your page layout.

<DepositModal
  isOpen={true}
  onClose={() => {}}
  inline={true}
  // ...other props
/>

Set closeOnOverlayClick={false} to prevent the modal from closing when the user clicks outside it.

Props reference

Required

Prop	Type	Description
`isOpen`	`boolean`	Controls modal visibility
`onClose`	`() => void`	Called when the user closes the modal
`targetChain`	`Chain \| number`	Destination chain (viem `Chain` object or chain ID)
`targetToken`	`Address`	Token address on the destination chain
`recipient`	`Address`	Where funds are delivered on the target chain

Wallet

Prop	Type	Default	Description
`reownAppId`	`string`	—	Reown project ID. Enables external wallet connection.
`dappAddress`	`Address`	—	Owner address for embedded wallet or QR code flows
`dappWalletClient`	`WalletClient`	—	Host-provided viem wallet client for signing
`dappPublicClient`	`PublicClient`	—	Host-provided viem public client
`onRequestConnect`	`() => void`	—	Called when the modal needs the user to connect a wallet
`connectButtonLabel`	`string`	—	Custom label for the connect button

Transfer

Prop	Type	Default	Description
`defaultAmount`	`string`	—	Pre-filled deposit amount
`sourceChain`	`Chain \| number`	—	Pre-selected source chain
`sourceToken`	`Address`	—	Pre-selected source token
`allowedRoutes`	`RouteConfig`	—	`{ sourceChains?, sourceTokens? }` to restrict selection
`postBridgeActions`	`PostBridgeAction[]`	—	Actions to execute after bridging

Session

Prop	Type	Default	Description
`sessionChainIds`	`number[]`	All supported	Chain IDs for session key creation
`forceRegister`	`boolean`	`false`	Force session re-creation
`waitForFinalTx`	`boolean`	`true`	Wait for destination chain confirmation
`signerAddress`	`Address`	Default signer	Session signer address
`rhinestoneApiKey`	`string`	—	API key for account setup

Backend

Prop	Type	Default	Description
`backendUrl`	`string`	Rhinestone production URL	URL of your deposit-widget-backend instance

Display

Prop	Type	Default	Description
`inline`	`boolean`	`false`	Render without modal overlay
`closeOnOverlayClick`	`boolean`	`true`	Close modal on backdrop click
`className`	`string`	—	CSS class for the modal container
`theme`	`DepositModalTheme`	—	Theme configuration
`branding`	`DepositModalBranding`	—	Branding configuration
`uiConfig`	`DepositModalUIConfig`	—	UI configuration
`debug`	`boolean`	`false`	Enable debug logging

Callbacks

Prop	Type	Description
`onReady`	`() => void`	Modal initialized
`onConnected`	`(data: ConnectedEventData) => void`	Smart account created
`onDepositSubmitted`	`(data: DepositSubmittedEventData) => void`	Deposit transaction submitted on source chain
`onDepositComplete`	`(data: DepositCompleteEventData) => void`	Tokens arrived on target chain
`onDepositFailed`	`(data: DepositFailedEventData) => void`	Bridge or transfer failed
`onError`	`(data: ErrorEventData) => void`	Error at any stage
`onEvent`	`(event: DepositEvent) => void`	Analytics event

See status tracking for callback payload types and the deposit lifecycle.

Solana

Prop	Type	Default	Description
`enableSolana`	`boolean`	`true`	Enable Solana wallet support and QR flows
`solanaRpcUrl`	`string`	Solana mainnet	Custom Solana RPC endpoint

API

Widget

API Reference

recipient vs dappAddress

Integration modes

External wallet

Embedded wallet

QR code deposit

Transfer configuration

Session configuration

Post-bridge actions

Display modes

Props reference

Required

Wallet

Transfer

Session

Backend

Display

Callbacks

Solana

API

Widget

API Reference

​recipient vs dappAddress

​Integration modes

​External wallet

​Embedded wallet

​QR code deposit

​Transfer configuration

​Session configuration

​Post-bridge actions

​Display modes

​Props reference

​Required

​Wallet

​Transfer

​Session

​Backend

​Display

​Callbacks

​Solana

recipient vs dappAddress

Integration modes

External wallet

Embedded wallet

QR code deposit

Transfer configuration

Session configuration

Post-bridge actions

Display modes

Props reference

Required

Wallet

Transfer

Session

Backend

Display

Callbacks

Solana