Skip to main content
POST
/
v1
/
evm
/
prices
/
spot
/
crypto
/
vwap-aggregate
curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "from_block": 18930000,
  "to_block": 18939999,
  "bucket_seconds": 3600,
  "dense": false,
  "limit": 200,
  "cursor": null
}'

{
  "meta": {
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "request_window": {
      "from_block": 18930000,
      "to_block": 18939999,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "resolved_window": {
      "from_block": 18930000,
      "to_block": 18939999,
      "from_timestamp": "2024-01-11T13:00:00Z",
      "to_timestamp": "2024-01-12T22:00:00Z"
    },
    "filters": {
      "bucket_seconds": 3600,
      "dense": false
    }
  },
  "data": [
    {
      "bucket_start": "2025-11-11T18:00:00.000Z",
      "bucket_end": "2025-11-11T19:00:00.000Z",
      "bucket_seconds": 3600,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "price_vwap": "3024.112233445566778899",
      "total_volume_in_raw": "580000000000000000000",
      "total_volume_in": "580.000000000000000000",
      "total_volume_out_raw": "1750000000000",
      "total_volume_out": "1750000.000000000000000000",
      "trade_count": 142,
      "pool_count": 23,
      "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": "0505000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T19:00:05.000Z",
      "_updated_at": "2025-11-11T19: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.

​
Bucket Controls

​
bucket_seconds
number
required
Bucket width in seconds. Allowed values: 60, 300, 900, 1800, 3600, 14400, 86400.
​
dense
boolean
default:"false"
Gap-fill: one row per bucket in the requested window. Gap buckets LOCF the last price_vwap, with zero volumes, trade_count=0, and pool_count=0.LOCF seeds from the last cross-pool bar before the window start when available, then from in-window bars (same 0505 table).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[]
Cross-pool VWAP aggregates matching the request; each object uses the same field names as 0505.
​
data.bucket_start
string
Inclusive UTC start of the VWAP bucket (ISO-8601).
​
data.bucket_end
string
Exclusive UTC end of the VWAP 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.token_in
string
Input token address (hex, 20 bytes, no 0x prefix).
​
data.token_out
string
Output token address (hex, 20 bytes, no 0x prefix).
​
data.price_vwap
string | null
Cross-venue VWAP (quote_token_address per 1 base_token_address, decimals-adjusted). null only when no prior bar exists for this pair and bucket_seconds before the window ends. In dense mode, gap buckets LOCF the last price (including pre-window bars).
​
data.total_volume_in_raw
string
Sum of raw UInt256 amountIn values across all contributing pools. "0" for carry-forward buckets in dense mode.
​
data.total_volume_in
string | null
Decimal-adjusted token_in volume. null when token decimals are unknown. "0" for carry-forward buckets in dense mode when decimals are known.
​
data.total_volume_out_raw
string
Sum of raw UInt256 amountOut values across all contributing pools. "0" for carry-forward buckets in dense mode.
​
data.total_volume_out
string | null
Decimal-adjusted token_out volume. null when token decimals are unknown. "0" for carry-forward buckets in dense mode when decimals are known.
​
data.trade_count
number
Total swaps across all contributing pools. 0 for carry-forward buckets in dense mode.
​
data.pool_count
number
Distinct pools that contributed to 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 per-pool VWAP (0405) bars; 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 VWAP entries returned in this page.

​
Usage Notes

curl -X POST "https://api.blockdb.io/v1/evm/prices/spot/crypto/vwap-aggregate" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
  "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "from_block": 18930000,
  "to_block": 18939999,
  "bucket_seconds": 3600,
  "dense": false,
  "limit": 200,
  "cursor": null
}'

{
  "meta": {
    "chain_id": 1,
    "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "request_window": {
      "from_block": 18930000,
      "to_block": 18939999,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "resolved_window": {
      "from_block": 18930000,
      "to_block": 18939999,
      "from_timestamp": "2024-01-11T13:00:00Z",
      "to_timestamp": "2024-01-12T22:00:00Z"
    },
    "filters": {
      "bucket_seconds": 3600,
      "dense": false
    }
  },
  "data": [
    {
      "bucket_start": "2025-11-11T18:00:00.000Z",
      "bucket_end": "2025-11-11T19:00:00.000Z",
      "bucket_seconds": 3600,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "price_vwap": "3024.112233445566778899",
      "total_volume_in_raw": "580000000000000000000",
      "total_volume_in": "580.000000000000000000",
      "total_volume_out_raw": "1750000000000",
      "total_volume_out": "1750000.000000000000000000",
      "trade_count": 142,
      "pool_count": 23,
      "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": "0505000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T19:00:05.000Z",
      "_updated_at": "2025-11-11T19:00:05.000Z"
    }
  ],
  "cursor": null,
  "page_count": 1
}
Last modified on May 29, 2026