Deposit modal - Rhinestone

The DepositModal component handles the full deposit flow: funding method, source chain and token selection, amount input, and cross-chain bridging.

Where the funds go

recipient (required) is the address that receives the bridged funds on the target chain. The deposit account is service-managed and derived from (recipient, targetChain, targetToken), so it doesn’t depend on which wallet the user pays from — or on a wallet existing at all. Changing the target changes the deposit address.

Connecting a wallet

Three options. The wallet is optional in all of them. The user connects their own wallet via Reown (WalletConnect). The modal manages the connection UI internally. Use this when your app has no wallet infrastructure of its own.

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"
  backendUrl={process.env.NEXT_PUBLIC_DEPOSIT_PROXY_URL}
  reownAppId="YOUR_REOWN_PROJECT_ID"
  onLifecycle={(event) => event.type === "complete" && console.log(event)}
/>

You supply one

Your app already has a wallet connected (via Privy, Dynamic, Turnkey, wagmi, or anything else). Pass its viem walletClient and the modal reuses that session instead of opening its own connect step. The modal reads the address off walletClient.account, so it cannot disagree with what your app thinks the user is connected as.

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"
  backendUrl={process.env.NEXT_PUBLIC_DEPOSIT_PROXY_URL}
  walletClient={walletClient}
  publicClient={publicClient}
  onLifecycle={(event) => event.type === "complete" && console.log(event)}
/>

Pass onRequestConnect as well if your app needs to run a login flow when the user picks the wallet row before one is connected. To disconnect a wallet the modal connected, call the exported disconnectWallet(). It no-ops with a warning if @reown/appkit isn’t installed.

walletClient={undefined} is not the same as omitting the prop. Passing it while your wallet connects tells the modal one is coming, so it waits instead of deciding there is none.

No wallet at all

QR transfer, the fiat on-ramp and exchange connect need no wallet. Supply neither walletClient nor reownAppId and the modal opens straight into whichever funding methods you enabled.

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"
  backendUrl={process.env.NEXT_PUBLIC_DEPOSIT_PROXY_URL}
  enableQrTransfer
  onLifecycle={(event) => event.type === "complete" && console.log(event)}
/>

Funding methods

Each method is a row on the modal’s home screen. When exactly one is enabled there is nothing to choose, and the modal opens directly into it.

Prop	Type	Default	Description
`enableWallet`	`boolean`	`true`	Offer the connected wallet as a source. Turn off for a flow with no wallet even when a `walletClient` or `reownAppId` is supplied
`enableQrTransfer`	`boolean`	`true`	Offer the “Transfer crypto” row — a deposit address and QR code the user sends to from anywhere
`enableFiatOnramp`	`boolean`	`false`	Offer card / bank / Apple Pay payment via Swapped’s embedded iframe
`fiatMethods`	`FiatMethodsConfig`	regional	Restrict which Swapped payment groups the on-ramp offers. Omitting it uses regional personalization
`enableExchangeConnect`	`boolean`	`false`	Offer “Connect exchange” — the user picks their CEX inside Swapped’s iframe and withdraws from it
`assetMigrations`	`AssetMigrationsConfig`	none	Offer migrating balances or DeFi positions the user already holds in a supported third-party app

enableFiatOnramp and enableExchangeConnect require Swapped keys on your backend.

Regional payment methods

Leave fiatMethods unset and the modal personalizes the Cash options for the user’s region. It renders the method list the backend resolves — provider labels, icons, limits, and one optional Popular badge — and hands the exact method the user picked to the signed Swapped widget URL. This is the recommended default: which methods exist varies by country, and a hard-coded subset can only go stale. Personalization never blocks the flow. After 500 ms the standard card, bank transfer and Apple Pay rows render; a late regional result only replaces a picker the user hasn’t touched; and any failure keeps the complete default set. Resolving the country happens at your proxy — see regional payment methods for what it needs.

A known country with no available methods is authoritative merchant data, and the modal hides the Cash option entirely. That is different from an unresolved country, which renders the defaults.

Restricting fiat payment methods

fiatMethods is a boolean map keyed by Swapped payment_group. Passing it pins the Cash rows to that exact subset and opts this modal instance out of regional personalization.

<DepositModal
  // ...required props
  enableFiatOnramp
  fiatMethods={{ creditcard: true, "apple-pay": true }}
/>

Valid keys are creditcard, bank-transfer, and apple-pay. Enabling one does not advertise the others.

An empty or all-false fiatMethods offers no payment methods, not all of them. To offer everything, omit the prop — which also turns personalization back on.

Transfer configuration

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

Prop	Type	Required	Description
`targetChain`	`Chain \| number \| "solana" \| "hypercore:spot"`	Yes	Destination chain (viem `Chain` object, chain ID, or a non-EVM identifier)
`targetToken`	`Address \| string`	Yes	Token address on the destination chain (base58 mint for Solana)
`recipient`	`Address \| string`	Yes	Where funds are delivered on the target chain (base58 address for Solana)
`defaultAmount`	`string`	No	Pre-filled deposit amount. A USD number string (e.g. `"25"`) or the sentinel `"max"` to fill the full available balance.
`sourceChain`	`Chain \| number`	No	Pre-selected source chain
`sourceToken`	`Address`	No	Pre-selected source token
`outputTokenRules`	`OutputTokenRule[]`	No	Route the deposit to a different final token based on what the user deposited
`rejectUnmapped`	`boolean`	No	Reject deposits that don’t match any routing rule instead of falling back to `targetToken`
`appBalanceUsd`	`number`	No	The user’s current in-app balance (USD). When set, the amount screen shows a “Balance after deposit” row (`appBalanceUsd + amount`).

For supported chains and tokens, see supported chains.

HyperCore destinations

HyperCore is targetChain: "hypercore:spot" (exported as HYPERCORE_SPOT_CAIP2) and accepts USDC only. The recipient can be an EOA or a smart account: deposits are credited through the MulticallHandler’s depositFor(recipient), which funds any address’s HyperCore account identically and never executes on the recipient. A HyperCore delivery names the venue it credits, because spot and perp margin are different balances. Spot is the only venue deposits are delivered to — perp margin cannot be moved back out without a signature the deposit account cannot produce.

targetChain: 1337 (HYPERCORE_CHAIN_ID) is the older spelling and still works. It resolves to the same venue and the same deposit address, so switching to HYPERCORE_SPOT_CAIP2 does not move your users’ accounts.

Earlier versions pre-screened the recipient’s bytecode and blocked a contract with an onError code of HYPERCORE_RECIPIENT_NOT_EOA. That rule never matched the orchestrator and is gone as of v0.9.0 — the code is no longer emitted.

HyperCore is also available as a deposit source in the QR / transfer flow, using the account’s own EVM address as the deposit address; a native Hyperliquid L1 spot transfer lands there.

Restricting which sources you accept

Which chains and tokens you accept is your project’s deposit whitelist, set via POST /setup and enforced by the processor when a deposit arrives. Configure it there rather than in the modal. To offer a restricted subset, use an API key whose whitelist matches.

Filtering the pickers client-side instead offers the user a source the processor then rejects, as soon as the two lists drift apart. The whitelist is the only place the restriction is enforced.

Account setup

The modal uses service-managed accounts: the deposit account is owned by Rhinestone and settles to your recipient, so there is no session key to configure and the user is never asked to sign during setup.

Prop	Type	Default	Description
`forceRegister`	`boolean`	`false`	Re-register even if the account already exists (bypasses the local cache; the call itself is idempotent)

Destination token routing

Deliver a different final token depending on what the user deposits. Pass outputTokenRules to map source deposits — matched by chain, token address, or symbol — to the output token delivered on the target chain. Deposits that don’t match any rule fall back to targetToken, or are rejected when 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 same deposit, the most specific one wins: chain + token outranks chain + symbol, which outranks token, then symbol, then chain alone. See token routing for the full rule semantics, priority order, and additional examples.

Migrate assets from other apps

Fund a deposit from balances the user already holds in a supported third-party app, with no manual transfer first. Opt in per provider via assetMigrations. See asset migrations for the provider list, Polymarket specifics, and the headless account lookup.

Package entry points

Everything is on the root entry; the subpaths exist so you only bundle what you use.

Import	Contains
`@rhinestone/deposit-modal`	All three modals, types, chain and token helpers
`@rhinestone/deposit-modal/deposit`	`DepositModal` and its types
`@rhinestone/deposit-modal/withdraw`	`WithdrawModal` and its types
`@rhinestone/deposit-modal/claim`	`ClaimModal` and its types
`@rhinestone/deposit-modal/server`	`createRefundHandler`. Server-only — holds your API key
`@rhinestone/deposit-modal/constants`	`MODAL_VERSION`, chain registry, token and explorer helpers
`@rhinestone/deposit-modal/polymarket`	`getPolymarketAccount`, headless
`@rhinestone/deposit-modal/styles.css`	Stylesheet, required

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
/>

Backdrop closing is opt-in. Set closeOnOverlayClick={true} to close the modal 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 \| "solana" \| "hypercore:spot"`	Destination chain (viem `Chain` object, chain ID, or a non-EVM identifier)
`targetToken`	`Address \| string`	Token address on the destination chain
`recipient`	`Address \| string`	Where funds are delivered on the target chain
`backendUrl`	`string`	Your backend proxy, which holds your API key

Wallet

Prop	Type	Default	Description
`reownAppId`	`string`	—	Reown project ID. Lets the modal connect a wallet itself.
`walletClient`	`WalletClient \| null`	—	A wallet your app already has connected. The modal reuses the session and reads the address off `.account`
`publicClient`	`PublicClient \| null`	—	Read client paired with `walletClient`. Defaults to the modal’s own
`enableWallet`	`boolean`	`true`	Offer the connected wallet as a funding source at all
`onRequestConnect`	`() => void`	—	Called when the modal needs the user to connect a wallet

Transfer

Prop	Type	Default	Description
`defaultAmount`	`string`	—	Pre-filled deposit amount. USD number string or the sentinel `"max"`.
`sourceChain`	`Chain \| number`	—	Pre-selected source chain
`sourceToken`	`Address`	—	Pre-selected source token
`appBalanceUsd`	`number`	—	In-app USD balance; enables the “Balance after deposit” row
`outputTokenRules`	`OutputTokenRule[]`	—	Per-deposit output token routing rules
`rejectUnmapped`	`boolean`	`false`	Reject deposits that don’t match any `outputTokenRules` entry

Funding

Prop	Type	Default	Description
`enableWallet`	`boolean`	`true`	Offer the connected wallet as a source
`enableQrTransfer`	`boolean`	`true`	Offer the “Transfer crypto” deposit-address / QR row
`enableFiatOnramp`	`boolean`	`false`	Offer fiat payment via Swapped’s iframe. Requires backend Swapped keys
`fiatMethods`	`FiatMethodsConfig`	regional	Restrict payment groups — `{ creditcard?, "bank-transfer"?, "apple-pay"? }`. Empty means none; omitted means regional
`enableExchangeConnect`	`boolean`	`false`	Offer “Connect exchange”. Requires backend Swapped keys
`assetMigrations`	`AssetMigrationsConfig`	—	Migrate balances or positions from third-party apps (e.g. `{ polymarket: true, aave: true }`)
`initialAssetMigration`	`keyof AssetMigrationsConfig`	—	Open the modal pre-routed into a migration provider (e.g. `"aave"`), skipping the home screen. Must name an enabled `assetMigrations` key.

Account

Prop	Type	Default	Description
`forceRegister`	`boolean`	`false`	Re-register even if the account already exists

Backend

Prop	Type	Default	Description
`rpcUrls`	`RpcUrlMap`	—	Per-chain RPC overrides keyed by EVM chain id or the literal `"solana"` key (e.g. `{ 8453: "https://…", solana: "https://…" }`). Applied to EVM public clients, the connected wallet, HyperEVM, and the Solana connection; chains left unset use their default RPC

Display

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

Callbacks

Prop	Type	Description
`onReady`	`() => void`	Modal initialized
`onLifecycle`	`(event: DepositLifecycleEvent) => void`	Lifecycle event — switch on `event.type` (`connected`, `submitted`, `complete`, `failed`, `balance-changed`, `smart-account-changed`)
`onError`	`(data: ErrorEventData) => void`	Error at any stage
`onEvent`	`(event: DepositAnalyticsEvent \| AnalyticsIngestFailureEvent) => void`	Deposit analytics event, or an ingest failure

See status tracking for lifecycle event payloads.

Analytics

Prop	Type	Default	Description
`enableAnalyticsIngest`	`boolean`	`true`	Sends deposit session analytics to Rhinestone in addition to `onEvent`. `false` turns collection off entirely; `onEvent` is unchanged either way

Content security policy

The modal loads chain, token and exchange logos from Rhinestone’s asset CDN. If your app sets an explicit img-src policy, it must allow the CDN:

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

A blocked image fails silently — the icon renders blank with no console error naming the policy, so this is easy to misread as a modal bug. Apps with no explicit img-src (or img-src *) need no change.

If you enable the fiat on-ramp or exchange connect, the modal embeds Swapped’s widget in an iframe, which needs frame-src:

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

The deposit, withdraw and claim modals all send session analytics to Rhinestone from the browser, so an explicit connect-src policy must allow the ingest origin:

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

That directive governs every request the modal makes, not just analytics — it must also list your own backendUrl origin and any endpoint you pass in rpcUrls. A policy assembled from the ingest origin alone breaks the modal.

A blocked ingest origin loses every event for the session, and the browser reports it to the modal as an ordinary network failure — nothing names the policy. The only signal is analytics_ingest_failure on onEvent, with reason: "network". Deposits are unaffected.

​Where the funds go

​Connecting a wallet

​The modal connects one

​You supply one

​No wallet at all

​Funding methods

​Regional payment methods

​Restricting fiat payment methods

​Transfer configuration

​HyperCore destinations

​Restricting which sources you accept

​Account setup

​Destination token routing

​Migrate assets from other apps

​Package entry points

​Display modes

​Props reference

​Required

​Wallet

​Transfer

​Funding

​Account

​Backend

​Display

​Callbacks

​Analytics

​Content security policy

Where the funds go

Connecting a wallet

The modal connects one

You supply one

No wallet at all

Funding methods

Regional payment methods

Restricting fiat payment methods

Transfer configuration

HyperCore destinations

Restricting which sources you accept

Account setup

Destination token routing

Migrate assets from other apps

Package entry points

Display modes

Props reference

Required

Wallet

Transfer

Funding

Account

Backend

Display

Callbacks

Analytics

Content security policy