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
    },
    "filters": {
      "exchange_ids": null,
      "bucket_seconds": 3600,
      "dense": false
    }
  },
  "data": [
    {
      "bucket_start": "2025-11-11T18: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,
  "count": 1
}

Documentation Index

Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt

Use this file to discover all available pages before exploring further.

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 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.

​
Direct Selectors

​
exchange_ids
number[]
Optional: restrict contributing venues to specific exchanges. See the DigitalExchange enumeration.

​
Bucket Controls

​
bucket_seconds
number
required
Bucket width in seconds. Allowed values: 60 (1 m), 300 (5 m), 900 (15 m), 3600 (1 h), 86400 (1 d).
​
dense
boolean
default:"false"
When true, the response is gap-filled: one row is emitted per bucket across the entire requested window. Gap buckets carry forward the last observed price_vwap (LOCF) and report zero volume and zero trade_count.Constraints:
  • dense=true requires a timestamp range. Using it with a block range returns HTTP 400.
  • dense=true cannot be combined with exchange_ids. Returns HTTP 400.

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

​
Data

​
data
object[]
Cross-pool VWAP aggregates matching the request.
​
data.bucket_start
string
Inclusive UTC start of the VWAP bucket (ISO-8601).
​
data.bucket_seconds
number
Bucket width in seconds.
​
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 (token_out per 1 token_in, decimals-adjusted). In dense mode, gap buckets carry forward the last observed price (LOCF). null only for gap buckets that precede the first observed trade.
​
data.total_volume_in_raw
string
Sum of raw on-chain UInt256 amountIn values across all contributing pools. "0" for gap buckets in dense mode.
​
data.total_volume_in
string | null
Total traded token_in across all contributing pools (decimals-adjusted). null when token decimals are unavailable. "0" for gap buckets in dense mode (when decimals are known).
​
data.total_volume_out_raw
string
Sum of raw on-chain UInt256 amountOut values across all contributing pools. "0" for gap buckets in dense mode.
​
data.total_volume_out
string | null
Total received token_out across all contributing pools (decimals-adjusted). null when token decimals are unavailable. "0" for gap buckets in dense mode (when decimals are known).
​
data.trade_count
number
Total swaps across all contributing pools. 0 for gap buckets in dense mode.
​
data.pool_count
number
Distinct pools that contributed to the bucket. 0 for gap buckets in dense mode.
​
data.block_bucket_first_block_number
number | null
First block number within the bucket’s time window, from the chain’s block-bucket index.
​
data.block_bucket_last_block_number
number | null
Last block number within the bucket’s time window.
​
data.block_bucket_first_block_timestamp
string | null
Timestamp of the first block in the bucket (ISO-8601).
​
data.block_bucket_last_block_timestamp
string | null
Timestamp of the last block in the bucket (ISO-8601).
​
data.block_bucket_block_count
number | null
Number of blocks mined during the bucket window.
​
data._tracing_id
string | null
Unique BlockDB tracing id for the row (hex string, no 0x prefix). null for synthetic gap-fill rows.
​
data._parent_tracing_ids
string[] | null
Tracing IDs of contributing per-pool VWAP (0405) bars. null for gap-fill rows and by default for real rows.
​
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.
​
count
number
Number of VWAP entries returned.

​
Usage Notes

  • For per-pool VWAP, use POST /evm/prices/spot/crypto/vwap (0405).
  • For USD VWAP buckets, use POST /evm/prices/spot/fiat/vwap (0605).
  • dense=true requires a timestamp range and cannot be combined with exchange_ids.
  • When exchange_ids is provided, the aggregation is computed on-the-fly from per-pool VWAP (0405). Without exchange_ids, the pre-aggregated cross-pool dataset (0505) is used.
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
    },
    "filters": {
      "exchange_ids": null,
      "bucket_seconds": 3600,
      "dense": false
    }
  },
  "data": [
    {
      "bucket_start": "2025-11-11T18: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,
  "count": 1
}
Last modified on May 19, 2026