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

# Deposit Stablecoins

> Accept stablecoin deposits via dedicated addresses with automatic sweeping and webhook notifications

<Note>
  In a nutshell<br />
  Blockradar lets you accept stablecoin deposits by generating dedicated blockchain addresses for each customer. Deposits are detected automatically, trigger webhook notifications, and can be swept into your master wallet — giving you full control over how funds flow through your platform.
</Note>

## Prerequisites

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Master Wallet">
    Create a wallet via the dashboard or API. You'll need the `walletId` for all deposit operations.
  </Step>

  <Step title="Assets Enabled">
    Enable the stablecoins you want to accept on your wallet. Your wallet only detects deposits for assets you've explicitly added — see [Asset Management](/en/use-cases/asset-management).
  </Step>

  <Step title="Webhook URL">
    Configure a webhook endpoint in your dashboard under **Developers → Webhooks** to receive real-time deposit notifications.
  </Step>
</Steps>

## How It Works

Blockradar's deposit flow is built around a simple principle: every customer gets their own address, and every deposit is tracked automatically.

<CardGroup cols={2}>
  <Card title="Generate Addresses" icon="address-card">
    Create a unique blockchain address for each customer or payment session. Deposits to that address are attributed to the customer automatically.
  </Card>

  <Card title="Detect Deposits" icon="bell">
    Blockradar monitors all generated addresses and fires a webhook the moment a deposit arrives. No polling required.
  </Card>

  <Card title="Auto-Sweep" icon="broom">
    Deposits are automatically consolidated into your master wallet, keeping customer addresses clean and your treasury centralized.
  </Card>

  <Card title="Check Balances" icon="scale-balanced">
    Query balances at the wallet or address level, for a single asset or all assets at once, with USD conversion included.
  </Card>
</CardGroup>

## Granular Control by Design

Most blockchain infrastructure treats wallets as flat, one-size-fits-all containers. Blockradar is different. Every layer of the wallet hierarchy: master wallet, child address, and individual asset, is independently configurable, so fintechs can tailor the deposit experience to their exact product needs.

This means you can:

* **Accept different stablecoins per wallet** — enable USDC on one wallet and USDT on another, or both on the same wallet. You decide what each wallet monitors.
* **Configure sweep behavior per address** — auto-sweep deposits to the master wallet by default, but disable it for specific addresses where you want funds to remain in place.
* **Attach metadata to every address** — tag addresses with your own user IDs, session tokens, or internal references so deposits map directly to your system.
* **Activate or deactivate addresses on demand** — pause an address without deleting it, then reactivate when needed.

This granularity matters when you're building products like multi-currency wallets, marketplace escrow, or per-user deposit flows, where a rigid wallet model would force workarounds that Blockradar handles natively.

***

## Step 1: Enable Assets on Your Wallet

Before you can accept deposits, your wallet needs to know which stablecoins to watch for. Fetch available assets with the [Get Assets](/en/api-reference/miscellaneous/get-assets) endpoint, then add the ones you want.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/assets \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "assetId": "global-asset-id-for-usdc"
    }'
  ```

  ```javascript JavaScript theme={null}
  const asset = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/assets`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        assetId: 'global-asset-id-for-usdc'
      })
    }
  ).then(r => r.json());

  console.log('Asset enabled:', asset.data.asset.symbol);
  ```
</CodeGroup>

Once added, Blockradar immediately begins monitoring your wallet and all its addresses for deposits of that token.

<Tip>
  Use [Get Wallet Assets](/en/api-reference/asset/get-wallet-assets) to retrieve wallet-specific asset IDs. These are the IDs you'll use in balance queries and other API calls — they're different from the global asset IDs.
</Tip>

## Step 2: Generate a Customer Address

Create a dedicated address for each customer or deposit session. Every deposit to this address is automatically attributed to the customer.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request POST \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "name": "Customer 12345",
      "metadata": {
        "userId": "user_12345",
        "plan": "premium"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const address = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Customer 12345',
        metadata: {
          userId: 'user_12345',
          plan: 'premium'
        }
      })
    }
  ).then(r => r.json());

  console.log('Deposit address:', address.data.address);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "statusCode": 201,
  "message": "Address generated successfully",
  "data": {
    "id": "address-uuid",
    "address": "0xe1037B45b48390285e5067424053fa35c478296b",
    "name": "Customer 12345",
    "type": "INTERNAL",
    "isActive": true,
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "configurations": {
      "autoSweep": true,
      "gaslessWithdraw": false
    },
    "blockchain": {
      "name": "base",
      "symbol": "ETH",
      "network": "mainnet"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

### Address Parameters

| Parameter               | Type    | Required | Description                                                                         |
| ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `name`                  | string  | No       | Human-readable label for the address                                                |
| `metadata`              | object  | No       | Custom key-value pairs mapped to your internal system                               |
| `disableAutoSweep`      | boolean | No       | Set `true` to keep deposits at the address instead of sweeping to the master wallet |
| `enableGaslessWithdraw` | boolean | No       | Enable gasless withdrawals from this address                                        |

Share the generated `address` with your customer. When they send stablecoins to it, Blockradar detects the deposit and fires a webhook.

## Step 3: Listen for Deposits

Configure your webhook endpoint to receive real-time notifications when deposits arrive.

### Webhook Events

| Event                   | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| `deposit.success`       | A deposit has been confirmed on-chain at a customer address |
| `deposit.swept.success` | The deposit has been auto-swept to the master wallet        |

### Webhook Payload

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "id": "tx-uuid",
    "hash": "0xabc123...",
    "type": "DEPOSIT",
    "status": "SUCCESS",
    "amount": "100",
    "senderAddress": "0xCustomerExternalWallet...",
    "recipientAddress": "0xe1037B45b48390285e5067424053fa35c478296b",
    "asset": {
      "id": "asset-uuid",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    },
    "wallet": {
      "id": "wallet-uuid",
      "name": "Deposits Wallet"
    },
    "blockchain": {
      "name": "base",
      "network": "mainnet"
    },
    "metadata": {
      "userId": "user_12345",
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
```

<Info>
  The `metadata` you attached when generating the address is included in every webhook for that address, so you can map deposits back to your users without an extra lookup.
</Info>

***

## Checking Balances

Query balances at any level of the hierarchy — master wallet or individual address, single asset or all assets.

### Single Asset Balance (Wallet)

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url 'https://api.blockradar.co/v1/wallets/{walletId}/balance?assetId={assetId}' \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const balance = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/balance?assetId=${assetId}`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  console.log(`Balance: ${balance.data.balance} (≈$${balance.data.convertedBalance})`);
  ```
</CodeGroup>

### All Asset Balances (Address)

<CodeGroup>
  ```bash Curl theme={null}
  curl --request GET \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
    --header 'x-api-key: <api-key>'
  ```

  ```javascript JavaScript theme={null}
  const balances = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/balances`,
    { headers: { 'x-api-key': apiKey } }
  ).then(r => r.json());

  balances.data.forEach(b => {
    console.log(`${b.asset.asset.symbol}: ${b.balance} (≈$${b.convertedBalance})`);
  });
  ```
</CodeGroup>

### Balance Endpoints

| Scope         | Single Asset                                                                 | All Assets                                                  |
| ------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Master Wallet | `GET /v1/wallets/{walletId}/balance?assetId={assetId}`                       | `GET /v1/wallets/{walletId}/balances`                       |
| Child Address | `GET /v1/wallets/{walletId}/addresses/{addressId}/balance?assetId={assetId}` | `GET /v1/wallets/{walletId}/addresses/{addressId}/balances` |

***

## Managing Addresses

### List All Addresses

Fetch every address under a wallet, with analytics on active vs. inactive counts.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses
```

### Get a Specific Address

Retrieve full details for a single address, including its configuration and metadata.

```bash theme={null}
GET /v1/wallets/{walletId}/addresses/{addressId}
```

### Update an Address

Modify an address's name, metadata, active status, or sweep configuration.

<CodeGroup>
  ```bash Curl theme={null}
  curl --request PATCH \
    --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId} \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>' \
    --data '{
      "name": "Customer 12345 — upgraded",
      "metadata": {
        "userId": "user_12345",
        "plan": "enterprise"
      },
      "disableAutoSweep": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const updated = await fetch(
    `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': apiKey
      },
      body: JSON.stringify({
        name: 'Customer 12345 — upgraded',
        metadata: {
          userId: 'user_12345',
          plan: 'enterprise'
        },
        disableAutoSweep: true
      })
    }
  ).then(r => r.json());
  ```
</CodeGroup>

### Deactivate an Address

Set `isActive` to `false` to stop monitoring an address. The address and its history are preserved — you can reactivate it at any time.

```javascript theme={null}
await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}`,
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({ isActive: false })
  }
);
```

***

## Auto-Sweep

By default, deposits to child addresses are automatically swept to the master wallet. This keeps customer addresses clean and consolidates funds for treasury management or payouts.

You can control this at the address level:

| Setting                          | Behavior                                                                 |
| -------------------------------- | ------------------------------------------------------------------------ |
| Auto-sweep **enabled** (default) | Deposits are automatically moved to the master wallet after confirmation |
| Auto-sweep **disabled**          | Deposits remain at the child address until manually swept or withdrawn   |

### Manual Sweep

If auto-sweep is disabled, you can trigger a sweep on demand:

```bash theme={null}
POST /v1/wallets/{walletId}/sweep/assets
```

```json theme={null}
{
  "forceSweep": true
}
```

### Deposit Finder

If a deposit doesn't appear (e.g., missed webhook), use the deposit finder to rescan the blockchain:

```bash theme={null}
POST /v1/wallets/{walletId}/rescan/blocks
```

```json theme={null}
{
  "transactionHash": "0xabc123..."
}
```

***

## Complete Flow Example

Here's a full implementation: enable an asset, generate a customer address, and handle the deposit webhook.

```javascript theme={null}
async function setupCustomerDeposit(walletId, userId) {
  const apiKey = process.env.BLOCKRADAR_API_KEY;
  const baseUrl = 'https://api.blockradar.co/v1';
  const headers = {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  };

  // Step 1: Generate a dedicated address for the customer
  const addressRes = await fetch(
    `${baseUrl}/wallets/${walletId}/addresses`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: `User ${userId}`,
        metadata: { userId, createdAt: new Date().toISOString() }
      })
    }
  ).then(r => r.json());

  const depositAddress = addressRes.data.address;
  console.log('Share this address with customer:', depositAddress);

  return depositAddress;
}

// Webhook handler (Express.js example)
app.post('/webhooks/blockradar', (req, res) => {
  const { event, data } = req.body;

  if (event === 'deposit.success') {
    const userId = data.metadata?.userId;
    const amount = data.amount;
    const symbol = data.asset.symbol;

    console.log(`Deposit received: ${amount} ${symbol} from user ${userId}`);

    // Credit the user's account in your system
    creditUserAccount(userId, amount, symbol);
  }

  if (event === 'deposit.swept.success') {
    console.log(`Deposit swept to master wallet: ${data.amount} ${data.asset.symbol}`);
  }

  res.sendStatus(200);
});
```

***

## Best Practices

### Address Management

* **One address per customer** — generate a unique address for each user or payment session to simplify attribution
* **Use metadata** — attach your internal user IDs and references so webhook payloads map directly to your system
* **Deactivate, don't delete** — set `isActive: false` on addresses you no longer need, preserving history

### Security

* **Validate webhooks** — verify that incoming webhook requests originate from Blockradar
* **Enable AML screening** — Blockradar can screen deposit addresses automatically (see [AML Screening](/en/use-cases/aml-screening))
* **Monitor webhook logs** — use `GET /v1/wallets/{walletId}/webhooks` to debug failed deliveries

### Operations

* **Enable only the assets you need** — a focused asset list reduces webhook noise and keeps balance queries fast
* **Test on testnet first** — generate addresses, simulate deposits, and verify your webhook handler before going to mainnet
* **Use the deposit finder** — if a customer reports a deposit you haven't received, rescan the blockchain before troubleshooting further

***

## API Reference

### Wallet

| Endpoint                                                       | Description                                 |
| -------------------------------------------------------------- | ------------------------------------------- |
| [Get Wallet](/en/api-reference/wallet/get-wallet)              | Retrieve wallet details and configuration   |
| [Get Balance](/en/api-reference/wallet/get-balance)            | Check single asset balance on master wallet |
| [Get Balances](/en/api-reference/wallet/get-balances)          | Check all asset balances on master wallet   |
| [Trigger Sweep](/en/api-reference/wallet/trigger-sweep-assets) | Manually sweep deposits to master wallet    |
| [Deposit Finder](/en/api-reference/wallet/deposit-finder)      | Rescan blockchain for missing deposits      |
| [Webhook Logs](/en/api-reference/wallet/webhooks-logs)         | View webhook delivery history               |

### Addresses

| Endpoint                                                         | Description                                     |
| ---------------------------------------------------------------- | ----------------------------------------------- |
| [Generate Address](/en/api-reference/addresses/generate-address) | Create a new customer deposit address           |
| [Get Addresses](/en/api-reference/addresses/get-addresses)       | List all addresses on a wallet                  |
| [Get Address](/en/api-reference/addresses/get-address)           | Retrieve details of a specific address          |
| [Update Address](/en/api-reference/addresses/update-address)     | Update address name, metadata, or configuration |
| [Get Balance](/en/api-reference/addresses/get-balance)           | Check single asset balance on an address        |
| [Get Balances](/en/api-reference/addresses/get-balances)         | Check all asset balances on an address          |
| [Get Transactions](/en/api-reference/addresses/get-transactions) | View deposit history for an address             |

### Asset Management

| Endpoint                                                         | Description                          |
| ---------------------------------------------------------------- | ------------------------------------ |
| [Get Wallet Assets](/en/api-reference/asset/get-wallet-assets)   | List enabled assets on a wallet      |
| [Add Asset](/en/api-reference/asset/add-asset-to-wallet)         | Enable a new stablecoin for deposits |
| [Remove Asset](/en/api-reference/asset/remove-asset-from-wallet) | Stop monitoring a stablecoin         |
| [Update Asset](/en/api-reference/asset/update-wallet-asset)      | Update asset-level configuration     |