Particle-Network · soos3d · May 25, 2026 · Jun 16, 2026 · Jun 29, 2026 · Jun 29, 2026
diff --git a/docs.json b/docs.json
@@ -152,7 +152,26 @@
           }
         ]
       },
-
+      {
+        "tab": "Simple Deposit",
+        "groups": [
+          {
+            "group": "OVERVIEW",
+            "pages": [
+              "simple-deposit/overview",
+              "simple-deposit/quickstart"
+            ]
+          },
+          {
+            "group": "SDK Reference",
+            "pages": [
+              "simple-deposit/react-sdk",
+              "simple-deposit/core-sdk",
+              "simple-deposit/reference"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Social Logins",
         "groups": [

diff --git a/simple-deposit/core-sdk.mdx b/simple-deposit/core-sdk.mdx
@@ -29,7 +29,7 @@
 | `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). |
+| `destination` | `DestinationConfig` | Yes | — | Where swept funds go (`chainId` required; optional `token` defaults to USDC — see [Destination tokens](/simple-deposit/reference#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. |
@@ -38,6 +38,7 @@
 | `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. |
 
@@ -49,7 +50,7 @@
 |---|---|---|---|
 | `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). |
@@ -67,6 +68,8 @@
 | `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. |
@@ -104,13 +107,13 @@
 ## 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:

 ```typescript
@@ -163,11 +166,39 @@
 ```

 <Note>
  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.
 </Note>
 
 ---
 
+## Onramp — Buy with Fiat (Headless)
+
+Let a user **buy crypto with fiat** (card / Apple Pay / bank) via [RampNow](https://rampnow.io), 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](/simple-deposit/reference#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.
+
+```typescript
+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 });
+```
+
+<Note>
+  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.
+</Note>
+
+---
+
 ## Transaction History
 
 Query the Universal Account's transaction history. Results are cached (30s TTL, LRU) to avoid redundant API calls when paginating.
@@ -251,6 +282,7 @@
 | `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. |
 
 ---

diff --git a/simple-deposit/react-sdk.mdx b/simple-deposit/react-sdk.mdx
@@ -12,7 +12,7 @@
 import { DepositProvider, CHAIN } from '@particle-network/simple-deposit/react';
 
 <DepositProvider config={{
-  destination: { chainId: CHAIN.POLYGON },
+  destination: { chainId: CHAIN.BASE },
   autoSweep: true,
   minValueUSD: 1,
 }}>
@@ -26,6 +26,7 @@
 |---|---|---|---|
 | `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](/simple-deposit/reference#destination-tokens). |
 | `supportedTokens` | `TokenType[]` | All | Tokens to watch. |
 | `supportedChains` | `number[]` | All 17 chains | Chains to watch. |
 | `autoSweep` | `boolean` | `true` | Auto-sweep detected deposits. |
@@ -35,11 +36,12 @@
 | `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.

@@ -68,7 +70,7 @@
 | `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). |
@@ -108,6 +110,36 @@
 
 ---
 
+## 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.
+
+```tsx
+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](/simple-deposit/reference#onramp)). |
+
+---
+
 ## Components
 
 ### DepositWidget
@@ -133,7 +165,7 @@
 | `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.
+  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.
 </Note>
 
 ### DepositModal
@@ -152,6 +184,44 @@
 | `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 }`.
+
+```tsx
+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.
+
+```tsx
+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. |
+
+<Note>
+  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.
+</Note>
+
 ### RecoveryWidget
 
 UI for scanning and recovering stuck funds.

diff --git a/simple-deposit/reference.mdx b/simple-deposit/reference.mdx
@@ -10,11 +10,45 @@
 
 ```typescript
 interface DestinationConfig {
-  address?: string;   // Defaults to ownerAddress
-  chainId: number;    // Required — use CHAIN constant
+  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`.
+
+```typescript
+// 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
 
 ```typescript
@@ -75,7 +109,7 @@

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

 ```typescript
 type DepositPhase = 'detected' | 'processing' | 'credited' | 'failed' | 'below_threshold';
@@ -135,7 +169,43 @@
 // straight back into fundFromWallet(). Treat it as opaque; don't construct it by hand.
 ```
 
+### OnrampConfig
+
+```typescript
+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`.
+
+```typescript
+interface OnrampOrder {
+  amount: string;     // Delivered amount
+  token: TokenType;   // Delivered token (USDC today)
+  // …plus RampNow order metadata (status, id, destination)
+}
+```
+
 ### UATransaction
 
 ```typescript
 interface UATransaction {
@@ -267,12 +337,14 @@
 
 ```typescript
 import {
-  getChainName,              // getChainName(42161) → "Arbitrum"
-  isValidDestinationChain,   // isValidDestinationChain(42161) → true
-  getAddressType,            // getAddressType(101) → 'solana'
-  isValidEvmAddress,         // Validates 0x + 40 hex chars
-  isValidSolanaAddress,      // Validates base58 format
-  validateAddressForChain,   // Validates address format for chain type
+  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';
 ```
 
@@ -349,12 +421,16 @@
 ```typescript Headless
 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' });
 ```
 
 </CodeGroup>
 
 <Note>
-  Throws `ConfigurationError` if the chain ID or address is invalid.
+  Throws `ConfigurationError` if the chain ID, address, or token is invalid — see the
+  [deliverable token × chain matrix](#destination-tokens).
 </Note>
 
 ### Notifications
@@ -400,7 +476,7 @@

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

 ```typescript
 const client = new DepositClient({
@@ -419,17 +495,45 @@
 | 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. |

 <Note>
   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.
 </Note>
 
+### Onramp
+
+Let users buy crypto with fiat (card / Apple Pay / bank) via [RampNow](https://rampnow.io), 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.
+
+```typescript
+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](/simple-deposit/react-sdk). Headless apps call `client.openOnramp({ amount })` directly — see the [Core SDK](/simple-deposit/core-sdk#onramp-buy-with-fiat-headless).
+
+<Note>
+  **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.
+</Note>
+
+<Note>
+  **Delivered token:** Onramp always buys **USDC**, matching the token the sweep delivers to the destination.
+</Note>
+
+<Warning>
+  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).
+</Warning>
+
 ### Recovery
 
 Recover funds that are stuck in the intermediary wallet (e.g., due to failed sweeps).