Skip to main content
POST
/
v1
/
evm
/
yields
curl -X POST "https://api.blockdb.io/v1/evm/yields" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "target_period_days": 30,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "require_full_period": true,
  "limit": 250
}'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "filters": {
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "target_period_days": 30,
      "require_full_period": true,
      "limit": 250,
      "cursor": null
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "target_period_days": 30,
      "observed_period_days": 30,
      "is_full_period": true,
      "is_extrapolated": false,
      "extrapolation_factor": "1.000000",
      "window_start_time": "2025-11-20T12:34:56Z",
      "window_end_time": "2025-12-20T12:34:56Z",
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "current_reserves": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "volume_observed": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "volume_predicted": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_observed": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_predicted": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "roi_predicted": [
        "0.028800000000000000",
        "0.000000000000000000"
      ],
      "_tracing_id": "0411c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0303c0ffee000000000000000000000000000000000000000000000000000001",
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  ],
  "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

  • Dataset ID: 0411 - Liquidity Pool Yields
  • Description: Rolling yield/ROI predictions per pool over fixed horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D), based on historical swap fees (blockdb_evm.b0303_liquidity_pools_swap_fees_v1) and current reserves (latest blockdb_evm.b0301_liquidity_pools_reserves_v1 snapshot).
  • CSV Sample: Download
  • JSON Sample: Download

​
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

​
exchange_ids
number[]
Filter pools by exchange IDs. See the DigitalExchange enumeration for supported values.
​
pool_uids
string[]
Filter by BlockDB pool identifiers (uid from /evm/entities/pools).
​
pool_addresses
string[]
Filter by pool contract addresses (hex string, 20 bytes, no 0x prefix).
​
pool_ids
string[]
Filter by protocol-specific pool identifiers (e.g., Uniswap V4 pool_id).
​
pool_type_ids
number[]
Filter by AMM archetype. See the PoolType enumeration for supported values.

​
Horizon & Token Filters

​
target_period_days
number
Target horizon in days. Allowed values: 1, 3, 7, 14, 30, 90, 365.
​
token_addresses
string[]
Restrict to pools that contain at least one of these tokens (hex string, 20 bytes, no 0x prefix).
​
require_full_period
boolean
default:"false"
If true, returns only rows where observed_period_days == target_period_days (no extrapolation).

​
Pagination Controls

​
limit
number
default:"250"
Recommended default 250; maximum 1000 to stay under ~10 MB responses.
​
cursor
string
Pagination cursor from a prior call.

​
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.request_window
object
Block/timestamp bounds derived from the request.
​
meta.filters
object
Filters echoed from the request (selectors, horizon filters, pagination state, etc.).

​
Data

​
data
object[]
Array of yield/ROI prediction records matching the request. Rows are keyed by (pool_uid, target_period_days, block_number, tx_index, log_index); there is no separate numeric id field.
​
data.pool_uid
string
BlockDB pool identifier (uid from /evm/entities/pools).
​
data.exchange_id
number
Exchange/DEX identifier.
​
data.type_id
number
Pool type identifier.
​
data.block_number
number
Block height of the as-of snapshot anchor.
​
data.block_time
string
UTC timestamp of the as-of snapshot anchor.
​
data.tx_index
number
Zero-based transaction index within the block.
​
data.log_index
number
Zero-based log index within the transaction.
​
data.target_period_days
number
Target horizon in days (1, 3, 7, 14, 30, 90, 365).
​
data.observed_period_days
number
Observed history actually used to produce the prediction.
​
data.is_full_period
boolean
true when observed_period_days == target_period_days.
​
data.is_extrapolated
boolean
true when the row is scaled from shorter history.
​
data.extrapolation_factor
string
Scaling factor applied when extrapolating. Returned as a string to preserve precision.
​
data.window_start_time
string
Start time of the observed window used for aggregation.
​
data.window_end_time
string
End time of the observed window used for aggregation.
​
data.tokens
string[]
Pool token addresses. All array-valued metrics are aligned to this order.
​
data.current_reserves
string[]
Current reserves per token (decimals-adjusted). Returned as strings to preserve precision.
​
data.volume_observed
string[]
Observed traded volume per token in the observed window.
​
data.volume_predicted
string[]
Predicted traded volume per token for the target horizon.
​
data.user_fees_observed
string[]
Observed user/LP fee amounts per token in the observed window.
​
data.user_fees_predicted
string[]
Predicted user/LP fee amounts per token for the target horizon.
​
data.roi_predicted
string[]
Predicted ROI fractions per token for the target horizon.
​
data._tracing_id
string
Row-level lineage hash (hex string, no 0x prefix).
​
data._parent_tracing_ids
string[]
Lineage references of immediate parents.
​
data._created_at
string
Record creation timestamp (ISO-8601).
​
data._updated_at
string
Last update timestamp (ISO-8601).

​
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/yields" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "target_period_days": 30,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "require_full_period": true,
  "limit": 250
}'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "filters": {
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "target_period_days": 30,
      "require_full_period": true,
      "limit": 250,
      "cursor": null
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "target_period_days": 30,
      "observed_period_days": 30,
      "is_full_period": true,
      "is_extrapolated": false,
      "extrapolation_factor": "1.000000",
      "window_start_time": "2025-11-20T12:34:56Z",
      "window_end_time": "2025-12-20T12:34:56Z",
      "tokens": [
        "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      ],
      "current_reserves": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "volume_observed": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "volume_predicted": [
        "12000.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_observed": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "user_fees_predicted": [
        "36.000000000000000000",
        "0.000000000000000000"
      ],
      "roi_predicted": [
        "0.028800000000000000",
        "0.000000000000000000"
      ],
      "_tracing_id": "0411c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0303c0ffee000000000000000000000000000000000000000000000000000001",
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  ],
  "cursor": null,
  "count": 1
}
Last modified on May 19, 2026