Skip to main content
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/universal-deposit';

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

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

Constructor Config

PropertyTypeRequiredDefaultDescription
ownerAddressstringYesUser’s wallet address.
intermediaryAddressstringYesJWT wallet from Auth Core.
authCoreProviderAuthCoreProviderNo*Provider for signing. *Required for sweeps.
destinationDestinationConfigYesWhere swept funds go (chainId required).
supportedTokensTokenType[]NoAllTokens to watch.
supportedChainsnumber[]NoAll 17Chains to watch.
autoSweepbooleanNotrueAuto-sweep on detection.
minValueUSDnumberNo0.50Minimum USD threshold.
pollingIntervalMsnumberNo3000Polling interval (ms).
recoveryRecoveryConfigNoRecovery behavior.
refundRefundConfigNo{ enabled: false }Auto-refund (experimental).
uaProjectIdstringNoSDK defaultParticle project ID for UA operations only.

Methods

MethodParametersReturnsDescription
initialize()Promise<void>Initialize client (call first).
destroy()voidCleanup resources.
getDepositAddresses()Promise<DepositAddresses>Get EVM + Solana addresses.
startWatching()voidStart balance polling.
stopWatching()voidStop balance polling.
checkBalances()Promise<DetectedDeposit[]>Get current balances (above threshold).
sweep(depositId?)string?Promise<SweepResult[]>Sweep specific or all deposits.
getStatus()ClientStatusCurrent status.
getPendingDeposits()DetectedDeposit[]Unsent deposits.
getConfig()ResolvedConfigResolved config.
setDestination(dest)Partial<DestinationConfig>voidChange 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)stringPromise<{ eligible, reason? }>Check refund eligibility.
getRefundConfig()RefundConfigCurrent refund config.
getTransactions(page, pageSize)number, numberPromise<TransactionsResponse>Page-based transaction history.
getTokenTransactions(filter, cursor?)TokenTransactionFilter, string?Promise<TokenTransactionsResponse>Cursor-based filtered transactions.
getTransaction(id)stringPromise<UATransaction>Single transaction lookup.

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/universal-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

EventPayloadDescription
deposit:detectedDetectedDepositNew deposit found.
deposit:processingDetectedDepositSweep started.
deposit:completeSweepResultSweep succeeded.
deposit:errorError, DetectedDeposit?Sweep failed.
recovery:startedRecovery started.
recovery:completeRecoveryResult[]Recovery finished.
recovery:failedDetectedDeposit, ErrorSingle recovery failed.
refund:startedDetectedDeposit, RefundReasonRefund initiated.
refund:processingDetectedDeposit, attemptRefund attempt.
refund:completeRefundResultRefund succeeded.
refund:failedDetectedDeposit, Error, exhaustedRefund failed.
status:changeClientStatusStatus changed.

Next Steps