Developer Platform

Get an API Key

# Step 1 — sign a message with your wallet to prove ownership
# Message format (sign this exact string with eth_sign or personal_sign):
#   BNBScan API Key Request
#   Address: 0xyouraddress
#   Timestamp: <unix ms>
#
# Example using ethers.js:
#   const ts = Date.now()
#   const msg = `BNBScan API Key Request\nAddress: ${addr.toLowerCase()}\nTimestamp: ${ts}`
#   const sig = await signer.signMessage(msg)

# Step 2 — submit the signed request
TS=$(date +%s000)  # current time in milliseconds
SIG="0xYourSignatureHere"

curl -X POST https://ethscan.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d "{
    \"ownerAddress\": \"0xYourAddress\",
    \"label\": \"My App\",
    \"signature\": \"$SIG\",
    \"timestamp\": $TS
  }"

# Response:
{
  "id": 1,
  "key": "bnbs_abc123...",
  "keyPrefix": "bnbs_abc123",
  "message": "API key created. Save it now — the full key will not be shown again."
}

Use Your Key

# Pass your key via the X-API-Key header
curl https://ethscan.io/api/v1/blocks \
  -H "X-API-Key: bnbs_abc123..."

# List your keys
curl "https://ethscan.io/api/v1/keys?owner=0xYourAddress"

Register a Webhook

curl -X POST https://ethscan.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "0xYourAddress",
    "url": "https://your-app.com/webhook",
    "watchAddress": "0xWatchedAddress",
    "eventTypes": ["tx", "token_transfer"]
  }'

# Response:
{
  "id": 42,
  "secret": "abcdef1234...",
  "message": "Webhook created. Keep the secret..."
}

Webhook Payload Format

// POST to your URL:
{
  "event": "tx",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "hash": "0xabc...",
    "from": "0x111...",
    "to": "0x222...",
    "value": "1000000000000000000",
    "blockNumber": 42000000
  }
}

// Headers included:
// X-BNBScan-Signature: sha256=<hmac>
// X-BNBScan-Event: tx
// User-Agent: BNBScan-Webhook/1.0

Verify Signature (Node.js)

const crypto = require('crypto')

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body)
      .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Manage Webhooks

# List your webhooks
curl "https://ethscan.io/api/v1/webhooks?owner=0xYourAddress"

# Delete a webhook
curl -X DELETE https://ethscan.io/api/v1/webhooks/42

Endpoint

Query Transactions by Address

curl -X POST https://ethscan.io/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "transactions",
    "filter": { "address": "0x..." },
    "limit": 50,
    "orderBy": "desc"
  }'

Query Token Transfers in Block Range

curl -X POST https://ethscan.io/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "token_transfers",
    "filter": {
      "tokenAddress": "0x...",
      "blockFrom": 42000000,
      "blockTo": 42001000
    },
    "limit": 100
  }'

Supported Entities & Filters