Deposit Stablecoins - Blockradar

In a nutshell
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.

Prerequisites

API Key

Get your API key from the Blockradar Dashboard. Navigate to Developers to generate one.

Master Wallet

Create a wallet via the dashboard or API. You’ll need the walletId for all deposit operations.

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.

Webhook URL

Configure a webhook endpoint in your dashboard under Developers → Webhooks to receive real-time deposit notifications.

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.

Generate Addresses

Create a unique blockchain address for each customer or payment session. Deposits to that address are attributed to the customer automatically.

Detect Deposits

Blockradar monitors all generated addresses and fires a webhook the moment a deposit arrives. No polling required.

Auto-Sweep

Deposits are automatically consolidated into your master wallet, keeping customer addresses clean and your treasury centralized.

Check Balances

Query balances at the wallet or address level, for a single asset or all assets at once, with USD conversion included.

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 endpoint, then add the ones you want.

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"
  }'

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);

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

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

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.

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"
    }
  }'

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);

Response

{
  "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

{
  "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"
  }
}

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.

Checking Balances

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

Single Asset Balance (Wallet)

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

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})`);

All Asset Balances (Address)

curl --request GET \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/balances \
  --header 'x-api-key: <api-key>'

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})`);
});

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.

GET /v1/wallets/{walletId}/addresses

Get a Specific Address

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

GET /v1/wallets/{walletId}/addresses/{addressId}

Update an Address

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

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
  }'

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

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.

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:

POST /v1/wallets/{walletId}/sweep/assets

{
  "forceSweep": true
}

Deposit Finder

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

POST /v1/wallets/{walletId}/rescan/blocks

{
  "transactionHash": "0xabc123..."
}

Complete Flow Example

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

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)
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	Retrieve wallet details and configuration
Get Balance	Check single asset balance on master wallet
Get Balances	Check all asset balances on master wallet
Trigger Sweep	Manually sweep deposits to master wallet
Deposit Finder	Rescan blockchain for missing deposits
Webhook Logs	View webhook delivery history

Addresses

Endpoint	Description
Generate Address	Create a new customer deposit address
Get Addresses	List all addresses on a wallet
Get Address	Retrieve details of a specific address
Update Address	Update address name, metadata, or configuration
Get Balance	Check single asset balance on an address
Get Balances	Check all asset balances on an address
Get Transactions	View deposit history for an address

Asset Management

Endpoint	Description
Get Wallet Assets	List enabled assets on a wallet
Add Asset	Enable a new stablecoin for deposits
Remove Asset	Stop monitoring a stablecoin
Update Asset	Update asset-level configuration

​Prerequisites

​How It Works

Generate Addresses

Detect Deposits

Auto-Sweep

Check Balances

​Granular Control by Design

​Step 1: Enable Assets on Your Wallet

​Step 2: Generate a Customer Address

​Response

​Address Parameters

​Step 3: Listen for Deposits

​Webhook Events

​Webhook Payload

​Checking Balances

​Single Asset Balance (Wallet)

​All Asset Balances (Address)

​Balance Endpoints

​Managing Addresses

​List All Addresses

​Get a Specific Address

​Update an Address

​Deactivate an Address

​Auto-Sweep

​Manual Sweep

​Deposit Finder

​Complete Flow Example

​Best Practices

​Address Management

​Security

​Operations

​API Reference

​Wallet

​Addresses

​Asset Management

Prerequisites

How It Works

Granular Control by Design

Step 1: Enable Assets on Your Wallet

Step 2: Generate a Customer Address

Response

Address Parameters

Step 3: Listen for Deposits

Webhook Events

Webhook Payload

Checking Balances

Single Asset Balance (Wallet)

All Asset Balances (Address)

Balance Endpoints

Managing Addresses

List All Addresses

Get a Specific Address

Update an Address

Deactivate an Address

Auto-Sweep

Manual Sweep

Deposit Finder

Complete Flow Example

Best Practices

Address Management

Security

Operations

API Reference

Wallet

Addresses

Asset Management