Skip to main content
POST
https://api.blockdb.io
/
v1
/
evm
/
raw
/
contracts
curl -X POST "https://api.blockdb.io/v1/evm/raw/contracts" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "contract_addresses": [
    "1234567890abcdef1234567890abcdef12345678"
  ],
  "block_numbers": [
    18934001,
    18934222
  ],
  "from_block": 18933000,
  "to_block": 18936000,
  "from_timestamp": null,
  "to_timestamp": null,
  "limit": 200,
  "cursor": null
}'

{
  "chain_id": 1,
  "meta": {
    "request_window": {
      "from_block": 18933000,
      "to_block": 18936000,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "filters": {
      "contract_addresses": [
        "1234567890abcdef1234567890abcdef12345678"
      ],
      "block_numbers": [
        18934001,
        18934222
      ]
    }
  },
  "data": [
    {
      "dataset": "0104_contracts",
      "dataset_id": "0104",
      "chain_id": 1,
      "address": "1234567890abcdef1234567890abcdef12345678",
      "block_number": 18934221,
      "block_time": "2024-04-01T12:34:56Z",
      "tx_index": 7,
      "log_index": 0,
      "_tracing_id": "0104000000000000000000000000000000000001",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  ],
  "cursor": null,
  "count": 1
}

​
Description

Returns deployment metadata for canonical smart contracts. Each record is keyed by the deployed contract address and anchored to the block, transaction, and log tuple that produced it. Use this endpoint to discover when a contract was created and to establish lineage back to the originating transaction and log entries.

​
Parameters

​
chain_id
number
required
Target EVM network. See the Chain enumeration for supported values.

​
Range Filters (mutually exclusive with direct selectors)

​
from_block
number
Starting block number (inclusive) for the query. Use with to_block.
​
to_block
number
Ending block number (inclusive) for the query. Use with from_block.
​
from_timestamp
string
Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with to_timestamp.
​
to_timestamp
string
Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with from_timestamp.
Validation rule:
You must provide either a block range, a time range, block_numbers, or contract_addresses.
Providing both range selectors and explicit selectors results in HTTP 400.
Providing none also results in HTTP 400.

​
Direct Selectors

​
contract_addresses
string[]
Filter by specific deployed contract addresses (hex string, 20 bytes, no 0x prefix). Up to 256 addresses per request.
​
block_numbers
number[]
Explicit list of block heights to fetch contract deployments from. Mutually exclusive with the range filters.

​
Pagination Controls

​
limit
number
default:"250"
Recommended default 250; maximum 1000 to stay under ~10 MB responses.
​
cursor
string
Opaque pagination cursor supplied by a previous response.

​
Response Fields

​
chain_id
number
EVM chain ID echoed at the response root.

​
Meta

​
meta
object
Echo of request metadata applied to the response.
​
meta.request_window
object
Block/timestamp bounds derived from the request.
​
meta.filters
object
Filters echoed from the request (contract addresses, block numbers, limit).

​
Data

​
data
object[]
Contract deployment records sorted by (block_number ASC, address).
​
data.dataset
string
Dataset slug for this collection (0104_contracts).
​
data.dataset_id
string
Canonical dataset identifier (0104).
​
data.chain_id
number
EVM network where the contract was deployed.
​
data.address
string
Deployed contract address (hex string, 20 bytes, no 0x prefix). This is the primary key.
​
data.block_number
number
Block height containing the contract creation.
​
data.block_time
string
ISO-8601 UTC timestamp of the creation block, joined from the blocks dataset.
​
data.tx_index
number
Zero-based index of the deployment transaction within the block.
​
data.log_index
number
Log offset within the deployment transaction. Use to join back to POST /evm/logs.
​
data._tracing_id
string
Unique lineage identifier (hex string, no 0x prefix). Resolves back to the source transaction + log in lineage APIs.
​
data._created_at
string
Timestamp when BlockDB materialized the record.
​
data._updated_at
string
Timestamp of the latest update to the record.

​
Envelope Fields

​
cursor
string | null
Pagination cursor to continue the query.
​
count
number
Number of records in the current page.

​
Use Cases

  • Look up the canonical creation block for a contract address before hydrating additional metadata.
  • Backfill on-chain analyses that require the deployment timestamp or transaction location.
  • Seed lineage exploration using _tracing_id to pivot into /evm/logs and /evm/transactions.
curl -X POST "https://api.blockdb.io/v1/evm/raw/contracts" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "contract_addresses": [
    "1234567890abcdef1234567890abcdef12345678"
  ],
  "block_numbers": [
    18934001,
    18934222
  ],
  "from_block": 18933000,
  "to_block": 18936000,
  "from_timestamp": null,
  "to_timestamp": null,
  "limit": 200,
  "cursor": null
}'

{
  "chain_id": 1,
  "meta": {
    "request_window": {
      "from_block": 18933000,
      "to_block": 18936000,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "filters": {
      "contract_addresses": [
        "1234567890abcdef1234567890abcdef12345678"
      ],
      "block_numbers": [
        18934001,
        18934222
      ]
    }
  },
  "data": [
    {
      "dataset": "0104_contracts",
      "dataset_id": "0104",
      "chain_id": 1,
      "address": "1234567890abcdef1234567890abcdef12345678",
      "block_number": 18934221,
      "block_time": "2024-04-01T12:34:56Z",
      "tx_index": 7,
      "log_index": 0,
      "_tracing_id": "0104000000000000000000000000000000000001",
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    }
  ],
  "cursor": null,
  "count": 1
}