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

# Multi-Address Webhooks

Multi-address webhooks let a single subscription monitor up to **100 EVM wallet addresses** for ERC-20 transfer activity on Base. Instead of creating one subscription per address, you create one subscription and pass a list of addresses. Events arrive with \~2s average freshness from chain tip.

<Info>
  Multi-address webhooks are live in production (API-only). Portal interface support is coming soon.
</Info>

<Warning>
  Multi-address webhooks cover **ERC-20 token transfers only** (to and from). Native ETH transfers are not currently supported.
</Warning>

## When to use this

| Scenario                       | Use `wallet.activity.multi`                              |
| ------------------------------ | -------------------------------------------------------- |
| Exchange deposit monitoring    | ✅ Watch hundreds of user deposit addresses               |
| Portfolio tracker              | ✅ Track all user wallets under one project               |
| Payment wallet                 | ✅ Monitor incoming transfers across a fleet of addresses |
| Agentic / automation use cases | ✅ React to transfers on a dynamic set of addresses       |
| Single address monitoring      | Use `wallet.activity.detected` instead                   |

## Prerequisites

<AccordionGroup>
  <Accordion title="A Secret API Key">
    Sign up at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com), then navigate to [API Keys](https://portal.cdp.coinbase.com/projects/api-keys) and select **Create API key** under the **Secret API Keys** tab.

    1. Enter an API key nickname (restrictions are optional)
    2. Click **Create**
    3. Secure your API Key ID and Secret in a safe location
  </Accordion>

  <Accordion title="A webhook URL">
    You'll need an HTTPS URL to receive webhook events. For quick testing, [webhook.site](https://webhook.site) gives free temporary URLs instantly.

    For production, use your own HTTPS endpoint.
  </Accordion>

  <Accordion title="CDP CLI">
    The [CDP CLI](/get-started/build-with-ai/cdp-for-agents) handles authentication and exposes webhook subscription endpoints as typed commands (`cdp data webhooks subscriptions create`, `list`, `update`, `delete`). For raw HTTP, use `cdp api`.

    ```bash theme={null}
    npm install -g @coinbase/cdp-cli
    cdp env live --key-file ./cdp_api_key.json
    cdp data webhooks subscriptions list
    ```
  </Accordion>
</AccordionGroup>

## 1. Review the configuration

Create a JSON payload with event type `wallet.activity.multi` and a `wallet_addresses` label containing a comma-separated list of EVM addresses.

```json title="multi-address.json" theme={null}
{
  "description": "Multi-address ERC-20 monitor",
  "eventTypes": [
    "wallet.activity.multi"
  ],
  "target": {
    "url": "https://your-webhook-url.com",
    "method": "POST"
  },
  "labels": {
    "wallet_addresses": "0xAddress1,0xAddress2,0xAddress3",
    "network": "base-mainnet"
  },
  "isEnabled": true
}
```

### Configuration fields

| Field                     | Description                                      | Required | Notes                                      |
| ------------------------- | ------------------------------------------------ | -------- | ------------------------------------------ |
| `target.url`              | Your webhook endpoint URL                        | Yes      | Must be a valid HTTPS URL                  |
| `labels.wallet_addresses` | Comma-separated list of EVM addresses to monitor | Yes      | Up to 100 addresses per subscription       |
| `labels.network`          | Network name                                     | No       | `base-mainnet` (default) or `base-sepolia` |
| `eventTypes`              | Must be `["wallet.activity.multi"]`              | Yes      |                                            |
| `isEnabled`               | Enable/disable webhook                           | No       | Defaults to `true`                         |
| `target.headers`          | Custom HTTP headers                              | No       | Object with header key-value pairs         |

<Note>
  The 100-address cap is per subscription. You can create multiple subscriptions to monitor more addresses.
</Note>

## 2. Create subscription

Create the webhook subscription with the CDP CLI:

```bash lines theme={null}
cdp data webhooks subscriptions create \
  description="Multi-address ERC-20 monitor" \
  'eventTypes:=["wallet.activity.multi"]' \
  target.url=https://your-webhook-url.com \
  target.method=POST \
  'labels.wallet_addresses=0xAddress1,0xAddress2,0xAddress3' \
  labels.network=base-mainnet \
  isEnabled:=true
```

Response:

```json title="response.json" theme={null}
{
  "createdAt": "2026-04-15T10:00:00.000000Z",
  "description": "Multi-address ERC-20 monitor",
  "eventTypes": [
    "wallet.activity.multi"
  ],
  "isEnabled": true,
  "labels": {
    "project": "<YOUR_CDP_PROJECT_ID>",
    "wallet_addresses": "0xAddress1,0xAddress2,0xAddress3",
    "network": "base-mainnet"
  },
  "metadata": {
    "secret": "<SECRET_FOR_WEBHOOK_VERIFICATION>"
  },
  "subscriptionId": "<YOUR_SUBSCRIPTION_ID>",
  "target": {
    "url": "https://your-webhook-url.com"
  }
}
```

## 3. Receive and handle events

When any ERC-20 transfer involves one of your monitored addresses, your endpoint receives a `wallet.activity.multi` event. The payload includes a `direction` field indicating whether your address was the sender, receiver, or both.

```json title="event-payload.json" theme={null}
{
  "id": "evt_1a2b3c4d5e6f",
  "type": "wallet.activity.multi",
  "createdAt": "2026-04-15T10:01:00.000000Z",
  "data": {
    "subscriptionId": "<YOUR_SUBSCRIPTION_ID>",
    "network": "base-mainnet",
    "matchedAddress": "0xAddress1",
    "direction": "to",
    "transactionHash": "0xabc123...",
    "blockNumber": 40000000,
    "logIndex": 12,
    "contractAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "from": "0xAddress2",
    "to": "0xAddress1",
    "value": "5000000"
  }
}
```

<Note>
  `value` is the raw token amount with no decimal adjustment. For a 6-decimal token like USDC, `5000000` equals \$5.00.
</Note>

### Direction values

| Value  | Meaning                                       |
| ------ | --------------------------------------------- |
| `to`   | One of your addresses received the transfer   |
| `from` | One of your addresses sent the transfer       |
| `both` | Both `from` and `to` are in your address list |

## Manage your subscription

<Note>
  To list, update, or delete your subscription, use the same endpoints described in the [Webhooks Quickstart](/webhooks/quickstart#manage-subscriptions). When updating, pass the full revised `wallet_addresses` list in the `labels` field.
</Note>

## Limits and rate limiting

* **Address cap**: up to 100 addresses per subscription
* **Rate limit**: 2 webhook events per second per project. Events that exceed this limit may not be delivered. The rate limit is subject to change.
* **Freshness**: \~2s average latency from chain tip to delivery
* **Supported networks**: Base mainnet, Base Sepolia
* **Delivery guarantees**: at-least-once, with retries and DLQ via the Webhooks 2.0 stack

## What to read next

<CardGroup cols={2}>
  <Card title="Verify signatures" icon="shield-check" href="/webhooks/verify-signatures">
    Validate that events are coming from Coinbase.
  </Card>

  <Card title="Wallet webhooks" icon="wallet" href="/webhooks/wallets">
    Track the full transaction lifecycle, signing operations, and delegation events.
  </Card>

  <Card title="Onchain Activity" icon="wave-pulse" href="/webhooks/onchain-activity/overview">
    Monitor smart contract events and ERC-20 transfers on Base.
  </Card>

  <Card title="Webhooks Overview" icon="bell" href="/webhooks/overview">
    Delivery guarantees, use cases, and supported networks.
  </Card>
</CardGroup>