TransactionListEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blockvectra/json-schema/blockvectra-transaction-list-envelope-schema.json",
  "title": "TransactionListEnvelope",
  "description": "`next_cursor` is present only when there is another page.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/data.yaml#/components/schemas/TransactionListEnvelope",
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Transaction"
      }
    },
    "next_cursor": {
      "type": "string",
      "description": "Opaque pagination token from the previous response's `next_cursor`; pass it back unchanged."
    },
    "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}$"
    },
    "ExtraJson": {
      "type": "object",
      "description": "Additional chain-specific fields as a JSON object; `{}` when there are none. Shape varies by chain.",
      "additionalProperties": true
    },
    "Hash32": {
      "type": "string",
      "description": "32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.",
      "pattern": "^0x[0-9a-f]{64}$"
    },
    "HexBytes": {
      "type": "string",
      "description": "Raw bytes of any length, `0x` + an even number of lowercase hex digits (`\"0x\"` alone for zero bytes).",
      "pattern": "^0x([0-9a-f]{2})*$"
    },
    "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."
    },
    "Transaction": {
      "type": "object",
      "required": [
        "block_number",
        "tx_index",
        "hash",
        "block_timestamp",
        "type",
        "from",
        "to",
        "value",
        "nonce",
        "gas",
        "gas_price",
        "max_fee_per_gas",
        "max_priority_fee_per_gas",
        "input",
        "status",
        "gas_used",
        "cumulative_gas_used",
        "effective_gas_price",
        "contract_address",
        "log_count",
        "gas_used_for_l1",
        "l1_block_number",
        "extra"
      ],
      "properties": {
        "block_number": {
          "type": "integer",
          "format": "int64"
        },
        "tx_index": {
          "type": "integer"
        },
        "hash": {
          "$ref": "#/$defs/Hash32"
        },
        "block_timestamp": {
          "$ref": "#/$defs/Timestamp"
        },
        "type": {
          "type": "integer",
          "minimum": 0,
          "maximum": 255,
          "description": "EIP-2718 transaction type byte."
        },
        "from": {
          "$ref": "#/$defs/Address"
        },
        "to": {
          "oneOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "type": "null"
            }
          ],
          "description": "`null` for a contract-creation transaction."
        },
        "value": {
          "$ref": "#/$defs/UInt256String"
        },
        "nonce": {
          "type": "integer",
          "format": "int64"
        },
        "gas": {
          "type": "integer",
          "format": "int64"
        },
        "gas_price": {
          "oneOf": [
            {
              "$ref": "#/$defs/UInt256String"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_fee_per_gas": {
          "oneOf": [
            {
              "$ref": "#/$defs/UInt256String"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_priority_fee_per_gas": {
          "oneOf": [
            {
              "$ref": "#/$defs/UInt256String"
            },
            {
              "type": "null"
            }
          ]
        },
        "input": {
          "$ref": "#/$defs/HexBytes"
        },
        "status": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 255,
          "description": "1 = success, 0 = reverted (EIP-658 receipt status byte), null when receipt_root is nonzero (before Byzantium); stored status is then a placeholder."
        },
        "gas_used": {
          "type": "integer",
          "format": "int64"
        },
        "cumulative_gas_used": {
          "type": "integer",
          "format": "int64"
        },
        "effective_gas_price": {
          "oneOf": [
            {
              "$ref": "#/$defs/UInt256String"
            },
            {
              "type": "null"
            }
          ]
        },
        "contract_address": {
          "oneOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "type": "null"
            }
          ],
          "description": "Set only for a contract-creation transaction."
        },
        "log_count": {
          "type": "integer"
        },
        "gas_used_for_l1": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ],
          "description": "L2-specific; `null` on chains with no L1 data-fee accounting."
        },
        "l1_block_number": {
          "oneOf": [
            {
              "type": "integer",
              "format": "int64"
            },
            {
              "type": "null"
            }
          ]
        },
        "extra": {
          "$ref": "#/$defs/ExtraJson"
        }
      }
    },
    "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]+$"
    }
  }
}