Status tracking

The modal emits every state transition through a single onLifecycle callback. You switch on event.type to update your UI, trigger backend processes, or log analytics. New event variants can be added without changing the prop surface.

Deposit lifecycle

The modal initializes and fires onReady
If the user funds from a wallet, "connected" fires with the EOA address and the smartAccount the deposit lands on
The user selects a source chain, token, and amount, then confirms
The modal submits the transaction on the source chain and emits "submitted"
The bridge routes funds to the target chain. Once they arrive, the modal emits "complete"

If the bridge fails after submission, "failed" is emitted instead of "complete".

"connected" fires only for wallet funding. QR transfer, fiat on-ramp and exchange connect involve no wallet, so it never fires — use onReady if you need a “flow started” signal.

onLifecycle

onLifecycle receives a discriminated union — DepositLifecycleEvent on <DepositModal>, WithdrawLifecycleEvent on <WithdrawModal>. The two are similar but not identical; see withdraw events for the differences.

import type { DepositLifecycleEvent } from "@rhinestone/deposit-modal";

<DepositModal
  // ...required props
  onLifecycle={(event: DepositLifecycleEvent) => {
    switch (event.type) {
      case "connected":
        console.log("smart account", event.smartAccount);
        break;
      case "submitted":
        console.log("source tx", event.txHash, "on", event.sourceChain);
        break;
      case "complete":
        console.log("done", event.destinationTxHash, event.amount);
        break;
      case "failed":
        console.error("failed", event.txHash, event.error);
        break;
      case "balance-changed":
        setBalance(event.totalUsd);
        break;
      case "smart-account-changed":
        setSmartAccount({ evm: event.evm, solana: event.solana });
        break;
    }
  }}
/>

Deposit events

`event.type`	Fields	Description
`"connected"`	`address: Address`, `smartAccount: Address`	A wallet was connected as the funding source
`"submitted"`	`txHash: string`, `sourceChain: ChainId \| "unknown"`, `amount: string`, `sourceDecimals?: number`, `amountUsd?: string`	Deposit transaction submitted on the source chain
`"complete"`	`txHash: string`, `destinationTxHash?: string`, `amount: string`, `sourceChain: ChainId \| "unknown"`, `sourceToken?: string`, `sourceDecimals?: number`, `amountUsd?: string`, `targetChain: number \| "solana"`, `targetToken: string`	Tokens arrived on the target chain
`"failed"`	`txHash: string`, `error?: string`	Bridge or transfer failed after submission
`"balance-changed"`	`totalUsd: number`	The user’s total portfolio balance (USD) changed
`"smart-account-changed"`	`evm: Address \| null`, `solana: string \| null`	The resolved smart account addresses changed

amount is in the source token’s base units — divide by sourceDecimals to display it. sourceDecimals is omitted when the token isn’t recognised, which happens for a QR deposit of an unlisted token. amountUsd is the USD value as entered in the modal. It is omitted for flows with no amount input: QR transfer, fiat on-ramp, and exchange connect.

sourceChain: "unknown" is deposit-only. When a webhook-detected deposit arrives without chain or token information, sourceChain is "unknown" and sourceToken is undefined — handle this branch so you don’t pick the wrong explorer URL.

Withdraw events

WithdrawLifecycleEvent carries the same type values minus "balance-changed" and "smart-account-changed". Its txHash is Hex, sourceChain is always a number, sourceToken / targetToken are Address, and "submitted" adds an accountAddress: Address field. "connected" means the deposit account for the chosen target is registered and fundable, not that a wallet connected.

Claim events

ClaimLifecycleEvent is a separate union — lookup, refund_requested, complete, failed. See claim modal.

onReady

Fires once when the modal is initialized and ready for interaction. No payload.

onReady={() => console.log("modal ready")}

onError

Fires on errors at any stage — wallet connection, transaction signing, bridge setup — that prevent the deposit from being submitted. Distinct from the "failed" lifecycle event, which covers failures after the source transaction confirms.

onError={(data) => console.error(`[${data.code}] ${data.message}`)}

Field	Type	Description
`message`	`string`	Error description
`code`	`string \| undefined`	Error code, if available

Codes

`code`	Meaning
`WITHDRAW_MISSING_SEND_TRANSACTION`	`<WithdrawModal>` opened without an `onSendTransaction` function
`WITHDRAW_REGISTER_FAILED`	Registering the withdrawal’s deposit account failed
`WITHDRAW_FLOW_ERROR`	The withdrawal failed after the form was submitted
`CLAIM_LOOKUP_FAILED`	`<ClaimModal>` could not look up the pasted transaction hash
`CLAIM_FAILED`	The refund request failed
`SWAPPED_CONNECT_EXCHANGES_FAILED`	The exchange list could not be fetched

Errors without a code carry only message. For bridge-level codes, see deposit processing error codes.

Error handling

Stage	Signal	Typical causes
Wallet connection	`onError`	User rejected connection, network error
Transaction signing	`onError`	User rejected transaction, insufficient gas
After submission	`onLifecycle` `"failed"`	Bridge failure, timeout, price deviation
Any stage	`onError`	Unexpected errors

After the source chain transaction confirms, the deposit service may retry automatically before the "failed" event fires.

Analytics

The onEvent callback fires on granular user interactions for your analytics pipeline. Its payload type is DepositAnalyticsEvent, WithdrawAnalyticsEvent, or ClaimAnalyticsEvent.

import type { DepositAnalyticsEvent } from "@rhinestone/deposit-modal";

onEvent={(event: DepositAnalyticsEvent) => {
  analytics.track(event.type, event);
}}

Events include modal views (*_open) and CTA clicks (*_cta_click) at each step of the flow, with contextual properties like selected token, chain, and amount.

Widget

API

Deposit lifecycle

onLifecycle

Deposit events

Withdraw events

Claim events

onReady

onError

Codes

Error handling

Analytics

​Deposit lifecycle

​onLifecycle

​Deposit events

​Withdraw events

​Claim events

​onReady

​onError

​Codes

​Error handling

​Analytics

Deposit lifecycle

onLifecycle

Deposit events

Withdraw events

Claim events

onReady

onError

Codes

Error handling

Analytics