Skip to main content
POST
https://api.blockdb.io
/
v1
/
evm
/
pools
curl -X POST "https://api.blockdb.io/v1/evm/pools" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "from_timestamp": "2025-10-29T00:00:00Z",
  "to_timestamp": "2025-11-11T00:00:00Z",
  "exchange_ids": [
    1,
    2
  ],
  "pool_type_ids": [
    1,
    2,
    4
  ],
  "address": "1234567890abcdef1234567890abcdef12345678"
}'

{
  "chain_id": 1,
  "meta": {
    "request_window": {
      "from_block": 12345678,
      "to_block": 12345999,
      "from_timestamp": "2025-10-29T00:00:00Z",
      "to_timestamp": "2025-11-11T00:00:00Z"
    },
    "filters": {
      "exchange_ids": [
        1,
        2
      ],
      "pool_type_ids": [
        1,
        2,
        4
      ],
      "address": "1234567890abcdef1234567890abcdef12345678"
    }
  },
  "data": [
    {
      "chain_id": 1,
      "uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "contract_address": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "pool_id": null,
      "factory": "1F98431c8aD98523631AE4a59f267346ea31F984",
      "pool_manager": "0000000000000000000000000000000000000000",
      "type_id": 2,
      "pair_number": 42,
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "assets_managers": null,
      "amp": null,
      "weights": [
        0.5,
        0.5
      ],
      "tick_spacing": null,
      "block_number": 567890,
      "block_time": "2018-07-07T12:34:56Z",
      "tx_index": 4,
      "log_index": 2,
      "_tracing_id": "0203000000000000000000000000000000000001",
      "_genesis_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    },
    ...
  ],
  "cursor": null,
  "count": 1
}

​
Description

Retrieves a list of pools based on the provided filters.

​
Parameters

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

​
Range Filters (mutually exclusive)

​
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, or at least one direct selector.
Providing more than one option results in HTTP 400.
Providing none results in HTTP 400.

​
Pool Selectors

​
address
string
Specific pool address to return (hex string, 20 bytes, no 0x prefix).
​
exchange_ids
number[]
Filter snapshots by exchange IDs. See the DigitalExchange enumeration for supported values.
​
pool_type_ids
number[]
Filter pools by archetype. See the PoolType enumeration for supported values.

​
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
Normalized block/timestamp bounds derived from the request.
​
meta.filters
object
Filter parameters echoed from the request.

​
Data

​
data
object[]
Array of pool objects.
​
data.chain_id
number
Chain ID for the pool record.
​
data.uid
string
BlockDB internal pool identifier (derived from address or pool_id).
​
data.exchange_id
number
Exchange identifier.
See the DigitalExchange enumeration for supported values.
​
data.contract_address
string
Pool contract address.
​
data.pool_id
string | null
Pool identifier used by Uniswap V4 / Balancer V2-style pools.
​
data.factory
string
Factory contract that created the pool.
​
data.pool_manager
string | null
Address of the pool manager contract for Uniswap V4 pools.
​
data.type_id
number
Integer identifier of the pool type.
See the PoolType enumeration for supported values.
​
data.pair_number
number | null
BlockDB-assigned ordinal for the pair within the exchange (when applicable).
​
data.tokens
string[]
Token contract addresses that compose the pool.
​
data.assets_managers
string[] | null
Asset manager contracts for Balancer-style pools.
​
data.amp
number | null
Amplification parameter for Balancer Stable pools.
​
data.weights
number[] | null
Token weights for Balancer Weighted pools.
​
data.tick_spacing
number | null
Tick spacing for Uniswap V3-style pools.
​
data.block_number
number
Block number of the pool-creation event.
​
data.tx_index
number
Transaction index within the genesis block.
​
data.log_index
number
Log index within the genesis transaction.
​
data.block_time
string
Block timestamp joined from the blocks table for easier selection and grouping.
​
data._tracing_id
string
Row-level lineage hash (hex string, no 0x prefix).
​
data._parent_tracing_ids
string[]
Lineage references of immediate parents.
​
data._genesis_tracing_ids
string[]
Lineage references to the original on-chain events.
​
data._created_at
string
Record creation timestamp, e.g. "2025-11-11T18:42:15.123Z".
​
data._updated_at
string
Last update timestamp in the same format.

​
Envelope Fields

​
cursor
string | null
Cursor token for pagination.
​
count
number
Number of records returned in data.
curl -X POST "https://api.blockdb.io/v1/evm/pools" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "from_block": 12345678,
  "to_block": 12345999,
  "from_timestamp": "2025-10-29T00:00:00Z",
  "to_timestamp": "2025-11-11T00:00:00Z",
  "exchange_ids": [
    1,
    2
  ],
  "pool_type_ids": [
    1,
    2,
    4
  ],
  "address": "1234567890abcdef1234567890abcdef12345678"
}'

{
  "chain_id": 1,
  "meta": {
    "request_window": {
      "from_block": 12345678,
      "to_block": 12345999,
      "from_timestamp": "2025-10-29T00:00:00Z",
      "to_timestamp": "2025-11-11T00:00:00Z"
    },
    "filters": {
      "exchange_ids": [
        1,
        2
      ],
      "pool_type_ids": [
        1,
        2,
        4
      ],
      "address": "1234567890abcdef1234567890abcdef12345678"
    }
  },
  "data": [
    {
      "chain_id": 1,
      "uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "contract_address": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
      "pool_id": null,
      "factory": "1F98431c8aD98523631AE4a59f267346ea31F984",
      "pool_manager": "0000000000000000000000000000000000000000",
      "type_id": 2,
      "pair_number": 42,
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "assets_managers": null,
      "amp": null,
      "weights": [
        0.5,
        0.5
      ],
      "tick_spacing": null,
      "block_number": 567890,
      "block_time": "2018-07-07T12:34:56Z",
      "tx_index": 4,
      "log_index": 2,
      "_tracing_id": "0203000000000000000000000000000000000001",
      "_genesis_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_parent_tracing_ids": [
        "0103000000000000000000000000000000000001",
        "0103000000000000000000000000000000000002"
      ],
      "_created_at": "2025-11-11T18:42:15.123Z",
      "_updated_at": "2025-11-11T18:42:15.123Z"
    },
    ...
  ],
  "cursor": null,
  "count": 1
}