explorer-monorepo/docs/specs/api/etherscan-compatible-api.md

Etherscan-Compatible API Specification

Overview

This document specifies the Etherscan-compatible API layer that provides an API surface matching Blockscout/Etherscan APIs for tool compatibility and easier migration.

Base URL: https://api.explorer.d-bis.org/api

Note: This is a compatibility layer that translates Etherscan API calls to our internal API.

API Surface Mapping

Account Endpoints

Get Account Balance

Etherscan: GET /api?module=account&action=balance&address={address}&tag=latest

Our Implementation:

• Maps to: GET /v1/addresses/{chain_id}/{address} (extract balance)

Response Format (matches Etherscan):

{
  "status": "1",
  "message": "OK",
  "result": "1000000000000000000"
}

Get Token Balance

Etherscan: GET /api?module=account&action=tokenbalance&contractaddress={token}&address={address}&tag=latest

Our Implementation:

• Maps to: GET /v1/addresses/{chain_id}/{address}/tokens (filter by token address)

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": "1000000000000000000"
}

Get Transaction List

Etherscan: GET /api?module=account&action=txlist&address={address}&startblock=0&endblock=99999999&page=1&offset=10&sort=desc

Our Implementation:

• Maps to: GET /v1/addresses/{chain_id}/{address}/transactions (with pagination)

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "blockNumber": "12345",
      "timeStamp": "1640995200",
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "gas": "21000",
      "gasPrice": "20000000000",
      "gasUsed": "21000",
      "isError": "0",
      "txreceipt_status": "1"
    }
  ]
}

Transaction Endpoints

Get Transaction Status

Etherscan: GET /api?module=transaction&action=getstatus&txhash={hash}

Our Implementation:

• Maps to: GET /v1/transactions/{chain_id}/{hash} (extract status)

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": {
    "isError": "0",
    "errDescription": ""
  }
}

Get Transaction Receipt Status

Etherscan: GET /api?module=transaction&action=gettxreceiptstatus&txhash={hash}

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": {
    "status": "1"
  }
}

Block Endpoints

Get Block by Number

Etherscan: GET /api?module=proxy&action=eth_getBlockByNumber&tag={number}&boolean=true

Our Implementation:

• Maps to: GET /v1/blocks/{chain_id}/{number} (transform format)

Response Format (Ethereum JSON-RPC format):

{
  "jsonrpc": "2.0",
  "result": {
    "number": "0x3039",
    "hash": "0x...",
    "transactions": [...]
  }
}

Contract Endpoints

Get Contract ABI

Etherscan: GET /api?module=contract&action=getabi&address={address}

Our Implementation:

• Maps to: GET /v1/contracts/{chain_id}/{address}/abi

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": "[{...}]"
}

Verify Contract

Etherscan: POST /api?module=contract&action=verifysourcecode

Our Implementation:

• Maps to: POST /v1/contracts/{chain_id}/{address}/verify

Parameter Mapping:

• sourceCode → source_code
• codeformat → verification_method
• contractaddress → address
• compilerversion → compiler_version

Token Endpoints

Get Token Total Supply

Etherscan: GET /api?module=stats&action=tokensupply&contractaddress={address}

Our Implementation:

• Maps to: GET /v1/tokens/{chain_id}/{address} (extract total_supply)

Event Logs

Get Event Logs

Etherscan: GET /api?module=logs&action=getLogs&address={address}&topic0={topic0}&fromBlock={fromBlock}&toBlock={toBlock}

Our Implementation:

• Maps to: GET /v1/logs (with filters)

Response Format:

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "address": "0x...",
      "topics": ["0x..."],
      "data": "0x...",
      "blockNumber": "0x3039",
      "transactionHash": "0x...",
      "logIndex": "0x0"
    }
  ]
}

Parameter Translation

Common Parameters

Etherscan	Our API	Notes
module	N/A	Determines endpoint category
action	N/A	Determines specific action
address	address	Same
tag	block_number	Convert "latest" to current block
startblock	from_block	Same
endblock	to_block	Same
page	page	Same
offset	page_size	Same
sort	order	Same (asc/desc)

Chain ID Handling

Etherscan: No chain_id parameter (single chain)

Our API: Require chain_id parameter or use default from context

Mapping: Add chain_id parameter to all requests

Response Format Compatibility

Status Codes

Etherscan Format:

• status: "1" = Success
• status: "0" = Error

Our Format:

• HTTP 200 = Success (map to status "1")
• HTTP 4xx/5xx = Error (map to status "0")

Error Messages

Etherscan Format:

{
  "status": "0",
  "message": "NOTOK",
  "result": "Error message here"
}

Our Mapping:

• Map our error codes to Etherscan error messages
• Preserve error details in result field

Migration Guide

For Tools Using Etherscan API

Step 1: Update base URL

• Old: https://api.etherscan.io/api
• New: https://api.explorer.d-bis.org/api

Step 2: Add chain_id parameter (if needed)

• Add &chainid=138 to requests
• Or use default chain from connection

Step 3: Test compatibility

• Verify response formats match
• Check error handling
• Validate data accuracy

For New Integrations

Recommendation: Use native REST API instead of Etherscan-compatible API

• More features
• Better performance
• Clearer API design

Limitations

Not All Endpoints Supported

Supported:

• Account operations
• Transaction queries
• Block queries
• Contract verification
• Token operations
• Event logs

Not Supported (Etherscan-specific):

• Gas tracker (use our analytics API)
• Historical stats (use our analytics API)
• Token list (use our token API)

Response Format Differences

Some differences may exist:

• Field naming (camelCase vs snake_case)
• Data precision
• Additional fields in our responses

Implementation

Translation Layer

Architecture:

• Request interceptor: Parse Etherscan-style requests
• Parameter mapper: Convert to our API format
• Response transformer: Convert our responses to Etherscan format

Code Structure:

compatibility/
├── etherscan/
│   ├── request_parser.py    # Parse Etherscan requests
│   ├── parameter_mapper.py  # Map parameters
│   └── response_transformer.py  # Transform responses

References

• REST API: See rest-api.md
• API Gateway: See api-gateway.md