Simple Deposit — React API

React API reference for the Simple Deposit: DepositProvider, hooks, and UI components.

DepositProvider

Wraps your app and manages the deposit lifecycle. Handles Auth Core context internally.

import { DepositProvider, CHAIN } from '@particle-network/simple-deposit/react';

<DepositProvider config={{
  destination: { chainId: CHAIN.BASE },
  autoSweep: true,
  minValueUSD: 1,
}}>
  <App />
</DepositProvider>

Config

Property	Type	Default	Description
destination.chainId	number	—	Required. Destination chain (use CHAIN constant).
destination.address	string	Owner’s EOA	Custom sweep destination address.
destination.token	TokenType	'USDC'	Token delivered to the destination (sweep converts to it; onramp buys it). See Destination tokens.
supportedTokens	TokenType[]	All	Tokens to watch.
supportedChains	number[]	All 17 chains	Chains to watch.
autoSweep	boolean	true	Auto-sweep detected deposits.
minValueUSD	number	0.50	Minimum USD value to trigger sweep.
pollingIntervalMs	number	3000	Balance check interval (ms).
refund	RefundConfig	{ enabled: false }	Auto-refund config (experimental).
notifications	boolean | DepositNotificationsProps	false	Show in-app deposit notifications. Set true to auto-mount the toaster, or pass props to configure it.
funding	FundingConfig	{ enabled: false }	Let users fund the deposit address from a connected browser wallet. When enabled, DepositWidget shows a “Fund from wallet” toggle.
fundingWallet	{ evm?: { provider, address } }	—	Reuse your app’s already-connected wallet as the funding source (skips the connect step).
onramp	OnrampConfig	{ enabled: false }	Let users buy crypto with fiat (card / Apple Pay / bank) via RampNow, delivered straight to the destination. When enabled, DepositWidget shows a “Buy” toggle.
uaProjectId	string	SDK default	Particle project ID for UA operations only.

---

useDeposit

Primary hook. Pass ownerAddress to trigger auto-connection and start watching for deposits.

import { useDeposit } from '@particle-network/simple-deposit/react';

const {
  isReady, depositAddresses, pendingDeposits,
  sweep, status, currentDestination,
} = useDeposit({ ownerAddress: '0x...' });

Options

Property	Type	Description
ownerAddress	string | undefined	User’s wallet address. Pass to trigger connection.

Return Value

Property	Type	Description
isConnecting	boolean	SDK is initializing.
isConnected	boolean	Auth Core connected.
isReady	boolean	Client ready for operations.
error	Error | null	Last error.
disconnect	() => Promise<void>	Disconnect and cleanup.
status	ClientStatus	Current client status.
depositAddresses	DepositAddresses | null	EVM and Solana deposit addresses.
pendingDeposits	DetectedDeposit[]	Detected but unsent deposits.
recentActivity	ActivityItem[]	Activity history.
sweep	(id?: string) => Promise<SweepResult[]>	Trigger sweep (all or by ID).
setDestination	(dest: DestinationConfig) => void	Change destination at runtime.
currentDestination	{ address: string; chainId: number } | null	Current destination.

---

useDepositContext

Access the full context including recovery and refund methods. Returns everything from useDeposit plus:

import { useDepositContext } from '@particle-network/simple-deposit/react';

const { client, stuckFunds, recoverFunds, refundDeposit } = useDepositContext();

Extended Properties

Property	Type	Description
client	DepositClient | null	Underlying client instance.
ownerAddress	string | null	User’s wallet.
intermediaryAddress	string | null	JWT wallet.
connect	(address: string) => Promise<void>	Manual connect.
startWatching / stopWatching	() => void	Control balance polling.
stuckFunds	DetectedDeposit[]	Stuck funds list.
isRecovering	boolean	Recovery in progress.
getStuckFunds	() => Promise<DetectedDeposit[]>	Refresh stuck funds.
recoverFunds	() => Promise<RecoveryResult[]>	Recover all funds.
isRefunding	boolean	Refund in progress.
refundDeposit	(id: string) => Promise<RefundResult>	Refund specific deposit.
refundAll	() => Promise<RefundResult[]>	Refund all pending.
canRefund	(id: string) => Promise<{ eligible: boolean; reason?: string }>	Check eligibility.
refundConfig	RefundConfig	Current refund config.

---

useOnramp

Drive a fiat purchase (buy crypto with fiat via RampNow) from a fully custom UI. Returns nothing useful until onramp.enabled is set on the provider.

import { useOnramp } from '@particle-network/simple-deposit/react';

const { open, status, error, enabled, supported } = useOnramp();

// Render your own button:
<button disabled={!enabled || !supported} onClick={() => open({ amount: 100 })}>
  Buy
</button>

Return Value

Property	Type	Description
open	(opts?: { amount?: number }) => Promise<void>	Open the RampNow overlay/redirect.
close	() => void	Close the overlay.
isOpen	boolean	Overlay is open.
status	'idle' | 'opening' | 'open' | 'processing' | 'success' | 'error'	Current purchase status.
lastOrder	OnrampOrder | null	Most recent completed order.
error	Error | null	Last error.
enabled	boolean	Onramp is enabled in config.
supported	boolean	Destination chain supports onramp (see supported chains).

---

Components

DepositWidget

Inline deposit UI with token selection, QR code, and activity feed.

import { DepositWidget } from '@particle-network/simple-deposit/react';

<DepositWidget fullWidth theme="dark" />

Prop	Type	Default	Description
client	DepositClient	Context	Optional client (uses context if omitted).
theme	'dark' | 'light'	'dark'	Color theme.
destination	DestinationConfig	Provider config	Override destination.
onDestinationChange	(dest) => void	—	Destination change callback.
showDestination	boolean	true	Show destination section.
fullWidth	boolean	false	Expand to container (default: 380px).
showHeader	boolean	true	Show header with title.
className	string	—	Custom CSS class.
onClose	() => void	—	Close handler.

When funding.enabled and/or onramp.enabled are set on the provider, DepositWidget automatically gains a “Receive | Fund | Buy” toggle — segments appear only for the features you enable, no extra props needed. Pass showBuy={false} to suppress the Buy tab.

DepositModal

Modal wrapper around DepositWidget. Accepts all DepositWidget props plus:

import { DepositModal } from '@particle-network/simple-deposit/react';

<DepositModal isOpen={open} onClose={() => setOpen(false)} />

Prop	Type	Description
isOpen	boolean	Modal visibility.
onClose	() => void	Close handler (required).
overlayClassName	string	Custom overlay CSS class.

OnrampButton

Standalone “Buy” button for custom placement. Renders nothing when onramp is disabled. Must live inside a DepositProvider with onramp: { enabled: true }.

import { OnrampButton } from '@particle-network/simple-deposit/react';

<OnrampButton theme="dark" amount={100} onPurchased={(order) => console.log('bought', order)} />

Prop	Type	Default	Description
client	DepositClient	Context	Optional client (uses context if omitted).
theme	'dark' | 'light'	'dark'	Color theme.
amount	number	—	Pre-fill the fiat amount.
onPurchased	(order: OnrampOrder) => void	—	Called when a purchase completes.

OnrampStatusToast

A small floating “purchase in progress / complete / failed” popup that persists even after the user switches tabs or closes the RampNow overlay. Mount it once near your app root — it portals to document.body and is driven by useOnramp status.

import { OnrampStatusToast } from '@particle-network/simple-deposit/react';

<OnrampStatusToast theme="dark" position="bottom-right" />

Prop	Type	Default	Description
client	DepositClient	Context	Optional client (uses context if omitted).
theme	'dark' | 'light'	'dark'	Color theme.
position	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'	'bottom-right'	Where the toast anchors.
successDurationMs	number	6000	Auto-dismiss delay for the success toast. 0 keeps it until dismissed.

Order events only flow in mode: 'overlay'. A redirect tab has no postMessage channel back, so there’s nothing to track and the toast stays hidden.

RecoveryWidget

UI for scanning and recovering stuck funds.

import { RecoveryWidget } from '@particle-network/simple-deposit/react';

<RecoveryWidget autoScan theme="dark" />

Prop	Type	Default	Description
client	DepositClient	Context	Optional client.
theme	'dark' | 'light'	'dark'	Color theme.
autoScan	boolean	true	Auto-scan on mount.
showModeSelector	boolean	true	Show recover/refund toggle.
defaultMode	'recover' | 'refund'	'recover'	Initial mode.
className	string	—	Custom CSS class.
onClose	() => void	—	Close handler.

RecoveryModal

Modal wrapper around RecoveryWidget. Accepts all RecoveryWidget props plus:

import { RecoveryModal } from '@particle-network/simple-deposit/react';

<RecoveryModal isOpen={open} onClose={() => setOpen(false)} />

Prop	Type	Description
isOpen	boolean	Modal visibility.
onClose	() => void	Close handler (required).
overlayClassName	string	Custom overlay CSS class.

---

Next Steps

Core SDK

Headless DepositClient for non-React apps.

Reference

Types, constants, and advanced topics.