explorer-monorepo/docs/specs/api/rest-api.md

REST API Specification

Overview

This document specifies the REST API for the explorer platform. The API follows RESTful principles and provides comprehensive access to blockchain data, search, and analytics.

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

Authentication: API Key via X-API-Key header (optional for read-only endpoints with rate limits)

API Design Principles

1. RESTful: Use HTTP methods appropriately (GET, POST, etc.)
2. Consistent: Uniform response format
3. Versioned: /v1 in path, version in response headers
4. Paginated: All list endpoints support pagination
5. Filtered: Support filtering and sorting
6. Documented: OpenAPI 3.0 specification

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100,
      "total_pages": 5
    }
  }
}

Error Response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "details": {},
    "request_id": "uuid"
  }
}

Endpoints

Blocks

List Blocks

GET /blocks

Query Parameters:

• chain_id (integer, required): Chain ID
• page (integer, default: 1): Page number
• page_size (integer, default: 20, max: 100): Items per page
• min_block (integer): Minimum block number
• max_block (integer): Maximum block number
• miner (string): Filter by miner address
• sort (string, default: "number"): Sort field (number, timestamp, gas_used)
• order (string, default: "desc"): Sort order (asc, desc)

Response:

{
  "data": [
    {
      "chain_id": 138,
      "number": 12345,
      "hash": "0x...",
      "timestamp": "2024-01-01T00:00:00Z",
      "miner": "0x...",
      "transaction_count": 100,
      "gas_used": 15000000,
      "gas_limit": 20000000
    }
  ],
  "meta": { "pagination": {...} }
}

Get Block by Number

GET /blocks/{chain_id}/{number}

Response: Single block object

Get Block by Hash

GET /blocks/{chain_id}/hash/{hash}

Response: Single block object

Transactions

List Transactions

GET /transactions

Query Parameters:

• chain_id (integer, required)
• block_number (integer): Filter by block
• from_address (string): Filter by sender
• to_address (string): Filter by recipient
• status (string): Filter by status (success, failed)
• min_value (string): Minimum value
• page, page_size, sort, order

Response: Array of transaction objects

Get Transaction by Hash

GET /transactions/{chain_id}/{hash}

Response: Single transaction object with full details

Includes:

• Transaction data
• Receipt data
• Logs
• Traces (if available)

Get Transaction Receipt

GET /transactions/{chain_id}/{hash}/receipt

Response: Transaction receipt object

Addresses

Get Address Info

GET /addresses/{chain_id}/{address}

Response:

{
  "address": "0x...",
  "chain_id": 138,
  "balance": "1000000000000000000",
  "balance_usd": "3000.00",
  "transaction_count": 500,
  "token_count": 10,
  "label": "My Wallet",
  "tags": ["wallet"],
  "is_contract": false
}

Get Address Transactions

GET /addresses/{chain_id}/{address}/transactions

Query Parameters: Standard pagination and filtering

Response: Array of transactions

Get Address Token Holdings

GET /addresses/{chain_id}/{address}/tokens

Query Parameters:

• type (string): Filter by token type (ERC20, ERC721, ERC1155)
• page, page_size

Response: Array of token holdings with balances

Get Address NFTs

GET /addresses/{chain_id}/{address}/nfts

Response: Array of NFT holdings (ERC-721/1155)

Tokens

List Tokens

GET /tokens

Query Parameters:

• chain_id (integer, required)
• type (string): Filter by type
• verified (boolean): Filter verified tokens
• search (string): Search by name or symbol
• page, page_size, sort, order

Response: Array of token objects

Get Token Info

GET /tokens/{chain_id}/{address}

Response: Token details including metadata

Get Token Holders

GET /tokens/{chain_id}/{address}/holders

Query Parameters: Pagination

Response: Array of holder addresses with balances

Get Token Transfers

GET /tokens/{chain_id}/{address}/transfers

Query Parameters: Pagination, from_address, to_address

Response: Array of token transfers

Contracts

Get Contract Info

GET /contracts/{chain_id}/{address}

Response: Contract details including verification status, source code, ABI

Verify Contract

POST /contracts/{chain_id}/{address}/verify

Request Body:

{
  "compiler_version": "0.8.19",
  "optimization_enabled": true,
  "optimization_runs": 200,
  "source_code": "...",
  "constructor_arguments": "0x...",
  "verification_method": "standard_json"
}

Response: Verification status

Get Contract Source Code

GET /contracts/{chain_id}/{address}/source

Response: Source code and metadata

Get Contract ABI

GET /contracts/{chain_id}/{address}/abi

Response: Contract ABI JSON

Logs

Get Logs

GET /logs

Query Parameters:

• chain_id (integer, required)
• address (string): Filter by contract address
• topic0 (string): Filter by event signature
• from_block (integer): Start block
• to_block (integer): End block
• page, page_size

Response: Array of log objects

Traces

Get Transaction Traces

GET /transactions/{chain_id}/{hash}/traces

Response: Array of trace objects

Get Block Traces

GET /blocks/{chain_id}/{number}/traces

Response: Array of trace objects for all transactions in block

Search

Unified Search

GET /search

Query Parameters:

• chain_id (integer, optional): Filter by chain
• q (string, required): Search query
• type (string): Filter by type (block, transaction, address, token, contract)
• page, page_size

Response: Mixed array of results with type indicators

Analytics

Network Stats

GET /analytics/{chain_id}/network/stats

Response:

{
  "current_block": 12345,
  "tps": 15.5,
  "gps": 30000000,
  "avg_gas_price": 20000000000,
  "pending_transactions": 50
}

Gas Price Statistics

GET /analytics/{chain_id}/gas/price

Query Parameters:

• period (string): Time period (1h, 24h, 7d, 30d)

Response: Gas price statistics (min, max, avg, percentiles)

Top Contracts

GET /analytics/{chain_id}/contracts/top

Query Parameters:

• by (string): Sort by (transactions, gas_used, value)
• limit (integer, default: 100)

Response: Array of top contracts

Pagination

All list endpoints support pagination:

Query Parameters:

• page (integer, default: 1): Page number (1-indexed)
• page_size (integer, default: 20, max: 100): Items per page

Response Metadata:

{
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 500,
      "total_pages": 25,
      "has_next": true,
      "has_prev": false
    }
  }
}

Filtering and Sorting

Common Filter Parameters:

• Date ranges: from_date, to_date
• Block ranges: from_block, to_block
• Value ranges: min_value, max_value
• Address filters: from_address, to_address

Sorting:

• sort (string): Field to sort by
• order (string): asc or desc

Rate Limiting

See API Gateway specification for rate limiting details.

Rate Limit Headers:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

OpenAPI Specification

Full OpenAPI 3.0 specification available at:

• /api-docs/openapi.json
• Interactive docs: /api-docs (Swagger UI)

Versioning

Current Version: v1

Version Header: API-Version: 1

Deprecation: Deprecated endpoints return Deprecation header with deprecation date

References

• API Gateway: See api-gateway.md
• GraphQL API: See graphql-api.md
• Etherscan-Compatible API: See etherscan-compatible-api.md