Skip to main content
POST
/
v1
/
evm
/
prices
/
spot
/
crypto
/
ohlc
curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "from_timestamp": "2025-11-11T00:00:00Z",
  "to_timestamp": "2025-11-11T01:00:00Z",
  "exchange_ids": [1, 2],
  "bucket_seconds": 60,
  "dense": false,
  "limit": 200,
  "cursor": null
}'

{
  "meta": {
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "request_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-11-11T00:00:00Z",
      "to_timestamp": "2025-11-11T01:00:00Z"
    },
    "resolved_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-11-11T00:00:00Z",
      "to_timestamp": "2025-11-11T01:00:00Z"
    },
    "filters": {
      "exchange_ids": [1, 2],
      "pool_uids": null,
      "bucket_seconds": 60,
      "dense": false
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "bucket_start": "2025-11-11T00:00:00.000Z",
      "bucket_end": "2025-11-11T00:01:00.000Z",
      "bucket_seconds": 60,
      "open": "3010.112233445566778899",
      "high": "3033.998877665544332211",
      "low": "3008.001122334455667788",
      "close": "3025.219821481234567890",
      "volume_base_raw": "420000000000000000000",
      "volume_base": "420.000000000000000000",
      "volume_quote_raw": "1269000000000",
      "volume_quote": "1269000.000000000000000000",
      "trades_count": 128,
      "block_bucket_first_block_number": null,
      "block_bucket_last_block_number": null,
      "block_bucket_first_block_timestamp": null,
      "block_bucket_last_block_timestamp": null,
      "block_bucket_block_count": null,
      "_tracing_id": "0404000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T01:00:05.000Z",
      "_updated_at": "2025-11-11T01:00:05.000Z"
    }
  ],
  "cursor": null,
  "page_count": 1
}
Not available on the public API yet: This endpoint is scheduled to become available by the end of May 2026. Until then, calls may fail (for example with 404, 403, or 501). For early access or contract timelines, contact support@blockdb.io.

​
Overview

​
Parameters

​
chain_id
number
required
Target EVM chain. See the Chain enumeration for supported values.
​
base_token_address
string
required
ERC-20 contract address for the base asset (hex string, 20 bytes, no 0x prefix).
​
quote_token_address
string
required
ERC-20 contract address for the quote asset (hex string, 20 bytes, no 0x prefix).

​
Range Filters (mutually exclusive)

​
from_block
number
Starting block (inclusive). Block ranges use strict containment: only buckets whose entire span maps to blocks within [from_block, to_block] are returned, so each bar aggregates only blocks inside your range. The partial bucket that merely contains from_block (and also spans earlier blocks) is excluded. A range narrower than one bucket_seconds returns no bars. Use with to_block.
​
to_block
number
Ending block (inclusive). The partial bucket that contains to_block (and also spans later blocks) is excluded — only buckets ending at or before to_block’s timestamp are returned. Use with from_block.
​
from_timestamp
string
Window start (ISO-8601, inclusive). Used directly as bucket_start >= from_timestamp. Use with to_timestamp.
​
to_timestamp
string
Window end (ISO-8601, inclusive). Buckets with bucket_end <= to_timestamp are included. Use with from_timestamp.
Provide either a block range (from_block + to_block) or a time range (from_timestamp + to_timestamp), not both. Omitting both is HTTP 400.

​
Direct Selectors

​
exchange_ids
number[]
Filter by exchange identifiers. See the DigitalExchange enumeration.
​
pool_uids
string[]
Restrict to specific BlockDB pool identifiers.

​
Candle Controls

​
bucket_seconds
number
required
Candle width in seconds. Allowed values: 60, 300, 900, 1800, 3600, 14400, 86400.
​
dense
boolean
default:"false"
Gap-fill: one row per pool per bucket in the requested window. Gap buckets LOCF the last close (flat candle: open=high=low=close), with zero volumes and trades_count=0.Eligible pools have at least one bar for this pair and bucket_seconds on or before the window end (same 0404 table). LOCF seeds from the last bar before the window start when available, then from in-window bars.Works with a timestamp or block range (blocks resolve to timestamps, then align to bucket boundaries).

​
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

​
Meta

​
meta
object
Echo of request metadata applied to the response.
​
meta.chain_id
number
EVM chain ID echoed from the request.
​
meta.base_token_address
string
ERC-20 contract address of the base asset, echoed from the request.
​
meta.quote_token_address
string
ERC-20 contract address of the quote asset, echoed from the request.
​
meta.request_window
object
Pure echo of the window you sent (from_block/to_block/from_timestamp/to_timestamp); unset bounds are null.
​
meta.resolved_window
object | null
The concrete window the query actually executed against, after resolving the request. For a block range on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), from_timestamp/to_timestamp hold the resolved timestamp window (and from_block/to_block echo your request). For a time range on a block-keyed endpoint, from_block/to_block hold the resolved block range (and the timestamps echo your request). null for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
​
meta.resolved_window.from_block
number | null
Resolved/echoed start block of the executed window.
​
meta.resolved_window.to_block
number | null
Resolved/echoed end block of the executed window.
​
meta.resolved_window.from_timestamp
string | null
Resolved/echoed start timestamp (ISO-8601) of the executed window.
​
meta.resolved_window.to_timestamp
string | null
Resolved/echoed end timestamp (ISO-8601) of the executed window.
​
meta.filters
object
Filter parameters echoed from the request.

​
Data

​
data
object[]
OHLC candles matching the request; each object uses the same field names as 0404. When dense=true, one row is returned per pool per bucket for every bucket in the requested window.
​
data.pool_uid
string
BlockDB pool identifier for the candle.
​
data.exchange_id
number
Exchange/DEX identifier.
​
data.type_id
number
Pool type identifier.
​
data.bucket_start
string
Inclusive UTC start of the candle bucket (ISO-8601).
​
data.bucket_end
string
Exclusive UTC end of the candle bucket (ISO-8601). Equal to bucket_start + bucket_seconds.
​
data.bucket_seconds
number
Bucket width in seconds: 60, 300, 900, 1800, 3600, 14400, or 86400.
​
data.open
string | null
Opening price for the bucket (quote_token_address per 1 base_token_address, decimals-adjusted). null only when no prior bar exists for this pool, pair, and bucket_seconds before the window ends.
​
data.high
string | null
Highest price within the bucket. null under the same condition as open.
​
data.low
string | null
Lowest price within the bucket. null under the same condition as open.
​
data.close
string | null
Closing price for the bucket. In dense mode, gap buckets LOCF the last close (including pre-window bars). null only when no LOCF seed exists.
​
data.volume_base_raw
string
Sum of raw UInt256 amountIn values. "0" for carry-forward buckets in dense mode.
​
data.volume_base
string | null
Decimal-adjusted base (base_token_address) volume. null when token decimals are unknown. "0" for carry-forward buckets in dense mode when decimals are known.
​
data.volume_quote_raw
string
Sum of raw UInt256 amountOut values. "0" for carry-forward buckets in dense mode.
​
data.volume_quote
string | null
Decimal-adjusted quote (quote_token_address) volume. null when token decimals are unknown. "0" for carry-forward buckets in dense mode when decimals are known.
​
data.trades_count
number
Trade count in the bucket. 0 for carry-forward buckets in dense mode.
​
data.block_bucket_first_block_number
number | null
First block number in the chain-wide bucket. Populated when dense=true; null in sparse mode.
​
data.block_bucket_last_block_number
number | null
Last block number in the chain-wide bucket. Populated when dense=true; null in sparse mode.
​
data.block_bucket_first_block_timestamp
string | null
Timestamp of the first block in the chain-wide bucket (ISO-8601). Populated when dense=true; null in sparse mode.
​
data.block_bucket_last_block_timestamp
string | null
Timestamp of the last block in the chain-wide bucket (ISO-8601). Populated when dense=true; null in sparse mode.
​
data.block_bucket_block_count
number | null
Block count in the chain-wide bucket. Populated when dense=true; null in sparse mode.
​
data._tracing_id
string | null
BlockDB tracing ID (hex, no 0x prefix). null for synthetic gap-fill rows when dense=true.
​
data._parent_tracing_ids
string[] | null
Tracing IDs of contributing swap prints; optional. null for gap-fill rows and by default.
​
data._created_at
string | null
Record creation timestamp (ISO-8601). null for gap-fill rows.
​
data._updated_at
string | null
Record update timestamp (ISO-8601). null for gap-fill rows.

​
Envelope Fields

​
cursor
string | null
Pagination cursor.
​
page_count
number
Number of candles returned in this page.

​
Usage Notes

  • Pair direction is meta.base_token_address → meta.quote_token_address (token_in → token_out). Row objects do not repeat token addresses.
  • For USD-denominated VWAP buckets, use /evm/prices/spot/fiat/vwap instead of this endpoint.
  • Each row is one pool’s candle for one bucket. Use pool_uids or exchange_ids to narrow results.
  • dense=true works with a timestamp or block range.
curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/ohlc" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "from_timestamp": "2025-11-11T00:00:00Z",
  "to_timestamp": "2025-11-11T01:00:00Z",
  "exchange_ids": [1, 2],
  "bucket_seconds": 60,
  "dense": false,
  "limit": 200,
  "cursor": null
}'

{
  "meta": {
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "request_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-11-11T00:00:00Z",
      "to_timestamp": "2025-11-11T01:00:00Z"
    },
    "resolved_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-11-11T00:00:00Z",
      "to_timestamp": "2025-11-11T01:00:00Z"
    },
    "filters": {
      "exchange_ids": [1, 2],
      "pool_uids": null,
      "bucket_seconds": 60,
      "dense": false
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "bucket_start": "2025-11-11T00:00:00.000Z",
      "bucket_end": "2025-11-11T00:01:00.000Z",
      "bucket_seconds": 60,
      "open": "3010.112233445566778899",
      "high": "3033.998877665544332211",
      "low": "3008.001122334455667788",
      "close": "3025.219821481234567890",
      "volume_base_raw": "420000000000000000000",
      "volume_base": "420.000000000000000000",
      "volume_quote_raw": "1269000000000",
      "volume_quote": "1269000.000000000000000000",
      "trades_count": 128,
      "block_bucket_first_block_number": null,
      "block_bucket_last_block_number": null,
      "block_bucket_first_block_timestamp": null,
      "block_bucket_last_block_timestamp": null,
      "block_bucket_block_count": null,
      "_tracing_id": "0404000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T01:00:05.000Z",
      "_updated_at": "2025-11-11T01:00:05.000Z"
    }
  ],
  "cursor": null,
  "page_count": 1
}
Last modified on May 29, 2026