Claim modal - Rhinestone

The ClaimModal returns a failed or rejected EVM deposit to the user, on the chain it came from. The user pastes the deposit’s transaction hash, the modal looks it up, and the user signs to authorize where the funds go. There is no source chain to pick — the hash is looked up across every chain, so a deposit that landed on a chain your deposit flow doesn’t offer is still claimable.

On the ./claim subpath. Applies to deposits in failed or rejected status. See troubleshooting for the operator-side equivalent in the dashboard.

How authorization works

The deposit’s recipient — the in-app wallet the funds were headed to — signs an EIP-712 struct naming the deposit and the destination. The service verifies that signature against the same recipient before moving anything. That signature is the authorization, so this needs no backend of your own. The request goes from the browser through your proxy, which contributes only your project API key. That key cannot move funds through this route without a signature, so there is nothing for a page to borrow.

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

<ClaimModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  backendUrl={process.env.NEXT_PUBLIC_DEPOSIT_PROXY_URL}
  signRecovery={({ typedData }) => wallet.signTypedData(typedData)}
/>

The modal never runs a connect step — it has no wallet UI and asks for no provider. It calls signRecovery and expects a signature back. For an embedded wallet that is headless, so the user sees a single confirmation at most.

The signer is the deposit’s recipient, never the deposit account. Deposit accounts are service-managed and hold no user key, so nothing can sign for them.

Your proxy must forward POST /deposits/recover alongside the GET /deposits used for the lookup. Both are in the reference proxy.

Signing

Return whatever the recipient address’s own verifier accepts. signRecovery receives the exact typed data to sign, so you never construct it yourself.

`recipient` is	Return
An embedded EOA (Privy, Turnkey, Dynamic)	`signTypedData`, the raw 65-byte result
A deployed smart account	A signature valid under its ERC-1271 `isValidSignature`
A smart account not yet deployed	The same, wrapped per ERC-6492

// Embedded EOA — the common case.
signRecovery={({ typedData }) => wallet.signTypedData(typedData)}

For a smart account, a raw owner signature is usually not enough. A Safe expects its own message wrapping, so go through your account SDK rather than signing with the owner key directly.

An undeployed account can still be verified, because an ERC-6492 wrapper carries the account’s factory and factory data. That makes the check work without the account existing on chain yet — which matters, since a deposit can fail before the user’s account is ever deployed.

import { SignatureErc6492 } from "ox/erc6492";

signRecovery={async ({ typedData }) => {
  const signature = await account.signTypedData(typedData);
  if (await account.isDeployed()) return signature;
  return SignatureErc6492.wrap({
    to: factory,        // the factory that will deploy the account
    data: factoryData,  // the calldata that deploys it
    signature,
  });
}}

ox is already a dependency of viem, so this adds nothing to your install.

What the user signs

domain:      { name: "Rhinestone Deposit Recovery", version: "1" }
primaryType: "RecoverDeposit"
types: { RecoverDeposit: [
  { name: "depositId",   type: "uint256" },
  { name: "destination", type: "address" },
]}

Two fields, both meaningful to the person signing: which deposit, and where the money goes. The destination is inside the signature, which is the property worth understanding. The service cannot pay anywhere other than the address the user signed for, so a compromised page cannot redirect the funds — and your success screen can state where they went without trusting a response to echo it back. The signature is verified on the deposit’s target chain, where the recipient wallet lives, not the source chain the funds sit on. For a smart account with different owners per chain, its target-chain owners are the ones who can authorize.

A signature stays valid until the deposit is claimed — there is no expiry. Replay is already closed, because claiming moves the deposit out of failed/rejected and a second attempt is rejected. But do not persist a signature: treat it as single-use and discard it once the request returns.

Handling failures

The response carries a machine-readable code. Switch on that rather than the HTTP status — the code is the contract, and the correct advice differs between codes that share a status.

`code`	Means	Retry?
`DEPOSIT_NOT_RECOVERABLE`	Not in `failed`/`rejected` — often already claimed	No
`RECOVERY_UNSUPPORTED`	The deposit has no recipient to verify against, or a non-EVM chain on either side	No
`SIGNATURE_INVALID`	The recipient’s verifier rejected these bytes	No — signing again the same way won’t help
`VERIFICATION_UNAVAILABLE`	The on-chain check couldn’t run	Yes, and without re-signing
`REFUND_RECONCILIATION_REQUIRED`	Funds may be in flight; needs an operator	No
`REFUND_FAILED`	The transfer didn’t complete	Yes

The modal maps these to copy and to whether it offers a retry, so you get this for free. Handle them yourself only if you drive your own UI.

Never retry REFUND_RECONCILIATION_REQUIRED. The funds may already be moving, and the deposit needs an operator either way — contact support with the deposit.

When the user can’t sign

Some recipients have no key to sign with: a wallet the user has lost, or a recipient your app controls rather than the user. For those, @rhinestone/deposit-modal/server exports createRefundHandler, which authorizes on your say-so instead of a signature — you decide who the caller is, and it verifies the deposit belongs to them before spending your API key.

// app/api/refund/route.ts
import { createRefundHandler } from "@rhinestone/deposit-modal/server";

export const POST = createRefundHandler({
  apiKey: process.env.RHINESTONE_API_KEY!,
  async authorize(request) {
    const session = await getSession(request);
    return session ? { depositRecipient: session.depositRecipient } : null;
  },
});

authorize returns the deposit recipient the caller owns, or null to reject with 401. Add refundDestination to pin where the money goes rather than letting the request choose. depositRecipient never decides the destination — the handler lists deposits settling to it and rejects a txHash that isn’t among them. It returns a (Request) => Promise<Response>, so it mounts in any fetch-based runtime: Next.js route handlers, Hono, Bun.serve, Cloudflare Workers.

Import from @rhinestone/deposit-modal/server only — it holds your API key and must never reach the browser. ClaimModal does not call this route; drive your own UI against it.

Never refund to an exchange deposit address. Exchanges don’t credit arbitrary incoming transfers, so the funds may be lost. This is why the modal never defaults the destination to the deposit’s sender.

Props reference

Required

Prop	Type	Description
`isOpen`	`boolean`	Controls modal visibility
`onClose`	`() => void`	Called when the user closes the modal
`signRecovery`	`(payload) => Promise<Hex>`	Signs the authorization. Throwing is treated as the user declining, and is retryable
`backendUrl`	`string`	Your proxy, which holds your API key

signRecovery receives:

Field	Type	Description
`typedData`	`TypedDataDefinition`	Sign this exactly — pass it to `signTypedData` or your account SDK
`signer`	`Address`	The address whose signature is verified: the deposit’s `recipient`
`depositId`	`string`	The deposit being recovered, for your own logging or confirmation UI
`destination`	`Address`	Where the funds will go. Covered by the signature

Prefills

Prop	Type	Default	Description
`defaultTxHash`	`string`	—	Prefills the lookup field
`defaultRefundDestination`	`Address`	—	Prefills the destination as an editable seed. Left empty otherwise

Backend

Prop	Type	Default	Description
`rpcUrls`	`RpcUrlMap`	Chain defaults	Per-chain RPC overrides keyed by EVM chain id

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
`uiConfig`	`DepositModalUIConfig`	—	UI configuration
`debug`	`boolean`	`false`	Enable debug logging

Callbacks

Prop	Type	Description
`onReady`	`() => void`	Modal initialized
`onLifecycle`	`(event: ClaimLifecycleEvent) => void`	Claim lifecycle — switch on `event.type`
`onError`	`(data: ErrorEventData) => void`	Error at any stage
`onEvent`	`(event: ClaimAnalyticsEvent) => void`	Analytics event

Lifecycle events

`event.type`	Payload	Fired when
`lookup`	`txHash`, `matches`	The pasted hash was looked up. `matches` is how many deposits it resolved to
`refund_requested`	`account`, `destination`, `chain`	The signed request was submitted
`complete`	`txHash`, `account`, `destination`, `chain`, `token`, `amount`	The recovery succeeded
`failed`	`status`, `error`	It failed. `status` is the HTTP status, or `0` if the service was unreachable

<ClaimModal
  // ...required props
  onLifecycle={(event) => {
    if (event.type === "complete") {
      trackRefund(event.txHash, event.amount);
    }
  }}
/>

ClaimLifecycleEvent shares no variants with the deposit or withdraw unions, so don’t reuse a handler across them.

​How authorization works

​Signing

​What the user signs

​Handling failures

​When the user can’t sign

​Props reference

​Required

​Prefills

​Backend

​Display

​Callbacks

​Lifecycle events

How authorization works

Signing

What the user signs

Handling failures

When the user can’t sign

Props reference

Required

Prefills

Backend

Display

Callbacks

Lifecycle events