TokensBatchEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blockvectra/json-schema/blockvectra-tokens-batch-envelope-schema.json",
  "title": "TokensBatchEnvelope",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/data.yaml#/components/schemas/TokensBatchEnvelope",
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "object",
      "required": [
        "tokens",
        "missing"
      ],
      "properties": {
        "tokens": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Token"
          }
        },
        "missing": {
          "type": "array",
          "description": "Canonical (`0x`-lowercase) addresses from the request with no matching metadata, first-occurrence request order, deduplicated.",
          "items": {
            "$ref": "#/$defs/Address"
          }
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    }
  },
  "$defs": {
    "Address": {
      "type": "string",
      "description": "20-byte address, canonical form always `0x` + 40 lowercase hex digits.",
      "pattern": "^0x[0-9a-f]{40}$"
    },
    "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."
    },
    "Token": {
      "type": "object",
      "required": [
        "address",
        "standard",
        "name",
        "symbol",
        "decimals",
        "total_supply",
        "first_seen_block",
        "metadata_updated_at",
        "metadata_block",
        "metadata_status",
        "metadata_issues"
      ],
      "properties": {
        "address": {
          "$ref": "#/$defs/Address"
        },
        "standard": {
          "type": "string",
          "enum": [
            "erc20",
            "erc721",
            "unknown"
          ]
        },
        "name": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "symbol": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "decimals": {
          "oneOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 255
            },
            {
              "type": "null"
            }
          ]
        },
        "total_supply": {
          "oneOf": [
            {
              "$ref": "#/$defs/UInt256String"
            },
            {
              "type": "null"
            }
          ],
          "description": "Raw on-chain integer, no `decimals` scaling applied server-side."
        },
        "first_seen_block": {
          "type": "integer",
          "format": "int64"
        },
        "metadata_updated_at": {
          "$ref": "#/$defs/Timestamp",
          "description": "When this token's metadata was last updated (UTC)."
        },
        "metadata_block": {
          "type": "integer",
          "format": "int64",
          "description": "Block height at which this token's metadata was read."
        },
        "metadata_status": {
          "type": "string",
          "enum": [
            "ok",
            "partial",
            "unavailable"
          ],
          "description": "Overall status of the token metadata."
        },
        "metadata_issues": {
          "type": "object",
          "description": "Issues encountered while fetching individual metadata fields. Key is the field name; value is the issue category.",
          "properties": {
            "name": {
              "type": "string",
              "enum": [
                "reverted",
                "no_data",
                "invalid_encoding",
                "temporarily_unavailable"
              ]
            },
            "symbol": {
              "type": "string",
              "enum": [
                "reverted",
                "no_data",
                "invalid_encoding",
                "temporarily_unavailable"
              ]
            },
            "decimals": {
              "type": "string",
              "enum": [
                "reverted",
                "no_data",
                "invalid_encoding",
                "temporarily_unavailable"
              ]
            },
            "total_supply": {
              "type": "string",
              "enum": [
                "reverted",
                "no_data",
                "invalid_encoding",
                "temporarily_unavailable"
              ]
            }
          },
          "additionalProperties": false
        }
      }
    },
    "UInt256String": {
      "type": "string",
      "description": "Non-negative integer that may exceed 2^53, rendered as a plain decimal string — never a JSON number, never scientific or hex notation.",
      "pattern": "^[0-9]+$"
    }
  }
}