BlockVectra NFTs API

openapi: 3.2.0
info:
  title: BlockVectra Data NFTs 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: NFTs
  description: ERC-721/ERC-1155 ownership.
paths:
  /{chain}/nfts/{contract}/{token_id}:
    get:
      tags:
      - NFTs
      summary: Get one NFT's owner/holders
      description: 'Get ownership for a specific NFT token ID by contract address. Returns the ERC-721 owner or the list of ERC-1155 token holders.

        **Snapshot freshness**: ownership comes from materialized snapshots that the data store refreshes every 5 minutes. The ERC-721 ownership snapshot only contains transfers older than head minus 256 blocks, so a newer ERC-721 transfer is not reflected yet; ERC-1155 balances are refreshed every 5 minutes without that cutoff. `as_of_block` here 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`.'
      operationId: getNftByContractAndTokenId
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - name: contract
        in: path
        required: true
        description: 20-byte contract address, `0x` optional, either case.
        schema:
          $ref: '#/components/schemas/AddressInput'
      - name: token_id
        in: path
        required: true
        description: Decimal (base-10) integer string, must fit in `UInt256`. Empty, non-decimal, or out-of-range values are `400`.
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: The ERC-721 owner or ERC-1155 holder list for this `(contract, token_id)`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftPointEnvelope'
        '400':
          description: '`error.code = "bad_request"`: invalid `{contract}`, or `{token_id}` is not a plain non-negative decimal integer (or does not fit in `UInt256`).'
          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 ownership record was found for this `(contract, token_id)`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          $ref: '#/components/responses/NotIndexedYetEmptyChain'
        '422':
          $ref: '#/components/responses/NoCoverage'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /{chain}/nfts:
    get:
      tags:
      - NFTs
      summary: List NFTs owned by an address
      description: 'Keyset-paginated list of NFTs owned by an address (ERC-721 holdings followed by ERC-1155 holdings), optionally filtered by contract address. Opaque pagination token from the previous response''s `next_cursor`; pass it back unchanged. A page may hold fewer than `limit` items, or none, while `next_cursor` is present; keep following `next_cursor` until it is absent.

        **Snapshot freshness**: holdings come from materialized snapshots that the data store refreshes every 5 minutes. The ERC-721 ownership snapshot only contains transfers older than head minus 256 blocks, so a newer ERC-721 transfer is not reflected yet; ERC-1155 balances are refreshed every 5 minutes without that cutoff. `as_of_block` here 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`.'
      operationId: getNftsByOwner
      parameters:
      - $ref: '#/components/parameters/ChainParam'
      - name: owner
        in: query
        required: true
        description: 20-byte owner/holder address, `0x` optional, either case.
        schema:
          $ref: '#/components/schemas/AddressInput'
      - name: contract
        in: query
        required: false
        description: Optional 20-byte contract address to restrict the list to a single collection.
        schema:
          $ref: '#/components/schemas/AddressInput'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: NFTs owned by `owner` (ERC-721 entries before ERC-1155 entries).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NftListEnvelope'
        '400':
          description: '`error.code = "bad_request"`: missing `owner`; invalid `owner`/`contract`; invalid `limit`; or an invalid `cursor`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          $ref: '#/components/responses/GatewayUnauthorized'
        '402':
          $ref: '#/components/responses/GatewayPaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/NotIndexedYetEmptyChain'
        '422':
          $ref: '#/components/responses/NoCoverage'
        '429':
          $ref: '#/components/responses/GatewayRateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    AddressInput:
      type: string
      description: 20-byte address. `0x`/`0X` prefix optional; either hex digit case is accepted.
      pattern: ^(0[xX])?[0-9a-fA-F]{40}$
      example: '0xAbCdEf0123456789aBcDeF0123456789aBCDEF01'
    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
    Erc721Nft:
      type: object
      required:
      - standard
      - contract
      - token
      - token_id
      - owner
      - block_number
      - log_index
      - block_timestamp
      - tx_hash
      properties:
        standard:
          type: string
          const: erc721
        contract:
          $ref: '#/components/schemas/Address'
        token:
          $ref: '#/components/schemas/Address'
          description: Always equal to `contract`.
        token_id:
          $ref: '#/components/schemas/UInt256String'
        owner:
          $ref: '#/components/schemas/Address'
        block_number:
          type: integer
          format: int64
          description: The block the current owner's transfer was logged in.
        log_index:
          type: integer
        block_timestamp:
          $ref: '#/components/schemas/Timestamp'
        tx_hash:
          $ref: '#/components/schemas/Hash32'
    Timestamp:
      type: string
      format: date-time
      description: '`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision.'
      example: 2026-09-26 05:41:07+00:00
    Erc721NftListItem:
      allOf:
      - $ref: '#/components/schemas/Erc721Nft'
      description: Same shape as the single ERC-721 object; `owner` always equals the request's `?owner=`.
    Address:
      type: string
      description: 20-byte address, canonical form always `0x` + 40 lowercase hex digits.
      pattern: ^0x[0-9a-f]{40}$
    NftListEnvelope:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Erc721NftListItem'
            - $ref: '#/components/schemas/Erc1155NftListItem'
        next_cursor:
          type: string
          description: Opaque pagination token from the previous response's `next_cursor`; pass it back unchanged.
        meta:
          $ref: '#/components/schemas/Meta'
    Erc1155NftHolders:
      type: object
      required:
      - standard
      - contract
      - token
      - token_id
      - holders
      properties:
        standard:
          type: string
          const: erc1155
        contract:
          $ref: '#/components/schemas/Address'
        token:
          $ref: '#/components/schemas/Address'
          description: Always equal to `contract`.
        token_id:
          $ref: '#/components/schemas/UInt256String'
        holders:
          type: array
          items:
            type: object
            required:
            - holder
            - balance
            properties:
              holder:
                $ref: '#/components/schemas/Address'
              balance:
                $ref: '#/components/schemas/Int256String'
    Erc1155NftListItem:
      type: object
      required:
      - standard
      - contract
      - token
      - token_id
      - owner
      - balance
      description: Flattened one row per `(token, id, holder)` — note this differs from the single ERC-1155 shape (`Erc1155NftHolders`), which nests a `holders` array instead of repeating `owner`/`balance` per row.
      properties:
        standard:
          type: string
          const: erc1155
        contract:
          $ref: '#/components/schemas/Address'
        token:
          $ref: '#/components/schemas/Address'
        token_id:
          $ref: '#/components/schemas/UInt256String'
        owner:
          $ref: '#/components/schemas/Address'
          description: Always equal to the request's `?owner=`.
        balance:
          $ref: '#/components/schemas/Int256String'
    NftPointEnvelope:
      type: object
      required:
      - data
      - meta
      description: '`next_cursor` is never present (no pagination for a single `(contract, token_id)`).'
      properties:
        data:
          oneOf:
          - $ref: '#/components/schemas/Erc721Nft'
          - $ref: '#/components/schemas/Erc1155NftHolders'
        meta:
          $ref: '#/components/schemas/Meta'
    Hash32:
      type: string
      description: 32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.
      pattern: ^0x[0-9a-f]{64}$
    Int256String:
      type: string
      description: Signed integer that may exceed +-2^53, rendered as a plain decimal string, optionally sign-prefixed.
      pattern: ^-?[0-9]+$
    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]+$
      example: '9007199254740993'
  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.'
    Unavailable:
      description: '`error.code = "unavailable"`: the service is temporarily unavailable, timed out, busy on this chain (no query slot freed up in time, see `limits.max_concurrent_queries` in `GET /chains`), or shutting down (see "Errors" above). Always carries an HTTP `Retry-After` header (seconds); wait at least that long before retrying.'
      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: service temporarily unavailable, please retry
    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.
    NotFound:
      description: '`error.code = "not_found"`: the target object was not found, or `{chain}` is not a registered or public chain (returns HTTP 404 with `error.code = "not_found"`, not billed).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            unknown_chain:
              summary: Unknown or not-public chain
              value:
                error:
                  code: not_found
                  message: unknown chain
            object_not_found:
              summary: Resource not found
              value:
                error:
                  code: not_found
                  message: block not found
          example:
            error:
              code: not_found
              message: unknown chain
    NoCoverage:
      description: '`error.code = "no_coverage"`: no data here, which is permanent except while a dataset is being backfilled (a windowed endpoint''s lower bound can move down as the backfill proceeds, so retry later). Either the chain does not have this endpoint''s capability, or the requested block (or whole block window) is before the chain''s first covered block (`coverage.from_block`) -- for the windowed endpoints, the lower bound of the dataset they read, which is that block or higher while the dataset is still being backfilled -- or the capability needs history from genesis (`balances`, `holders`, `nfts`) and `coverage.from_block` is not `0` yet or the indexed blocks have holes, or (traces) the block falls in a permanent trace coverage gap. A block window entirely before the lower bound is reported as this `422` even when its `to_block` is also above `as_of_block`. See Coverage in the API description (the history start in examples is a placeholder; read `GET /chains` `coverage.from_block` at runtime).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          examples:
            capability:
              value:
                error:
                  code: no_coverage
                  message: chain 'eth_mainnet' does not support balances
            before_history:
              summary: the start is live -- read `GET /chains` `coverage.from_block` at runtime
              value:
                error:
                  code: no_coverage
                  message: block 1 is before indexed history start <from_block> on chain 'eth_mainnet'
            history_not_at_genesis:
              summary: balances, holders and nfts need history from genesis
              value:
                error:
                  code: no_coverage
                  message: 'chain ''eth_mainnet'' does not serve balances yet: it needs history from genesis and indexed history starts at block <from_block>'
    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
    NotIndexedYetEmptyChain:
      description: 'After the operation passes its earlier routing, capability, parameter and permit checks and reaches the indexed-head check, `error.code = "not_indexed_yet"` without `indexed_through`: the chain has no indexed block at all yet (`GET /chains` `coverage.has_data = false`), so there is no head to answer against (see "Errors" above). Transient: retry later. A missing capability (including `traces`) is checked before the empty head and returns `422 no_coverage` instead.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            error:
              code: not_indexed_yet
              message: 'chain ''hyperevm_mainnet'' has no indexed data yet: no block has been indexed'
  parameters:
    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
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque pagination token from the previous response's `next_cursor`; pass it back unchanged.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Page size. Absent defaults to 50. `0` or a non-integer value is `400 bad_request`. A value above 500 is clamped to 500, not rejected.
      schema:
        type: integer
        minimum: 1
        default: 50
        maximum: 500
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your BlockVectra API key.