Developer Platform

Get an API Key

# Request a key with your Ethereum address
curl -X POST https://ethscan.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{
    "ownerAddress": "0xYourAddress",
    "label": "My App"
  }'

# Response:
{
  "id": 1,
  "key": "eths_abc123...",
  "keyPrefix": "eths_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: eths_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-07-01T00:00:00.000Z",
  "data": {
    "hash": "0xabc...",
    "from": "0x111...",
    "to": "0x222...",
    "value": "1000000000000000000",
    "blockNumber": 20000000
  }
}

// Headers included:
// X-EthScan-Signature: sha256=<hmac>
// X-EthScan-Event: tx
// User-Agent: EthScan-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?ownerAddress=0xYourAddress"

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": 20000000,
      "blockTo": 20001000
    },
    "limit": 100
  }'

Supported Entities & Filters