BlockVectra Traces API

openapi: 3.2.0
info:
  title: BlockVectra Data Traces API
  version: 0.1.3
  description: BlockVectra Data API — read-only REST endpoints over indexed data for each supported chain. The base URL is `https://api.blockvectra.com/v1/data`; supply your API key in the `x-api-key` header.
  contact:
    name: BlockVectra
servers:
- url: https://api.blockvectra.com/v1/data
  description: BlockVectra Data API
security:
- ApiKeyHeader: []
tags:
- name: Traces
  description: Historical callTracer call trees.
paths:
  /{chain}/blocks/{number}/traces:
    get:
      tags:
      - Traces
      summary: Historical callTracer trace tree for a whole block
      description: Reconstructed call tree per transaction in a block using `callTracer`, wrapped in the standard response envelope. **Returns the whole block, unpaginated** (`next_cursor` is never present). A permanent coverage gap returns `422`, never an empty array; a recent block with transactions but no trace data yet returns `503` instead -- once it is further behind the indexed head than the chain's trace window, it is `422` too (see "Errors" above).
      operationId: getBlockTraces
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - $ref: '#/components/parameters/BlockNumberPath'
      responses:
        '200':
          description: One call tree per transaction in the block, in `tx_index` order (`[]` for a real, finalized block that has zero transactions).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockTracesEnvelope'
        '400':
          description: '`error.code = "bad_request"`: `{number}` is not a valid non-negative integer.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          description: '`error.code = "not_found"`: either `{chain}` is unknown or not public, or block `{number}` does not exist (never indexed, or removed by a reorg).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          $ref: '#/components/responses/BlockAboveHead'
        '422':
          description: '`error.code = "no_coverage"`: the chain does not have the `traces` capability (checked first), or `{number}` falls in a permanent trace coverage gap -- the chain has no trace data at all yet (`coverage.traces_from_block` is `null`), `{number}` is before trace coverage started (below the chain''s `coverage.traces_from_block` in `GET /chains`), inside a recorded gap, or (distinct from the `503` case below) it has transactions but was never traced and is already too far behind the indexed head for that to still be a pending write. `message` names the chain and the reason.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              examples:
                capability:
                  value:
                    error:
                      code: no_coverage
                      message: chain 'eth_mainnet' does not support traces
                no_trace_data:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 12345 has no trace coverage on chain ''robinhood_mainnet'': no trace data available'
                before_coverage_start:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 12345 has no trace coverage on chain ''robinhood_mainnet'': coverage starts at block <traces_from_block>'
                coverage_gap:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 1500000 has no trace coverage on chain ''robinhood_mainnet'': trace data is not available for blocks 1499993-1500000'
                permanent_hole:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 1200000 has no trace coverage on chain ''robinhood_mainnet'': trace data is not available'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          description: '`error.code = "unavailable"`: the data store is unreachable or slow (including while the chain''s trace coverage start cannot be determined), or (see "Errors" above) `{number}` is a recent block with transactions but no trace data yet -- always with `Retry-After`.'
          headers:
            Retry-After:
              required: true
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                error:
                  code: unavailable
                  message: trace data for this block is not written yet; retry shortly
  /{chain}/transactions/{hash}/trace:
    get:
      tags:
      - Traces
      summary: Historical callTracer trace tree for one transaction
      description: Reconstructed `callTracer` call frame for a single transaction by its transaction hash. Unpaginated; `next_cursor` is never present. `data` is the call frame object directly.
      operationId: getTransactionTrace
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - $ref: '#/components/parameters/TxHashPath'
      responses:
        '200':
          description: This transaction's call tree.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TxTraceEnvelope'
        '400':
          description: '`error.code = "bad_request"`: `{hash}` does not parse as a 32-byte hash (`0x` optional, either case).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          description: '`error.code = "not_found"`: either `{chain}` is unknown or not public, or no transaction with this `{hash}` exists in the lookup table (a transaction submitted moments ago may take a few seconds to be indexed; `message` says so -- retry briefly before treating it as permanent), or it resolved to a block whose trace tree has no matching transaction. If the hash is found in the lookup table but resolves to a block above `as_of_block`, it returns `409 not_indexed_yet` instead.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              examples:
                not_found:
                  value:
                    error:
                      code: not_found
                      message: transaction 0x1234...abcd not found (a just-submitted transaction may take a few seconds to be indexed)
        '409':
          description: '`error.code = "not_indexed_yet"`: the resolved block is above `as_of_block`. On a chain with no indexed block at all it is the same code without `indexed_through` (see "Errors").'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: '`error.code = "no_coverage"`: the chain does not have the `traces` capability (checked first), or the resolved block falls in a permanent trace coverage gap -- the chain has no trace data at all yet (`coverage.traces_from_block` is `null`), the block is before trace coverage started (below the chain''s `coverage.traces_from_block` in `GET /chains`), inside a recorded gap, or (distinct from the `503` case below) it has transactions but was never traced and is already too far behind the indexed head for that to still be a pending write. `message` names the chain and the reason.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              examples:
                capability:
                  value:
                    error:
                      code: no_coverage
                      message: chain 'eth_mainnet' does not support traces
                no_trace_data:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 12345 has no trace coverage on chain ''robinhood_mainnet'': no trace data available'
                before_coverage_start:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 12345 has no trace coverage on chain ''robinhood_mainnet'': coverage starts at block <traces_from_block>'
                coverage_gap:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 1500000 has no trace coverage on chain ''robinhood_mainnet'': trace data is not available for blocks 1499993-1500000'
                permanent_hole:
                  value:
                    error:
                      code: no_coverage
                      message: 'block 1200000 has no trace coverage on chain ''robinhood_mainnet'': trace data is not available'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          description: '`error.code = "unavailable"`: the data store is unreachable or slow (including while the chain''s trace coverage start cannot be determined), or (see "Errors" above) the resolved block is a recent block with transactions but no trace data yet -- always with `Retry-After`.'
          headers:
            Retry-After:
              required: true
              schema:
                type: integer
                minimum: 1
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
              example:
                error:
                  code: unavailable
                  message: trace data for this block is not written yet; retry shortly
components:
  schemas:
    TxTraceEnvelope:
      type: object
      required:
      - data
      - meta
      description: Unpaginated; `next_cursor` is never present.
      properties:
        data:
          $ref: '#/components/schemas/CallFrame'
        meta:
          $ref: '#/components/schemas/Meta'
    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.
          example: robinhood_mainnet
        chain_slug:
          type: string
          description: Canonical uppercase chain slug; `chain` is always its lowercase form.
          example: ROBINHOOD_MAINNET
        chain_external_id:
          type: string
          description: CAIP-2 formatted external chain identifier (`eip155:{chain_id}`).
          example: eip155:4663
        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: '#/components/schemas/Timestamp'
          - type: 'null'
    ErrorBody:
      type: object
      description: The only shape any non-2xx response ever takes. `code` and `message` are always present; `indexed_through` is present only on `error.code = "not_indexed_yet"` on a chain with an indexed block, and absent (never `null`) otherwise. No other field is ever added.
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - code
          - message
          additionalProperties: false
          properties:
            code:
              type: string
              description: Stable machine-readable identifier; see each operation for the exact set of values it can return.
            message:
              type: string
              description: Free-form English text for logs/debugging. Do not pattern-match on it.
            indexed_through:
              type: integer
              format: int64
              description: 'Highest indexed block on this chain. Present only when `code = "not_indexed_yet"` and the chain has at least one indexed block; absent when it has none at all (an absent value is not `0`: block 0 indexed is `indexed_through: 0`).'
            data:
              type: object
              description: Optional structured error details.
              additionalProperties: true
    Timestamp:
      type: string
      format: date-time
      description: '`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision.'
      example: 2026-09-26 05:41:07+00:00
    Address:
      type: string
      description: 20-byte address, canonical form always `0x` + 40 lowercase hex digits.
      pattern: ^0x[0-9a-f]{40}$
    BlockTracesEnvelope:
      type: object
      required:
      - data
      - meta
      description: Unpaginated; `next_cursor` is never present.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlockTraceItem'
        meta:
          $ref: '#/components/schemas/Meta'
    HashInput:
      type: string
      description: 32-byte hash. `0x`/`0X` prefix optional; either hex digit case is accepted.
      pattern: ^(0[xX])?[0-9a-fA-F]{64}$
    CallFrame:
      type: object
      description: 'A single `callTracer` call frame in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities. Any additional fields in the call frame are preserved (`additionalProperties: true`).'
      required:
      - type
      - from
      - gas
      - gasUsed
      - input
      properties:
        type:
          type: string
          description: e.g. `CALL`, `DELEGATECALL`, `STATICCALL`, `CREATE`, `CREATE2`, `SELFDESTRUCT`.
        from:
          $ref: '#/components/schemas/Address'
        to:
          $ref: '#/components/schemas/Address'
          description: Absent for a `CREATE`/`CREATE2` frame's target (the address does not exist yet at call time in the node's own output).
        value:
          $ref: '#/components/schemas/HexQuantity'
          description: Absent for a `STATICCALL` frame (no value can move).
        gas:
          $ref: '#/components/schemas/HexQuantity'
        gasUsed:
          $ref: '#/components/schemas/HexQuantity'
        input:
          $ref: '#/components/schemas/HexBytes'
        output:
          $ref: '#/components/schemas/HexBytes'
          description: Absent when the call returned no data.
        error:
          type: string
          description: Absent on a successful call.
        revertReason:
          type: string
          description: Absent unless the call reverted with `Error(string)` data.
        calls:
          type: array
          description: Nested sub-calls, in call order. Absent for a leaf frame.
          items:
            $ref: '#/components/schemas/CallFrame'
      additionalProperties: true
    Hash32:
      type: string
      description: 32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.
      pattern: ^0x[0-9a-f]{64}$
    HexQuantity:
      type: string
      description: '`0x`-prefixed hexadecimal integer in standard Ethereum `callTracer` format; `value`/`gas`/`gasUsed` are `0x`-prefixed hex quantities.'
      pattern: ^0x[0-9a-f]+$
    BlockTraceItem:
      type: object
      required:
      - txHash
      - result
      properties:
        txHash:
          $ref: '#/components/schemas/Hash32'
        result:
          $ref: '#/components/schemas/CallFrame'
  responses:
    GatewayPaymentRequired:
      description: 'Payment required: the paid balance or the free grant is exhausted. The response body is `{"error":{"code":"insufficient_balance"}}`. Rejected requests are not billed.'
    GatewayRateLimited:
      description: Rate limited. `{"error":{"code":"rate_limited"}}` when the key CU rate limit is exceeded (the response includes `Retry-After`) or the account call rate limit is exceeded (no `Retry-After`). `{"error":{"code":"cost_exceeds_burst"}}` when a single request exceeds the key burst capacity; split the request, retrying as sent never succeeds. Rejected requests are not billed.
    GatewayUnauthorized:
      description: 'HTTP 401: a missing API key returns missing_api_key; an unknown, disabled, or revoked key returns the same invalid_api_key error envelope. error.code and error.data.reason contain the reason. Rejected requests are not billed.'
      content:
        application/json:
          examples:
            missing_api_key:
              value:
                error:
                  code: missing_api_key
                  message: 'missing API key: send it in the x-api-key header'
                  data:
                    reason: missing_api_key
                    docs_url: https://docs.blockvectra.com/en/errors/#missing_api_key
                    retryable: false
            invalid_api_key:
              value:
                error:
                  code: invalid_api_key
                  message: 'invalid API key: it is unknown, disabled or revoked; check the key in the console'
                  data:
                    reason: invalid_api_key
                    docs_url: https://docs.blockvectra.com/en/errors/#invalid_api_key
                    retryable: false
    BlockAboveHead:
      description: After the operation passes its earlier routing, capability, parameter and permit checks and reaches the indexed-head check, `error.code = "not_indexed_yet"` when the requested block (a `{number}` path parameter, or the block a hash resolved to) is above `as_of_block`, the newest fully written block (see "Errors" above). It carries `indexed_through`, the highest indexed block. `meta.finalized_block` is a marker only and never rejects an indexed block. On a chain with no indexed block at all it is also `not_indexed_yet` but `indexed_through` is **absent** (block 0 is not indexed either).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            not_indexed_yet:
              value:
                error:
                  code: not_indexed_yet
                  message: block 999999999 has not been indexed yet (indexed through 12345)
                  indexed_through: 12345
            chain_has_no_data:
              value:
                error:
                  code: not_indexed_yet
                  message: 'chain ''hyperevm_mainnet'' has no indexed data yet: no block has been indexed'
  parameters:
    TxHashPath:
      name: hash
      in: path
      required: true
      description: 32-byte transaction hash, `0x` prefix optional, either digit case.
      schema:
        $ref: '#/components/schemas/HashInput'
    ChainParam:
      name: chain
      in: path
      required: true
      description: 'Chain identifier: the `chain` value of an entry in `GET /chains` (for example `robinhood_mainnet`), which lists every value this API accepts, i.e. the exact lowercase form of that entry''s `chain_slug`. Matching is exact and case-sensitive; other spellings, aliases and numeric chain IDs are not accepted and return `404 not_found` (unknown or not-public chain). What the chain serves differs per chain: see that entry''s `features` and `coverage`.'
      schema:
        type: string
        pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)+$
      examples:
        robinhood_mainnet:
          value: robinhood_mainnet
        eth_mainnet:
          value: eth_mainnet
    BlockNumberPath:
      name: number
      in: path
      required: true
      description: Non-negative block height.
      schema:
        type: integer
        format: int64
        minimum: 0
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your BlockVectra API key.