Simple Deposit — Reference

Type definitions, constants, chain utilities, and advanced configuration for the Simple Deposit.

Types

DestinationConfig

interface DestinationConfig {
  address?: string;     // Defaults to ownerAddress
  chainId: number;      // Required — use CHAIN constant
  token?: TokenType;    // Defaults to 'USDC' — see "Destination tokens"
}

Destination tokens

By default every deposit is delivered as USDC on the destination chain. Set destination.token to deliver a different asset; the sweep converts each deposit into that token and the fiat onramp buys it directly. The token must be deliverable on the destination chain or the client throws a ConfigurationError.

// Deliver native ETH on Base instead of USDC
destination: { chainId: CHAIN.BASE, token: 'ETH' }

Deliverable token × chain matrix:

Token	Ethereum	Base	Arbitrum	BNB	Solana
USDC	✓	✓	✓	✓	✓
USDT	✓	—	✓	✓	✓
ETH	✓ (native)	✓ (native)	✓ (native)	✓ (bridged)	—
SOL	—	—	—	—	✓ (native)

Deliverability mirrors the Universal Account’s routable primary assets (Base has no USDT route, for example). Use isSupportedDestinationToken(token, chainId) to check a combo at runtime.

X Layer is a deposit source only — the Universal Account has no X Layer primary tokens, so it cannot be used as a sweep destination.

Onramp note: RampNow’s fiat “Buy” supports a narrower set than the sweep — stablecoins on all chains, but ETH only on Ethereum/Base, BNB on BNB, and SOL on Solana. isOnrampSupported() / isOnrampTokenSupported(token, chainId) reflect this; gate “Buy” UI on them.

DetectedDeposit

interface DetectedDeposit {
  id: string;
  token: TokenType;
  chainId: number;
  amount: string;
  amountUSD: number;
  rawAmount: bigint;
  detectedAt: number;
}

SweepResult

interface SweepResult {
  depositId: string;
  transactionId: string;
  explorerUrl: string;
  status: 'success' | 'failed' | 'pending';
  error?: string;
}

RecoveryResult

interface RecoveryResult {
  token: TokenType;
  chainId: number;
  amount: string;
  amountUSD: number;
  status: 'success' | 'failed' | 'skipped';
  error?: string;
  txHash?: string;
}

RefundResult

interface RefundResult {
  depositId: string;
  token: TokenType;
  sourceChainId: number;
  amount: string;
  amountUSD: number;
  status: 'pending' | 'processing' | 'success' | 'failed' | 'skipped';
  reason: RefundReason;
  txHash?: string;
  error?: string;
  refundedTo?: string;
  refundedToSender?: boolean;
}

DepositLifecycleEvent

Normalized, serializable view of a deposit at a single lifecycle phase — delivered by the onDepositEvent callback and the deposit:lifecycle event, and the basis for the notification UI. id is stable across phase transitions.

type DepositPhase = 'detected' | 'processing' | 'credited' | 'failed' | 'below_threshold';

interface DepositLifecycleEvent {
  id: string;
  phase: DepositPhase;
  token: TokenType;
  chainId: number;
  amount: string;
  amountUSD: number;
  destination?: { address: string; chainId: number };
  transactionId?: string; // present on 'credited'
  explorerUrl?: string;   // present on 'credited'
  error?: string;         // present on 'failed'
  timestamp: number;
}

// DepositNotification (from useDepositNotifications) adds `createdAt` / `updatedAt`.

FundingConfig

interface FundingConfig {
  enabled: boolean;                       // Master switch (default: false)
  apiKey?: string;                        // Moralis key for DIRECT browser calls — dev/PoC only
  proxyUrl?: string;                      // Your own reverse proxy (injects the key server-side)
  balanceProvider?: BalanceProvider;      // Replace balance discovery entirely
  evmRpcUrls?: Record<number, string>;    // Per-chain EVM RPC overrides
  solanaRpcUrl?: string;                  // Solana RPC for building SPL/native transfers
  minValueUSD?: number;                   // Min USD value for a balance to be offered
}

Funding Types

// A connected browser wallet used as a funding source.
interface FundingWallet {
  evm?: { provider: unknown; address: string };     // EIP-1193 provider + address
  solana?: { provider: unknown; address: string };  // Solana wallet provider + address
}

// Options when transferring a discovered balance.
interface FundOptions {
  rawAmount?: bigint;   // Omit for the gas-adjusted max
}

// Result of a fund-from-wallet transfer.
interface FundingTransferResult {
  txHash: string;
  // …plus chain/token/amount metadata for the submitted transfer
}

// FundingBalance is the descriptor returned by getWalletBalances() — pass one
// straight back into fundFromWallet(). Treat it as opaque; don't construct it by hand.

OnrampConfig

interface OnrampConfig {
  enabled: boolean;                          // Master switch (default: false)
  apiKey?: string;                           // Your RampNow partner key (pk_live_…); omit to use the SDK default
  mode?: 'overlay' | 'redirect';             // 'overlay' = in-page iframe (emits order events); 'redirect' = new tab (no events). Default 'overlay'
  fiatCurrency?: string;                     // Fiat the user spends, e.g. 'EUR' (default 'USD')
  defaultFiatAmount?: number;                // Pre-fill the fiat amount
  paymentMode?: string;                      // 'card' | 'apple_pay' | 'google_pay' | 'sepa' | …
  widgetUrl?: string;                        // Override the RampNow widget base URL (e.g. a sandbox host)
}

Property	Type	Default	Description
enabled	boolean	false	Master switch for the feature.
apiKey	string	(SDK default)	Optional. Your RampNow partner key (pk_live_…). Omit to use the SDK’s built-in key; set it to route through your own partner account (your fees / KYC / limits).
mode	'overlay' | 'redirect'	'overlay'	'overlay' = in-page iframe modal (emits order events → activity feed updates). 'redirect' = open in a new tab (no close button to manage, but no order events).
fiatCurrency	string	'USD'	Fiat currency the user spends (e.g. 'EUR').
defaultFiatAmount	number	—	Pre-fill the fiat amount.
paymentMode	string	—	Preferred method: 'card', 'apple_pay', 'google_pay', 'sepa', …
widgetUrl	string	https://app.rampnow.io	Override the RampNow widget base URL (e.g. a sandbox host). For testing you normally just use a sandbox apiKey.

OnrampOrder

The completed-order payload from RampNow, delivered by the onramp:complete event and exposed as lastOrder from useOnramp.

interface OnrampOrder {
  amount: string;     // Delivered amount
  token: TokenType;   // Delivered token (USDC today)
  // …plus RampNow order metadata (status, id, destination)
}

UATransaction

interface UATransaction {
  transactionId: string;
  tag: string;
  createdAt: string;
  updatedAt: string;
  targetToken: {
    name: string;
    type: string;
    image: string;
    price: number;
    symbol: string;
    address: string;
    assetId: string;
    chainId: number;
    decimals: number;
    realDecimals: number;
    isPrimaryToken: boolean;
    isSmartRouterSupported: boolean;
  };
  change: {
    amount: string;
    amountInUSD: string;
    from: string;
    to: string;
  };
  detail: {
    redPacketCount: number;
  };
  status: number;
  fromChains: number[];
  toChains: number[];
}

TransactionsResponse

interface TransactionsResponse {
  transactions: UATransaction[];
  page: number;
  pageSize: number;
}

TokenTransactionFilter

interface TokenTransactionFilter {
  chainId: number;   // Chain ID to filter by
  address: string;   // Token contract address
}

TokenTransactionsResponse

interface TokenTransactionsResponse {
  transactions: UATransaction[];
  nextPageToken?: string;  // Cursor for next page (undefined = no more pages)
}

Other Types

type TokenType = 'ETH' | 'USDC' | 'USDT' | 'BTC' | 'SOL' | 'BNB';

type ClientStatus =
  | 'idle'
  | 'initializing'
  | 'ready'
  | 'watching'
  | 'sweeping'
  | 'error';

type RefundReason =
  | 'sweep_failed'
  | 'user_requested'
  | 'address_type_mismatch'
  | 'below_minimum';

interface DepositAddresses {
  evm: string;
  solana: string;
}

---

Constants

CHAIN

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

CHAIN.ETHEREUM    // 1
CHAIN.OPTIMISM    // 10
CHAIN.BNB         // 56
CHAIN.POLYGON     // 137
CHAIN.MONAD       // 143
CHAIN.SONIC       // 146
CHAIN.XLAYER      // 196
CHAIN.HYPERVM     // 999
CHAIN.MERLIN      // 4200
CHAIN.MANTLE      // 5000
CHAIN.BASE        // 8453
CHAIN.ARBITRUM    // 42161
CHAIN.AVALANCHE   // 43114
CHAIN.LINEA       // 59144
CHAIN.PLASMA      // 9745
CHAIN.BERACHAIN   // 80094
CHAIN.SOLANA      // 101

Defaults

import {
  DEFAULT_SUPPORTED_TOKENS,      // ['ETH', 'USDC', 'USDT', 'BTC', 'SOL', 'BNB']
  DEFAULT_MIN_VALUE_USD,          // 0.50
  DEFAULT_POLLING_INTERVAL_MS,    // 3000
} from '@particle-network/simple-deposit';

Chain Utilities

import {
  getChainName,                 // getChainName(42161) → "Arbitrum"
  isValidDestinationChain,      // isValidDestinationChain(42161) → true
  isSupportedDestinationToken,  // isSupportedDestinationToken('ETH', CHAIN.BASE) → true
  isOnrampTokenSupported,       // isOnrampTokenSupported('ETH', CHAIN.BASE) → true
  getAddressType,               // getAddressType(101) → 'solana'
  isValidEvmAddress,            // Validates 0x + 40 hex chars
  isValidSolanaAddress,         // Validates base58 format
  validateAddressForChain,      // Validates address format for chain type
} from '@particle-network/simple-deposit';

Wallet Detection Utilities

Framework-agnostic helpers for the Fund from Wallet feature — discover and connect injected browser wallets without React.

import {
  detectInjectedEvmWallets,     // EIP-6963 + legacy window.ethereum fallback
  connectInjectedEvm,           // eth_requestAccounts → address
  getEvmAccounts,               // current eth_accounts
  promptEvmAccountSelection,    // wallet_requestPermissions → eth_accounts
  detectInjectedSolanaWallet,   // window.phantom?.solana / window.solana
  connectInjectedSolana,        // connect() → publicKey
  formatUnits, parseUnits,      // smallest-unit ↔ human-readable amount helpers
} from '@particle-network/simple-deposit';

---

Advanced Topics

Custom Particle Credentials

You can provide your own Particle project ID via the uaProjectId config option.

uaProjectId only affects Universal Account operations (smart account initialization and asset queries). The intermediary wallet authentication (JWT + Auth Core session) always uses the SDK’s built-in credentials — this is by design and cannot be overridden.

This is useful if you want to handle your own app fees. If you use your own project ID, deposits are subject to a 1% fee going to Particle. Reach out to configure a custom rate and establish a revenue sharing model.

Contact: Particle Developer Support

React

<DepositProvider config={{
  destination: { chainId: CHAIN.BASE },
  uaProjectId: 'your-project-id',
}}>
  <App />
</DepositProvider>

const client = new DepositClient({
  ownerAddress: '0x...',
  intermediaryAddress: '0x...',
  destination: { chainId: CHAIN.BASE },
  uaProjectId: 'your-project-id',
});

Destination Configuration

Change the sweep destination at runtime.

React

const { setDestination, currentDestination } = useDepositContext();

setDestination({ chainId: CHAIN.ETHEREUM });

client.setDestination({ chainId: CHAIN.BASE, address: '0xTreasury...' });
const dest = client.getDestination(); // { address, chainId }

// Deliver a non-default token (see "Destination tokens")
client.setDestination({ chainId: CHAIN.BASE, token: 'ETH' });

Throws ConfigurationError if the chain ID, address, or token is invalid — see the deliverable token × chain matrix.

Notifications

Surface deposit progress to your users. Set notifications: true on DepositProvider to auto-mount the toaster, build a custom UI with the useDepositNotifications hook, or go headless with the onDepositEvent callback / deposit:lifecycle event — all driven by the same DepositLifecycleEvent.

React

<DepositProvider config={{
  destination: { chainId: CHAIN.BASE },
  notifications: { position: 'bottom-right', durationMs: 6000 },
}}>
  <App />
</DepositProvider>

const client = new DepositClient({
  ownerAddress: '0x...',
  intermediaryAddress: '0x...',
  destination: { chainId: CHAIN.BASE },
  onDepositEvent: (e) => console.log(e.phase, e.token, e.amountUSD),
});

DepositNotificationsProps

Property	Type	Default	Description
position	'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'	'top-right'	Anchor on screen.
theme	'dark' | 'light'	'dark'	Color theme.
durationMs	number	6000	Auto-dismiss delay for terminal toasts. 0 disables.
max	number	5	Max simultaneous toasts.
className	string	—	Extra classes for the fixed container.
renderItem	(n, dismiss) => ReactNode	—	Render-prop escape hatch (replaces default markup).

Lifecycle events fire client-side and best-effort — they are not a reliable server webhook. Don’t use them as the source of truth for crediting funds.

Fund from Wallet

Let users top up their deposit address from a connected browser wallet (MetaMask / Rabby / Phantom / any injected EIP-1193 or Solana wallet). The SDK discovers cross-chain balances, builds a transfer to the deposit address, and the watcher sweeps it as usual. Balance discovery is zero-config (Particle’s hosted service — no Moralis key, proxy, or backend). The browser wallet is a funding source only — it never becomes the Universal Account owner/signer.

const client = new DepositClient({
  ownerAddress: '0x...',
  intermediaryAddress: '0x...',
  authCoreProvider: provider,
  destination: { chainId: CHAIN.BASE },
  funding: { enabled: true },   // ← that's it
});

When funding.enabled is set, DepositWidget automatically shows a “Receive | Fund from wallet” toggle. For a standalone surface use the FundFromWallet component, or call client.getWalletBalances() / client.fundFromWallet() directly — see the React SDK and Core SDK.

FundingConfig

Property	Type	Default	Description
enabled	boolean	false	Master switch for the feature.
apiKey	string	—	Moralis API key for direct browser calls. Dev/PoC only — exposes the key. Prefer the hosted default.
proxyUrl	string	Hosted service	Base URL of your own reverse proxy. Omit to use Particle’s hosted service.
balanceProvider	BalanceProvider	—	Replace balance discovery entirely; apiKey / proxyUrl / hosted default are ignored.
evmRpcUrls	Record<number, string>	Public RPCs	Per-chain EVM RPC overrides (native gas checks / send fallback).
solanaRpcUrl	string	Public RPC	Solana RPC used to build SPL/native transfers.
minValueUSD	number	Client minValueUSD	Minimum USD value for a balance to be offered.

Balance-source precedence: balanceProvider > apiKey (direct) > proxyUrl > hosted default. Balance discovery covers Ethereum, BNB Chain, Base, Arbitrum, and Solana; X Layer is not supported and is skipped during discovery.

Onramp

Let users buy crypto with fiat (card / Apple Pay / bank) via RampNow, delivered straight to the destination. Onramp bypasses the watcher/sweeper pipeline — RampNow’s order events are the source of truth and are forwarded as onramp:* events. Zero-config: the SDK ships a default RampNow key, and @rampnow/sdk loads lazily only when the onramp opens.

const client = new DepositClient({
  ownerAddress: '0x...',
  intermediaryAddress: '0x...',
  authCoreProvider: provider,
  destination: { chainId: CHAIN.BASE },
  onramp: { enabled: true },   // ← that's it
});

When onramp.enabled is set, DepositWidget automatically adds a “Buy” tab. For custom placement use OnrampButton, the useOnramp() hook, or the OnrampStatusToast popup — see the React SDK. Headless apps call client.openOnramp({ amount }) directly — see the Core SDK.

Supported chains: Ethereum, BNB Chain, Base, Arbitrum, and Solana. X Layer is not supported — isOnrampSupported() returns false and the “Buy” UI is disabled with an explanation.

Delivered token: Onramp always buys USDC, matching the token the sweep delivers to the destination.

Order events only flow in mode: 'overlay'. A redirect tab has no postMessage channel back, so there’s nothing to track (no activity-feed updates, no status toast).

Recovery

Recover funds that are stuck in the intermediary wallet (e.g., due to failed sweeps).

const { stuckFunds, recoverFunds, isRecovering } = useDepositContext();

Or use the built-in UI:

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

Refund (Experimental)

Refund is experimental. Auto-refund is disabled by default.

Enable auto-refund to automatically return funds to the source chain when sweeps fail:

<DepositProvider config={{
  destination: { chainId: CHAIN.BASE },
  refund: {
    enabled: true,
    delayMs: 5000,
    maxAttempts: 2,
    refundToSender: true,
  },
}}>
  <App />
</DepositProvider>

RefundConfig

Property	Type	Default	Description
enabled	boolean	false	Enable auto-refund.
delayMs	number	5000	Delay before refund attempt.
maxAttempts	number	2	Max refund attempts.
refundToSender	boolean	true	Refund to original sender if detectable.

Manual refund is always available regardless of the auto-refund setting:

const result = await client.refund('deposit-id', 'user_requested');
const { eligible, reason } = await client.canRefund('deposit-id');

Error Handling

All SDK errors extend DepositSDKError:

import {
  DepositSDKError,       // Base class
  ConfigurationError,    // Invalid config
  AuthenticationError,   // Auth failed
  JwtError,              // JWT service error
  UniversalAccountError, // UA operations failed
  SweepError,            // Sweep failed
  RefundError,           // Refund failed
  FundingError,          // Fund-from-wallet failed
  NetworkError,          // Network issues
} from '@particle-network/simple-deposit';

try {
  await client.initialize();
} catch (error) {
  if (error instanceof ConfigurationError) {
    // Invalid config — check destination chain ID and address
  }
  if (error instanceof JwtError) {
    // JWT service unreachable
  }
  if (error instanceof UniversalAccountError) {
    // UA initialization failed
  }
}

---

Back to Quickstart

Installation, quickstart, and usage patterns.