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

# From 0 to Integration

> Go from zero to a live stablecoin integration in under 2 hours.

This guide walks you through everything you need to accept stablecoin deposits using Blockradar, from account setup to handling your first webhook event. You can integrate and go live with one developer in under 2 hours.

<Info>
  Follow along and build as you read. By the end you'll have a working stablecoin payment flow.
</Info>

## What you'll build

By the end of this guide you will have:

* A Blockradar account and a master wallet on testnet
* Child addresses generated and tied to your users
* A webhook handler receiving real-time deposit events
* A pattern for updating user balances after a deposit

***

## Step 1: Create your account

<Steps>
  <Step title="Sign up">
    Visit [dashboard.blockradar.co/signup](https://dashboard.blockradar.co/signup) and complete the onboarding process. It takes under 60 seconds.
  </Step>

  <Step title="Check Live Mode">
    In the top-right corner of the dashboard you'll see a **Live Mode** toggle. It's off by default, this means every action runs on **testnet**, a safe sandbox where no real funds are involved. Leave it off while following this guide.
  </Step>
</Steps>

***

## Step 2: Create a master wallet

### What is a master wallet?

The master wallet is the foundation of your stablecoin infrastructure. Think of it as your treasury, it holds control over all the child addresses you create for your users. Each master wallet is tied to a specific blockchain, so if you want to support deposits on Ethereum, Base, and BNB Chain, you'll create a separate master wallet for each.

### Create your first wallet

<Steps>
  <Step title="Go to the Wallets page">
    From the dashboard, click **Create Master Wallet**.
  </Step>

  <Step title="Select a network">
    Choose **Base Sepolia (Testnet)** to follow this guide. You can create wallets on other chains later.
  </Step>

  <Step title="Name your wallet">
    Give it a name like `base-testnet` and click **Create**.
  </Step>
</Steps>

You now have a master wallet. This is where all child addresses for your users will be generated.

***

## Step 3: Generate addresses for your users

### What are child addresses?

When a user onboards to your app and needs to receive stablecoins, they need a wallet address, like a bank account number, but on the blockchain. In Blockradar, these are called **child addresses**. They are generated under your master wallet and inherit its network configuration.

<Note>
  Addresses generated on any EVM-compatible chain (Base, Ethereum, BNB Chain, etc.) work across all EVM chains. One address covers all your EVM networks.
</Note>

### Generate an address via API

Call this endpoint when a user signs up on your platform:

```bash theme={null}
curl -X POST https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Wallet",
    "disableAutoSweep": false,
    "enableGaslessWithdraw": true,
    "metadata": {
      "user_id": 1234,
      "email": "user@example.com"
    }
  }'
```

```javascript theme={null}
const options = {
  method: "POST",
  headers: {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Customer Wallet",
    disableAutoSweep: false,
    enableGaslessWithdraw: true,
    metadata: { user_id: 1234, email: "user@example.com" },
  }),
};

fetch("https://api.blockradar.co/v1/wallets/{walletId}/addresses", options)
  .then((res) => res.json())
  .then(console.log);
```

### Where to find your walletId and API key

1. Go to your master wallet in the dashboard
2. Scroll down to the **API Config** section
3. Click the reveal icon (you'll need to pass 2FA)
4. Copy both your **API Key** and **Wallet ID**

### The metadata field

The `metadata` object is one of the most important parts of this request. Anything you attach here will be included in every webhook Blockradar sends for that address, deposits, withdrawals, sweeps. This is how your backend identifies which user a transaction belongs to.

```json theme={null}
{
  "user_id": 1234,
  "email": "user@example.com"
}
```

**Best practice:** Always include a `user_id` in metadata so you can map every deposit directly to a user in your database without any additional lookups.

***

## Step 4: Configure auto sweep and gasless transactions

### Auto sweep

When auto sweep is enabled (`disableAutoSweep: false`), funds deposited to a child address are automatically consolidated into your master wallet. This keeps treasury management simple, all funds sit in one place, and you track user balances in your own database.

<Warning>
  For auto sweep to work, your master wallet must hold native tokens to cover gas fees. Find the master wallet deposit address on the wallet overview page and send testnet tokens there.
</Warning>

**Testnet faucets for gas tokens:**

| Network          | Token | Faucet                                                                                   |
| ---------------- | ----- | ---------------------------------------------------------------------------------------- |
| Base Sepolia     | ETH   | [alchemy.com/faucets/base-sepolia](https://www.alchemy.com/faucets/base-sepolia)         |
| Ethereum Sepolia | ETH   | [alchemy.com/faucets/ethereum-sepolia](https://www.alchemy.com/faucets/ethereum-sepolia) |
| BNB Testnet      | BNB   | [bnbchain.org/en/testnet-faucet](https://www.bnbchain.org/en/testnet-faucet)             |
| Polygon Testnet  | MATIC | [faucet.polygon.technology](https://faucet.polygon.technology/)                          |
| Tron Testnet     | TRX   | [nileex.io](https://nileex.io/join/getJoinPage)                                          |
| Solana Devnet    | SOL   | [faucet.solana.com](https://faucet.solana.com/)                                          |
| Celo Alfajores   | CELO  | [faucet.celo.org/alfajores](https://faucet.celo.org/alfajores)                           |
| Avalanche Fuji   | AVAX  | [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/)                  |

**Testnet stablecoin faucets:**

| Network                            | Token | Faucet                                                                       |
| ---------------------------------- | ----- | ---------------------------------------------------------------------------- |
| Base / Ethereum / Polygon / Solana | USDC  | [faucet.circle.com](https://faucet.circle.com/)                              |
| BNB Testnet                        | USDT  | [bnbchain.org/en/testnet-faucet](https://www.bnbchain.org/en/testnet-faucet) |

### Gasless transactions

When `enableGaslessWithdraw: true`, your users can send stablecoins from their address without holding any native tokens. Your master wallet covers the gas on their behalf. This removes the biggest UX friction in crypto onboarding.

### Set defaults globally

Instead of configuring each address individually, you can set defaults for the entire master wallet:

1. Go to your master wallet
2. Click **Configurations**
3. Set `disableAutoSweep` and `enableGaslessWithdraw`

<Note>
  Configuration set at the address level overrides the master wallet config. Use address-level config only when you need exceptions.
</Note>

***

## Step 5: Set up webhooks

Blockradar uses webhooks to notify your backend when blockchain events happen, deposits, withdrawals, sweeps, and more. Set this up before testing transactions.

### Register your webhook endpoint

1. Go to your master wallet in the dashboard
2. Click **Developer → Webhook**
3. Enter your backend endpoint URL (must be a `POST` endpoint)

### Handle webhooks in your backend

```javascript theme={null}
app.post("/webhook-handler", (req, res) => {
  const event = req.body;
  console.log("Webhook received:", event);
  // Handle event based on event type
  res.sendStatus(200);
});
```

### Common webhook events

| Event                   | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `deposit.success`       | A deposit was received at a child address                  |
| `deposit.swept.success` | Funds were swept from a child address to the master wallet |
| `withdraw.success`      | A withdrawal was sent successfully                         |
| `swap.success`          | A swap was executed successfully                           |

<Card title="Full webhook reference" icon="webhook" href="/en/utilities/webhooks">
  See all event types, payload schemas, retry logic, and HMAC verification.
</Card>

***

## Step 6: Handle a deposit event

When a user sends USDC to their address, Blockradar fires a `deposit.success` event to your webhook endpoint.

### Sample payload

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "amountPaid": "10.0",
    "currency": "USD",
    "senderAddress": "0xabc...",
    "recipientAddress": "0xdef...",
    "metadata": {
      "user_id": 1234
    }
  }
}
```

### How to process it

<Steps>
  <Step title="Identify the user">
    Extract `metadata.user_id` from the payload. This maps the deposit to a user in your database.
  </Step>

  <Step title="Read the amount">
    Use `data.amountPaid` to determine how much was deposited. Apply any deposit fee by subtracting from this value before saving.
  </Step>

  <Step title="Update the balance">
    Credit the user's balance in your database. If auto sweep is enabled, the funds are already in your master wallet.
  </Step>
</Steps>

***

## What you've built

You now have a complete stablecoin payment flow:

* A master wallet on testnet
* Child addresses tied to users via metadata
* Auto sweep consolidating funds into your treasury
* Gasless transactions removing friction for your users
* A webhook handler updating balances in real time

## Where to go next

<CardGroup cols={2}>
  <Card title="Send payouts" icon="arrow-up-from-bracket" href="/en/use-cases/pay-outs">
    Send stablecoins to your users or partners programmatically.
  </Card>

  <Card title="Add AML screening" icon="shield-halved" href="/en/use-cases/asset-recovery">
    Screen addresses before sending or receiving funds.
  </Card>

  <Card title="Explore swaps" icon="arrows-rotate" href="/en/use-cases/swap">
    Let users swap between stablecoins with a single API call.
  </Card>

  <Card title="Go live" icon="rocket" href="https://dashboard.blockradar.co">
    Enable Live Mode in the dashboard and start accepting real funds.
  </Card>
</CardGroup>