Simple Deposit — Core API

Headless Core API reference for the Simple Deposit: DepositClient constructor, methods, and events.

The DepositClient provides full deposit functionality without React. Use it for server-side scripts, Node.js backends, or custom UI frameworks.

DepositClient

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

const client = new DepositClient({
  ownerAddress: '0x...',
  intermediaryAddress: '0x...',
  authCoreProvider: provider,
  destination: { chainId: CHAIN.BASE },
});

await client.initialize();
client.startWatching();

Constructor Config

Property	Type	Required	Default	Description
ownerAddress	string	Yes	—	User’s wallet address.
intermediaryAddress	string	Yes	—	JWT wallet from Auth Core.
authCoreProvider	AuthCoreProvider	No*	—	Provider for signing. *Required for sweeps.
destination	DestinationConfig	Yes	—	Where swept funds go (chainId required; optional token defaults to USDC — see Destination tokens).
supportedTokens	TokenType[]	No	All	Tokens to watch.
supportedChains	number[]	No	All 17	Chains to watch.
autoSweep	boolean	No	true	Auto-sweep on detection.
minValueUSD	number	No	0.50	Minimum USD threshold.
pollingIntervalMs	number	No	3000	Polling interval (ms).
recovery	RecoveryConfig	No	—	Recovery behavior.
refund	RefundConfig	No	{ enabled: false }	Auto-refund (experimental).
funding	FundingConfig	No	{ enabled: false }	Fund the deposit address from a connected browser wallet (zero-config).
onramp	OnrampConfig	No	{ enabled: false }	Buy crypto with fiat via RampNow, delivered straight to the destination (zero-config).
onDepositEvent	(event: DepositLifecycleEvent) => void	No	—	Deposit-lifecycle callback. Best-effort and client-side (not a server webhook).
uaProjectId	string	No	SDK default	Particle project ID for UA operations only.

---

Methods

Method	Parameters	Returns	Description
initialize()	—	Promise<void>	Initialize client (call first).
destroy()	—	void	Cleanup resources.
getDepositAddresses()	—	Promise<DepositAddresses>	Get EVM + Solana addresses.
startWatching()	—	void	Start balance polling.
stopWatching()	—	void	Stop balance polling.
checkBalances()	—	Promise<DetectedDeposit[]>	Get current balances (above threshold).
sweep(depositId?)	string?	Promise<SweepResult[]>	Sweep specific or all deposits.
getStatus()	—	ClientStatus	Current status.
getPendingDeposits()	—	DetectedDeposit[]	Unsent deposits.
getConfig()	—	ResolvedConfig	Resolved config.
setDestination(dest)	Partial<DestinationConfig>	void	Change destination at runtime.
getDestination()	—	{ address, chainId }	Current destination.
getStuckFunds()	—	Promise<DetectedDeposit[]>	All non-zero balances (no threshold).
recoverAllFunds()	—	Promise<RecoveryResult[]>	Sweep all stuck funds.
refund(id, reason?)	string, RefundReason?	Promise<RefundResult>	Refund specific deposit.
refundAll(reason?)	RefundReason?	Promise<RefundResult[]>	Refund all pending.
canRefund(id)	string	Promise<{ eligible, reason? }>	Check refund eligibility.
getRefundConfig()	—	RefundConfig	Current refund config.
getWalletBalances(wallet)	FundingWallet	Promise<FundingBalance[]>	Discover a connected wallet’s cross-chain balances.
fundFromWallet(wallet, balance, opts?)	FundingWallet, FundingBalance, FundOptions?	Promise<FundingTransferResult>	Transfer a discovered balance to the deposit address.
openOnramp(opts?)	{ amount?: number }	Promise<void>	Open the RampNow onramp to buy crypto with fiat.
isOnrampSupported()	—	boolean	Whether the current destination chain supports onramp.
getTransactions(page, pageSize)	number, number	Promise<TransactionsResponse>	Page-based transaction history.
getTokenTransactions(filter, cursor?)	TokenTransactionFilter, string?	Promise<TokenTransactionsResponse>	Cursor-based filtered transactions.
getTransaction(id)	string	Promise<UATransaction>	Single transaction lookup.

---

Notifications (Headless)

Track each deposit through its lifecycle without any UI. Pass the onDepositEvent callback, or subscribe to the deposit:lifecycle event — both deliver the same normalized DepositLifecycleEvent, with a stable id across phase transitions (detected → processing → credited, or failed / below_threshold).

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

// Or subscribe to the same stream as an event:
client.on('deposit:lifecycle', (e) => console.log(e.phase, e.id));

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 (Headless)

Let a user top up their deposit address from a connected browser wallet (MetaMask / Rabby / Phantom / any injected EIP-1193 or Solana wallet). The SDK discovers the wallet’s cross-chain balances, builds a plain transfer to the deposit address, and submits it through the wallet; the watcher then detects and sweeps it as usual. The browser wallet is a funding source only — it never becomes the Universal Account owner/signer.

Balance discovery is zero-config (Particle’s hosted service — no Moralis key, proxy, or backend). Enable it on the client:

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

Flow

import {
  detectInjectedEvmWallets,
  connectInjectedEvm,
} from '@particle-network/simple-deposit';

// 1. Detect + connect an injected wallet (or bring your own EIP-1193 provider).
const [wallet] = await detectInjectedEvmWallets();
const address = await connectInjectedEvm(wallet.provider);

// 2. Discover spendable balances across supported chains.
const balances = await client.getWalletBalances({ evm: { provider: wallet.provider, address } });

// 3. Transfer a chosen balance to the deposit address (omit rawAmount for the
//    gas-adjusted max). Emits funding:started → funding:complete (or funding:error).
const result = await client.fundFromWallet(
  { evm: { provider: wallet.provider, address } },
  balances[0],
);

Detection Utilities

Framework-agnostic helpers for discovering and connecting injected wallets:

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

Balance discovery covers Ethereum, BNB Chain, Base, Arbitrum, and Solana. X Layer is not supported by the Moralis-backed service, so it is skipped during discovery — other supported chains are unaffected.

---

Onramp — Buy with Fiat (Headless)

Let a user buy crypto with fiat (card / Apple Pay / bank) via RampNow, delivered straight to the configured destination. Unlike Fund from Wallet, the purchase bypasses the deposit-address → watcher → sweeper pipeline — RampNow’s order events are the source of truth, forwarded by the SDK as onramp:* events. The onramp buys the destination token (USDC by default), matching the sweep — note RampNow supports a narrower token set than the sweep, so gate the “Buy” UI on isOnrampSupported() / isOnrampTokenSupported(token, chainId) (see Destination tokens).

Onramp is a single flag — zero-config. The SDK ships with a default RampNow key, so there’s nothing to source; pass your own apiKey only to route purchases through your own RampNow partner account. The underlying @rampnow/sdk is loaded lazily (dynamic import()) only when the onramp is opened, so it never bundles into apps that don’t use it.

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

// Events report progress.
client.on('onramp:complete', (order) => console.log('delivered', order.amount, order.token));

// Open the overlay (100 USD by default fiat currency).
await client.openOnramp({ amount: 100 });

Onramp delivery is supported for Ethereum, BNB Chain, Base, Arbitrum, and Solana. X Layer is not supported — isOnrampSupported() returns false for it. Order events only flow in mode: 'overlay'; a redirect tab has no channel back to report progress.

---

Transaction History

Query the Universal Account’s transaction history. Results are cached (30s TTL, LRU) to avoid redundant API calls when paginating.

Page-Based Pagination

const { transactions, page, pageSize } = await client.getTransactions(1, 10);

for (const tx of transactions) {
  console.log(tx.transactionId, tx.targetToken.symbol, tx.change.amountInUSD);
}

// Next page
const page2 = await client.getTransactions(2, 10);

Filter by Token and Chain (Cursor-Based)

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

// Get USDC transactions on Ethereum
const result = await client.getTokenTransactions({
  chainId: CHAIN.ETHEREUM,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC contract
});

// Paginate with cursor
if (result.nextPageToken) {
  const nextPage = await client.getTokenTransactions(
    { chainId: CHAIN.ETHEREUM, address: '0xA0b8...' },
    result.nextPageToken,
  );
}

Single Transaction Lookup

const tx = await client.getTransaction('tx_abc123');
console.log(tx.status, tx.change.amount, tx.fromChains, tx.toChains);

---

Events

Subscribe to events using on / off:

client.on('deposit:detected', (deposit: DetectedDeposit) => {
  console.log(`New deposit: ${deposit.token} on chain ${deposit.chainId}`);
});

client.on('deposit:complete', (result: SweepResult) => {
  console.log(`Sweep complete: ${result.explorerUrl}`);
});

// Remove a specific listener
client.off('deposit:detected', handler);

Event Reference

Event	Payload	Description
deposit:detected	DetectedDeposit	New deposit found.
deposit:processing	DetectedDeposit	Sweep started.
deposit:complete	SweepResult	Sweep succeeded.
deposit:below_threshold	DetectedDeposit	Deposit detected below minValueUSD.
deposit:error	Error, DetectedDeposit?	Sweep failed.
deposit:lifecycle	DepositLifecycleEvent	Normalized phase transition (mirrors the events above).
recovery:started	—	Recovery started.
recovery:complete	RecoveryResult[]	Recovery finished.
recovery:failed	DetectedDeposit, Error	Single recovery failed.
refund:started	DetectedDeposit, RefundReason	Refund initiated.
refund:processing	DetectedDeposit, attempt	Refund attempt.
refund:complete	RefundResult	Refund succeeded.
refund:failed	DetectedDeposit, Error, exhausted	Refund failed.
funding:started	FundingBalance	Wallet-funding transfer started.
funding:complete	FundingTransferResult	Wallet-funding transfer submitted.
funding:error	Error, FundingBalance?	Wallet-funding transfer failed.
onramp:complete	OnrampOrder	Fiat purchase delivered to the destination.
status:change	ClientStatus	Status changed.

---

Next Steps

React SDK

DepositProvider, hooks, and UI components.

Reference

Types, constants, and advanced topics.