> ## Documentation Index
> Fetch the complete documentation index at: https://developers.particle.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```tsx theme={null}
import { DepositProvider, CHAIN } from '@particle-network/simple-deposit/react';

<DepositProvider config={{
  destination: { chainId: CHAIN.POLYGON },
  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. |
| `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). |
| `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.

```tsx theme={null}
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:

```tsx theme={null}
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. |

***

## Components

### DepositWidget

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

```tsx theme={null}
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. |

<Note>
  When `funding.enabled` is set on the provider, `DepositWidget` automatically gains a **"Receive | Fund from wallet"** toggle — no extra props needed.
</Note>

### DepositModal

Modal wrapper around `DepositWidget`. Accepts all `DepositWidget` props plus:

```tsx theme={null}
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. |

### RecoveryWidget

UI for scanning and recovering stuck funds.

```tsx theme={null}
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:

```tsx theme={null}
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

<CardGroup cols={2}>
  <Card title="Core SDK" icon="code" href="/simple-deposit/core-sdk">
    Headless DepositClient for non-React apps.
  </Card>

  <Card title="Reference" icon="book" href="/simple-deposit/reference">
    Types, constants, and advanced topics.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.