Widget configuration

DepositModal handles funding method selection, source chain and token selection, amount input, and cross-chain routing. Complete the widget quickstart and backend setup before configuring optional behavior.

Destination

recipient is the address that receives funds on the target chain. The service-managed deposit account is derived from (recipient, targetChain, targetToken), so it does not depend on the payment wallet. Changing the target changes the deposit address. For a checkout, pass an order-specific account salt instead. Each order then has its own deposit address.

Prop	Type	Required	Description
`targetChain`	`Chain \| number \| "solana" \| "hypercore:spot"`	Yes	Destination chain as a viem `Chain`, chain ID, or non-EVM identifier
`targetToken`	`Address \| string`	Yes	Token on the destination chain; use a base58 mint for Solana
`recipient`	`Address \| string`	Yes	Address receiving funds; use a base58 address for Solana
`defaultAmount`	`string`	No	Pre-filled USD amount, or `"max"` for the full available balance
`payment`	`PaymentConfig`	—	Checkout for one order: `{ salt: Hex, amount: string }`. Amount is destination token base units; salt is the order’s registered account salt.
`sourceChain`	`Chain \| number`	No	Pre-selected source chain
`sourceToken`	`Address`	No	Pre-selected source token
`outputTokenRules`	`OutputTokenRule[]`	No	Route deposits to different final tokens based on the source deposit
`rejectUnmapped`	`boolean`	No	Reject an unmatched routing input instead of using `targetToken`
`appBalanceUsd`	`number`	No	Current in-app USD balance; shows the balance after deposit

For supported destinations and assets, see supported chains and tokens.

Checkout payments

Register a managed account for each order on your server with a unique 32-byte salt. Store the returned evmDepositAddress with the order, then pass the same salt and the required destination amount to the modal:

<DepositModal
  // ...required props, including the order's target and recipient
  payment={{ salt: order.salt, amount: order.amountBaseUnits }}
/>

payment.amount is an integer string in destination token base units. It is not a USD amount. The salt replaces the modal’s normal (recipient, targetChain, targetToken) account derivation, so it must match the salt used in managed account registration. The modal displays a fixed order amount and withholds the recipient’s deposit history from the payer. On the EVM wallet path, the modal asks POST /quotes/preview for an exactOut quote and uses its input.amount as the source amount to send. The proxy must forward that route to a processor that supports exactOut; an older processor cannot price the checkout. The quote is indicative, and a QR, exchange, or card payer can send a different amount. Reconcile deposits against the order’s account using processor webhooks or GET /deposits?account=<orderAccount>. Compare the delivered destination amount with the order amount before marking it paid. The modal’s complete lifecycle event also carries destinationAmount in destination token base units when available.

Account setup

The widget uses service-managed accounts. Rhinestone owns the deposit account and settles to your recipient, so there is no session key to configure and the user is not asked to sign during setup.

Prop	Type	Default	Description
`forceRegister`	`boolean`	`false`	Re-register even when the account is cached. Registration remains idempotent

Restrict accepted sources

Your project’s deposit whitelist controls the chains and tokens the processor accepts. Configure it through project setup rather than filtering the widget’s source picker.

A client-side filter can drift from the processor configuration and offer a source the processor rejects. The project whitelist is the enforced source of truth.

Funding methods

Each enabled method appears on the widget home screen. When exactly one is enabled, the widget skips the chooser and opens that flow directly.

Prop	Type	Default	Guide
`enableWallet`	`boolean`	`true`	Deposit from a wallet
`enableQrTransfer`	`boolean`	`true`	Deposit addresses and QR codes
`enableFiatOnramp`	`boolean`	`false`	Accept fiat payments
`fiatMethods`	`FiatMethodsConfig`	Regional	Payment methods and availability
`enableExchangeConnect`	`boolean`	`false`	Connect an exchange
`assetMigrations`	`AssetMigrationsConfig`	None	Asset migrations
`initialAssetMigration`	`keyof AssetMigrationsConfig`	—	Open directly into an enabled migration provider

Fiat onramps and exchange connect require Swapped routes and credentials on your backend proxy.

Output token routing

Pass outputTokenRules to choose the final token based on the source deposit. Rules can match chain, token address, or symbol. Unmatched deposits use targetToken unless rejectUnmapped is true.

<DepositModal
  // ...required props
  targetToken="0xFALLBACK_TOKEN_ADDRESS"
  outputTokenRules={[
    {
      match: { symbol: "USDC" },
      outputToken: "0x7f5c764cbc14f9669b88837ca1490cca17c31607",
    },
    {
      match: { symbol: "ETH" },
      outputToken: "0x4200000000000000000000000000000000000006",
    },
  ]}
/>

When several rules match, the most specific wins: chain + token, then chain + symbol, token, symbol, and chain. See token routing for full semantics and examples.

Non-EVM destinations

Solana

Use targetChain="solana", a base58 mint as targetToken, and a base58 recipient. rpcUrls accepts a literal solana key when you need to override the default connection.

HyperCore destinations

Use targetChain="hypercore:spot", exported as HYPERCORE_SPOT_CAIP2. HyperCore accepts USDC only. recipient can be an EOA or smart account: delivery calls the MulticallHandler’s depositFor(recipient), which funds either address type without executing on the recipient. A HyperCore destination names the venue it credits. Spot and perp margin are separate balances; deposits support spot only because the deposit account cannot produce the signature required to move funds back out of perp margin.

targetChain: 1337, exported as HYPERCORE_CHAIN_ID, is the older spelling and still resolves to the same venue and deposit address. Migrating to HYPERCORE_SPOT_CAIP2 does not move user accounts.

Earlier versions pre-screened recipient bytecode and could emit HYPERCORE_RECIPIENT_NOT_EOA. That check did not match orchestrator behavior and was removed in v0.9.0.

HyperCore is also available as a transfer source. The address and QR flow uses the account’s EVM address as the deposit address; a native Hyperliquid L1 spot transfer lands there.

Display modes

The widget renders as a centered overlay by default. Set inline={true} to place it in your page layout without a backdrop.

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

Backdrop closing is opt-in with closeOnOverlayClick={true}. Configure visual appearance in theming and customization.

Package entry points

Everything is exported from the root. Subpaths let you bundle only what you use.

Import	Contains
`@rhinestone/deposit-modal`	Both modals, types, chain helpers, and token helpers
`@rhinestone/deposit-modal/deposit`	`DepositModal` and its types
`@rhinestone/deposit-modal/withdraw`	`WithdrawModal` and its types
`@rhinestone/deposit-modal/server`	`createRefundHandler`; server-only because it holds your API key
`@rhinestone/deposit-modal/constants`	`MODAL_VERSION`, chain registry, token helpers, and explorer helpers
`@rhinestone/deposit-modal/polymarket`	Headless `getPolymarketAccount`
`@rhinestone/deposit-modal/styles.css`	Required stylesheet

Props reference

Required

Prop	Type	Description
`isOpen`	`boolean`	Controls widget visibility
`onClose`	`() => void`	Called when the user closes the widget
`targetChain`	`Chain \| number \| "solana" \| "hypercore:spot"`	Destination chain
`targetToken`	`Address \| string`	Destination token
`recipient`	`Address \| string`	Address receiving funds on the destination
`backendUrl`	`string`	Your backend proxy

Wallet

Prop	Type	Default	Description
`reownAppId`	`string`	—	Reown project ID; lets the widget connect a wallet
`walletClient`	`WalletClient \| null`	—	Wallet your app already connected; the widget reads `.account`
`publicClient`	`PublicClient \| null`	—	Read client paired with `walletClient`; defaults to the widget client
`enableWallet`	`boolean`	`true`	Offer wallet funding
`onRequestConnect`	`() => void`	—	Called when the widget needs your app to connect a wallet

See deposit from a wallet for widget-managed, app-supplied, and loading-state behavior.

Transfer

Prop	Type	Default	Description
`defaultAmount`	`string`	—	Pre-filled USD amount or `"max"`
`payment`	`PaymentConfig`	—	Checkout for one order: `{ salt: Hex, amount: string }`. Amount is destination token base units; salt is the order’s registered account salt.
`sourceChain`	`Chain \| number`	—	Pre-selected source chain
`sourceToken`	`Address`	—	Pre-selected source token
`appBalanceUsd`	`number`	—	In-app USD balance used for the balance-after-deposit row
`outputTokenRules`	`OutputTokenRule[]`	—	Per-deposit output token rules
`rejectUnmapped`	`boolean`	`false`	Reject deposits that match no output rule

Funding

Prop	Type	Default	Description
`enableWallet`	`boolean`	`true`	Offer a connected wallet as a source
`enableQrTransfer`	`boolean`	`true`	Offer the address and QR transfer flow
`enableFiatOnramp`	`boolean`	`false`	Offer fiat payment through Swapped
`fiatMethods`	`FiatMethodsConfig`	Regional	Restrict to `{ creditcard?, "bank-transfer"?, "apple-pay"? }`; empty means none
`enableExchangeConnect`	`boolean`	`false`	Offer Connect exchange through Swapped
`assetMigrations`	`AssetMigrationsConfig`	—	Enable supported migration providers
`initialAssetMigration`	`keyof AssetMigrationsConfig`	—	Open directly into an enabled migration provider

Account

Prop	Type	Default	Description
`forceRegister`	`boolean`	`false`	Re-register even when the account is cached

Backend

Prop	Type	Default	Description
`rpcUrls`	`RpcUrlMap`	Chain defaults	RPC overrides keyed by EVM chain ID or `solana`; applies to EVM clients, connected wallets, HyperEVM, and Solana

Display

Prop	Type	Default	Description
`inline`	`boolean`	`false`	Render without the overlay
`closeOnOverlayClick`	`boolean`	`false`	Close when the backdrop is clicked
`className`	`string`	—	CSS class for the widget container
`theme`	`DepositModalTheme`	—	Theme configuration
`uiConfig`	`DepositModalUIConfig`	—	UI configuration
`debug`	`boolean`	`false`	Enable debug logging

Recovery

Prop	Type	Default	Description
`signRecovery`	`SignRecovery`	—	Enable signed recovery from history; omit for read-only history

Callbacks

Prop	Type	Description
`onReady`	`() => void`	Widget initialized
`onLifecycle`	`(event: DepositLifecycleEvent) => void`	Deposit state transitions; see callbacks and error handling
`onError`	`(data: ErrorEventData) => void`	Error at any stage
`onEvent`	`(event: DepositAnalyticsEvent \| ClaimAnalyticsEvent \| AnalyticsIngestFailureEvent) => void`	Funnel events and ingest diagnostics; see analytics

Analytics

Prop	Type	Default	Description
`enableAnalyticsIngest`	`boolean`	`true`	Send session analytics to Rhinestone. `false` disables collection without changing `onEvent`

Content security policy

The widget loads chain, token, and exchange logos from Rhinestone’s asset CDN. Apps with an explicit img-src must allow it:

img-src 'self' data: https://s3.rhinestone.dev;

A blocked image fails silently and renders blank. Apps without an explicit img-src, or with img-src *, need no change. Fiat onramps and Connect exchange embed Swapped in an iframe, so those flows also need:

frame-src https://widget.swapped.com https://sandbox.swapped.com https://connect.swapped.com;

Deposit and withdraw sessions send analytics from the browser. An explicit connect-src must include Rhinestone, your proxy, and every RPC override:

connect-src 'self' https://v1.orchestrator.rhinestone.dev https://your-proxy.example.com;

That directive controls every widget request, not only analytics. A blocked ingest origin does not interrupt deposits, but it drops analytics and reports an analytics_ingest_failure event with reason: "network"; see analytics.

​Destination

​Checkout payments

​Account setup

​Restrict accepted sources

​Funding methods

​Output token routing

​Non-EVM destinations

​Solana

​HyperCore destinations

​Display modes

​Package entry points

​Props reference

​Required

​Wallet

​Transfer

​Funding

​Account

​Backend

​Display

​Recovery

​Callbacks

​Analytics

​Content security policy

Destination

Checkout payments

Account setup

Restrict accepted sources

Funding methods

Output token routing

Non-EVM destinations

Solana

HyperCore destinations

Display modes

Package entry points

Props reference

Required

Wallet

Transfer

Funding

Account

Backend

Display

Recovery

Callbacks

Analytics

Content security policy