API Reference

EthScan provides a public REST API for accessing Ethereum block explorer data. All endpoints return JSON. Base URL: https://ethscan.io

Rate Limiting: API requests are rate-limited to 100 requests per minute per IP address. Responses include X-RateLimit-Remaining headers.

GET/api/v1/stats

Returns high-level network statistics including the latest block number, total transaction count, total token count, and average gas price.

▶Example Response

{
  "latestBlock": 20000000,
  "totalTransactions": 2500000000,
  "totalTokens": 12000,
  "avgGasPrice": "12000000000"
}

GET/api/v1/blocks

Returns a paginated list of blocks ordered by block number descending.

Parameters

Name	Type	Required	Description
page	number	No	Page number, starting from 1 (default: 1)
limit	number	No	Number of results per page (default: 25, max: 100)

▶Example Response

{
  "blocks": [
    {
      "number": 20000000,
      "hash": "0xabc123...",
      "timestamp": "2024-07-01T00:00:00Z",
      "miner": "0xdef456...",
      "txCount": 180,
      "gasUsed": "15000000",
      "gasLimit": "30000000"
    }
  ],
  "total": 20000000
}

GET/api/v1/transactions

Returns a paginated list of transactions. Optionally filter by address.

Parameters

Name	Type	Required	Description
page	number	No	Page number, starting from 1 (default: 1)
limit	number	No	Number of results per page (default: 25, max: 100)
address	string	No	Filter by from or to address (e.g. 0x...)

▶Example Response

{
  "transactions": [
    {
      "hash": "0x123abc...",
      "blockNumber": 20000000,
      "fromAddress": "0xaaa...",
      "toAddress": "0xbbb...",
      "value": "1000000000000000000",
      "gasPrice": "12000000000",
      "gasUsed": "21000",
      "status": true,
      "timestamp": "2024-07-01T00:00:00Z"
    }
  ],
  "total": 2500000000
}

GET/api/v1/tokens

Returns a paginated list of ERC-20/ERC-721/ERC-1155 tokens tracked by the indexer.

Parameters

Name	Type	Required	Description
page	number	No	Page number, starting from 1 (default: 1)
limit	number	No	Number of results per page (default: 25, max: 100)

▶Example Response

{
  "tokens": [
    {
      "address": "0xccc...",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "type": "ERC20",
      "totalSupply": "83000000000000",
      "holderCount": 5200000
    }
  ],
  "total": 12000
}

GET/api/v1/addresses/:address

Returns detailed information about an address including balance, transaction count, contract status, and recent transactions.

Parameters

Name	Type	Required	Description
address	string	Yes	The Ethereum address (0x-prefixed, 42 chars)

▶Example Response

{
  "address": "0xddd...",
  "balance": "5000000000000000000",
  "txCount": 42,
  "isContract": false,
  "label": null,
  "firstSeen": "2022-01-01T00:00:00Z",
  "lastSeen": "2024-07-01T00:00:00Z",
  "recentTxs": []
}

POST/api/v1/verify

Submit a smart contract for source code verification. The contract bytecode must already be indexed. Checks Sourcify for existing verifications on Ethereum Mainnet (chain ID 1).

Parameters

Name	Type	Required	Description
address	string	Yes	Contract address to verify (0x-prefixed)
compilerVersion	string	Yes	Solidity compiler version (e.g. v0.8.19+commit.7dd6d404)

▶Example Response

{
  "success": true,
  "match": "sourcify",
  "address": "0xeee..."
}

POST/api/v1/contracts/:address/call

Call a read-only (view/pure) function on a verified contract using its ABI. Returns the result with BigInt values serialized as strings.

Parameters

Name	Type	Required	Description
address	string	Yes	Contract address (must be verified with ABI)
functionName	string	Yes	Name of the view/pure function to call
args	array	No	Array of arguments to pass to the function

▶Example Response

{
  "result": "1000000000000000000"
}

GET/api/v1/webhooks

List all webhooks registered to an owner address.

Parameters

Name	Type	Required	Description
owner	string	Yes	Owner Ethereum address (0x-prefixed)

▶Example Response

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://your-app.com/webhook",
      "watchAddress": "0xabc...",
      "eventTypes": [
        "tx",
        "token_transfer"
      ],
      "active": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "lastTriggeredAt": null,
      "failCount": 0
    }
  ]
}

POST/api/v1/webhooks

Register a new webhook. Returns a one-time secret for verifying incoming webhook signatures (HMAC-SHA256). EthScan will POST events to your URL with an X-EthScan-Signature header.

Parameters

Name	Type	Required	Description
ownerAddress	string	Yes	Your Ethereum address (0x-prefixed)
url	string	Yes	Your HTTPS endpoint to receive events
watchAddress	string	No	Address to watch for events
eventTypes	string[]	No	Event types: ["tx", "token_transfer"] (default: ["tx"])

▶Example Response

{
  "id": 1,
  "secret": "abc123...",
  "message": "Webhook created. Keep the secret — it will not be shown again."
}

GET/api/v1/keys

List API keys for an owner address. Key hashes are never returned — only the prefix for identification.

Parameters

Name	Type	Required	Description
owner	string	Yes	Owner Ethereum address (0x-prefixed)

▶Example Response

{
  "keys": [
    {
      "id": 1,
      "keyPrefix": "eths_abc123",
      "label": "My App",
      "requestsPerMinute": 100,
      "totalRequests": 5420,
      "createdAt": "2024-01-01T00:00:00Z",
      "lastUsedAt": "2024-07-01T12:00:00Z",
      "active": true
    }
  ]
}

POST/api/v1/keys

Generate a new API key linked to your Ethereum address. The full key is shown once — save it immediately. Use the X-API-Key header to authenticate requests.

Parameters

Name	Type	Required	Description
ownerAddress	string	Yes	Your Ethereum address (0x-prefixed)
label	string	No	Human-readable label for this key

▶Example Response

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

POST/api/v1/query

Flexible query endpoint for fetching any entity with filters, ordering, and pagination. Supports: transactions, blocks, tokens, token_transfers, dex_trades.

Parameters

Name	Type	Required	Description
entity	string	Yes	One of: transactions, blocks, tokens, token_transfers, dex_trades
filter	object	No	Filter object: { address, from, to, blockNumber, blockFrom, blockTo, tokenAddress, dex }
orderBy	string	No	"asc" or "desc" (default: "desc")
limit	number	No	Number of results (default: 25, max: 100)
offset	number	No	Pagination offset (default: 0)

▶Example Response

{
  "entity": "transactions",
  "count": 25,
  "data": [
    {
      "hash": "0x123...",
      "blockNumber": 20000000,
      "fromAddress": "0xaaa...",
      "toAddress": "0xbbb...",
      "value": "1000000000000000000"
    }
  ]
}