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.

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

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

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

A Secret API Key

Sign up at portal.cdp.coinbase.com, then navigate to API Keys and select Create API key under the Secret API Keys tab.

Enter an API key nickname (restrictions are optional)
Click Create
Secure your API Key ID and Secret in a safe location

A webhook URL

You’ll need an HTTPS URL to receive webhook events. For quick testing, webhook.site gives free temporary URLs instantly.For production, use your own HTTPS endpoint.

CDP CLI

The CDP CLI handles authentication and exposes webhook subscription endpoints as typed commands (cdp data webhooks subscriptions create, list, update, delete). For raw HTTP, use cdp api.

npm install -g @coinbase/cdp-cli
cdp env live --key-file ./cdp_api_key.json
cdp data webhooks subscriptions list

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.

multi-address.json

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

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

2. Create subscription

Create the webhook subscription with the CDP CLI:

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:

response.json

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

event-payload.json

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

value is the raw token amount with no decimal adjustment. For a 6-decimal token like USDC, 5000000 equals $5.00.

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

To list, update, or delete your subscription, use the same endpoints described in the Webhooks Quickstart. When updating, pass the full revised wallet_addresses list in the labels field.

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

Verify signatures

Validate that events are coming from Coinbase.

Wallet webhooks

Track the full transaction lifecycle, signing operations, and delegation events.

Onchain Activity

Monitor smart contract events and ERC-20 transfers on Base.

Webhooks Overview

Delivery guarantees, use cases, and supported networks.

GET STARTED

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

When to use this

Prerequisites

1. Review the configuration

Configuration fields

2. Create subscription

3. Receive and handle events

Direction values

Manage your subscription

Limits and rate limiting

What to read next

Verify signatures

Wallet webhooks

Onchain Activity

Webhooks Overview

​When to use this

​Prerequisites

​1. Review the configuration

​Configuration fields

​2. Create subscription

​3. Receive and handle events

​Direction values

​Manage your subscription

​Limits and rate limiting

​What to read next

Verify signatures

Wallet webhooks

Onchain Activity

Webhooks Overview

When to use this

Prerequisites

1. Review the configuration

Configuration fields

2. Create subscription

3. Receive and handle events

Direction values

Manage your subscription

Limits and rate limiting

What to read next