FreshnessEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blockvectra/json-schema/blockvectra-freshness-envelope-schema.json",
  "title": "FreshnessEnvelope",
  "description": "`next_cursor` is never present (this endpoint has no pagination).",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/data.yaml#/components/schemas/FreshnessEnvelope",
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FreshnessRow"
      }
    },
    "meta": {
      "allOf": [
        {
          "$ref": "#/$defs/Meta"
        },
        {
          "type": "object",
          "properties": {
            "stale": {
              "type": "boolean",
              "const": true,
              "description": "Present (always `true`) only when this is the previous successful answer served because the refresh failed; absent on a freshly queried answer."
            },
            "stale_age_seconds": {
              "type": "integer",
              "minimum": 0,
              "description": "Present with `stale`; seconds since this answer was queried (at most 60)."
            }
          }
        }
      ]
    }
  },
  "$defs": {
    "DateOnly": {
      "type": "string",
      "format": "date",
      "description": "`YYYY-MM-DD`, UTC calendar day."
    },
    "FreshnessRow": {
      "type": "object",
      "required": [
        "dataset",
        "category",
        "max_block_number",
        "max_day",
        "max_time",
        "seconds_behind",
        "blocks_behind",
        "days_behind",
        "checked_at"
      ],
      "properties": {
        "dataset": {
          "type": "string",
          "description": "Public dataset identifier.",
          "enum": [
            "blocks",
            "transactions",
            "logs",
            "traces",
            "erc20_transfers",
            "erc721_transfers",
            "erc1155_transfers",
            "token_balances",
            "erc1155_balances",
            "tokens",
            "nft_owners",
            "dex_swaps",
            "dex_prices",
            "stocks",
            "stock_daily"
          ]
        },
        "category": {
          "type": "string",
          "enum": [
            "raw",
            "derived"
          ],
          "description": "Dataset category classification (`raw` for core chain data, `derived` for computed datasets)."
        },
        "max_block_number": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_day": {
          "oneOf": [
            {
              "$ref": "#/$defs/DateOnly"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_time": {
          "oneOf": [
            {
              "$ref": "#/$defs/Timestamp"
            },
            {
              "type": "null"
            }
          ]
        },
        "seconds_behind": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ]
        },
        "blocks_behind": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ],
          "description": "Head of `blocks` minus `max_block_number`. Always `null` for `dataset = \"blocks\"` (it is the head itself; this is not the node lag)."
        },
        "days_behind": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ]
        },
        "coverage_from_block": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ],
          "description": "Lowest block number indexed with traces. Present only when `dataset = \"traces\"`."
        },
        "coverage_to_block": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ],
          "description": "Highest block number indexed with traces. Present only when `dataset = \"traces\"`."
        },
        "coverage_complete": {
          "type": "boolean",
          "description": "Whether trace coverage between `coverage_from_block` and `coverage_to_block` is complete. Present only when `dataset = \"traces\"`."
        },
        "checked_at": {
          "$ref": "#/$defs/Timestamp"
        }
      }
    },
    "Meta": {
      "type": "object",
      "description": "Metadata present on every success response.",
      "required": [
        "chain",
        "chain_slug",
        "chain_external_id",
        "as_of_block",
        "safe_block",
        "finalized_block",
        "coverage",
        "refreshed_at"
      ],
      "properties": {
        "chain": {
          "type": "string",
          "description": "Chain identifier; the value of the `{chain}` path parameter."
        },
        "chain_slug": {
          "type": "string",
          "description": "Canonical uppercase chain slug; `chain` is always its lowercase form."
        },
        "chain_external_id": {
          "type": "string",
          "description": "CAIP-2 formatted external chain identifier (`eip155:{chain_id}`)."
        },
        "as_of_block": {
          "type": "integer",
          "format": "int64",
          "description": "The newest fully written block (the `blocks` table's maximum height); the only serving bound for block-scoped endpoints. For snapshot endpoints (balances, holders, nfts, dex prices, stocks) it is the service's current indexed head, not the block height of the snapshot: read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`."
        },
        "safe_block": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "A marker only: the node's consensus `safe` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, never below `finalized_block`, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description."
        },
        "finalized_block": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "A marker only: the node's consensus `finalized` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description."
        },
        "coverage": {
          "type": "string",
          "enum": [
            "full",
            "partial"
          ],
          "description": "`\"partial\"` appears only from `GET /{chain}/addresses/{address}/transactions` and `GET /{chain}/addresses/{address}/transfers`, when `clamp=true` narrowed the served window, and from those two, `GET /{chain}/tokens/{token}/transfers` and `GET /{chain}/dex/swaps` when the block window starts before the lower bound of the dataset the endpoint reads -- the chain's first indexed block, or higher while that dataset is still being backfilled (see Coverage in the API description and each endpoint's window description). Every other endpoint reports `\"full\"`."
        },
        "refreshed_at": {
          "description": "When the data behind this response was last updated (UTC): the timestamp of `as_of_block` for block-based endpoints, the latest snapshot time for snapshot endpoints, and the last update time for token metadata and status. `null` means the snapshot's update time is currently unknown: treat the data as stale; it never means \"just refreshed\".",
          "oneOf": [
            {
              "$ref": "#/$defs/Timestamp"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "Timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision."
    }
  }
}