components:
  schemas:
    ActionDocument:
      additionalProperties: true
      type: object
    ActionReceiptBody:
      additionalProperties: false
      properties:
        Action:
          $ref: "#/components/schemas/ActionReceiptDocument"
      required:
        - Action
      type: object
    ActionReceiptDocument:
      additionalProperties: false
      properties:
        actions:
          items:
            $ref: "#/components/schemas/ActionDocument"
          type: array
        gas_price:
          type: string
        input_data_ids:
          items:
            type: string
          type: array
        is_promise_yield:
          type: boolean
        output_data_receivers:
          items:
            $ref: "#/components/schemas/OutputDataReceiverDocument"
          type: array
        signer_id:
          type: string
        signer_public_key:
          type: string
      required:
        - actions
        - gas_price
        - input_data_ids
        - is_promise_yield
        - output_data_receivers
        - signer_id
        - signer_public_key
      type: object
    BlockDocument:
      additionalProperties: false
      description: Full block document as served by neardata, including the block envelope and per-shard payloads.
      properties:
        block:
          $ref: "#/components/schemas/BlockEnvelope"
        shards:
          items:
            $ref: "#/components/schemas/ShardDocument"
          type: array
      required:
        - block
        - shards
      type: object
    BlockEnvelope:
      additionalProperties: false
      description: Block-level payload returned by neardata.
      properties:
        author:
          description: Block producer account ID.
          type: string
        chunks:
          items:
            $ref: "#/components/schemas/ChunkHeader"
          type: array
        header:
          $ref: "#/components/schemas/BlockHeader"
      required:
        - author
        - chunks
        - header
      type: object
    BlockErrorResponse:
      additionalProperties: false
      properties:
        error:
          type: string
        type:
          $ref: "#/components/schemas/BlockErrorType"
      required:
        - error
        - type
      type: object
    BlockErrorType:
      enum:
        - BLOCK_HEIGHT_TOO_HIGH
        - BLOCK_HEIGHT_TOO_LOW
        - BLOCK_DOES_NOT_EXIST
      type: string
    BlockHeader:
      additionalProperties: true
      description: Block header object as served by neardata.
      properties:
        chunks_included:
          format: uint64
          type: integer
        epoch_id:
          type: string
        gas_price:
          type: string
        hash:
          type: string
        height:
          format: uint64
          type: integer
        next_epoch_id:
          type: string
        prev_hash:
          type: string
        prev_height:
          format: uint64
          type: integer
        timestamp:
          type: integer
        timestamp_nanosec:
          type: string
        total_supply:
          type: string
      type: object
    ChunkDocument:
      additionalProperties: false
      description: Chunk payload returned by neardata for a single shard in a selected block.
      properties:
        author:
          description: Chunk producer account ID.
          type: string
        header:
          $ref: "#/components/schemas/ChunkHeader"
        receipts:
          items:
            $ref: "#/components/schemas/ReceiptDocument"
          type: array
        transactions:
          items:
            $ref: "#/components/schemas/ChunkTransactionWrapper"
          type: array
      required:
        - author
        - header
        - receipts
        - transactions
      type: object
    ChunkHeader:
      additionalProperties: true
      description: Chunk header object as served by neardata.
      properties:
        chunk_hash:
          type: string
        gas_limit:
          type: integer
        gas_used:
          type: integer
        height_created:
          format: uint64
          type: integer
        height_included:
          format: uint64
          type: integer
        outcome_root:
          type: string
        outgoing_receipts_root:
          type: string
        prev_block_hash:
          type: string
        shard_id:
          format: uint64
          type: integer
        tx_root:
          type: string
      type: object
    ChunkTransactionWrapper:
      additionalProperties: false
      description: Transaction entry returned inside a neardata chunk.
      properties:
        outcome:
          $ref: "#/components/schemas/ExecutionWithReceipt"
        transaction:
          $ref: "#/components/schemas/SignedTransactionDocument"
      required:
        - outcome
        - transaction
      type: object
    DataReceiptBody:
      additionalProperties: false
      properties:
        Data:
          $ref: "#/components/schemas/DataReceiptDocument"
      required:
        - Data
      type: object
    DataReceiptDocument:
      additionalProperties: false
      properties:
        data:
          type: string
        data_id:
          type: string
        is_promise_resume:
          type: boolean
      required:
        - data
        - data_id
        - is_promise_resume
      type: object
    ExecutionOutcomeDocument:
      additionalProperties: false
      properties:
        block_hash:
          type: string
        id:
          type: string
        outcome:
          $ref: "#/components/schemas/ExecutionOutcomeSummary"
        proof:
          items:
            $ref: "#/components/schemas/ExecutionProofItem"
          type: array
      required:
        - block_hash
        - id
        - outcome
        - proof
      type: object
    ExecutionOutcomeStatus:
      oneOf:
        - $ref: "#/components/schemas/ExecutionOutcomeStatusSuccessReceiptId"
        - $ref: "#/components/schemas/ExecutionOutcomeStatusSuccessValue"
        - $ref: "#/components/schemas/ExecutionOutcomeStatusFailure"
    ExecutionOutcomeStatusFailure:
      additionalProperties: false
      properties:
        Failure:
          additionalProperties: true
          type: object
      required:
        - Failure
      type: object
    ExecutionOutcomeStatusSuccessReceiptId:
      additionalProperties: false
      properties:
        SuccessReceiptId:
          type: string
      required:
        - SuccessReceiptId
      type: object
    ExecutionOutcomeStatusSuccessValue:
      additionalProperties: false
      properties:
        SuccessValue:
          type: string
      required:
        - SuccessValue
      type: object
    ExecutionOutcomeSummary:
      additionalProperties: false
      properties:
        executor_id:
          type: string
        gas_burnt:
          format: uint64
          type: integer
        logs:
          items:
            type: string
          type: array
        metadata:
          additionalProperties: true
          type: object
        receipt_ids:
          items:
            type: string
          type: array
        status:
          $ref: "#/components/schemas/ExecutionOutcomeStatus"
        tokens_burnt:
          type: string
      required:
        - executor_id
        - gas_burnt
        - logs
        - metadata
        - receipt_ids
        - status
        - tokens_burnt
      type: object
    ExecutionProofItem:
      additionalProperties: true
      type: object
    ExecutionWithReceipt:
      additionalProperties: false
      description: Execution result paired with an optional receipt object.
      properties:
        execution_outcome:
          $ref: "#/components/schemas/ExecutionOutcomeDocument"
        receipt:
          description: Receipt payload when neardata includes it for this entry.
          nullable: true
          oneOf:
            - $ref: "#/components/schemas/ReceiptDocument"
            - $ref: "#/components/schemas/OmittedReceiptDocument"
          type: object
        tx_hash:
          type: string
      required:
        - execution_outcome
        - receipt
      type: object
    HealthResponse:
      additionalProperties: false
      properties:
        status:
          type: string
      required:
        - status
      type: object
    OmittedReceiptDocument:
      additionalProperties: false
      type: object
    OutputDataReceiverDocument:
      additionalProperties: false
      properties:
        data_id:
          type: string
        receiver_id:
          type: string
      required:
        - data_id
        - receiver_id
      type: object
    ReceiptBody:
      oneOf:
        - $ref: "#/components/schemas/ActionReceiptBody"
        - $ref: "#/components/schemas/DataReceiptBody"
    ReceiptDocument:
      additionalProperties: false
      description: Receipt object as served by neardata inside a chunk payload.
      properties:
        predecessor_id:
          type: string
        priority:
          format: uint64
          type: integer
        receipt:
          $ref: "#/components/schemas/ReceiptBody"
        receipt_id:
          type: string
        receiver_id:
          type: string
      required:
        - predecessor_id
        - priority
        - receipt
        - receipt_id
        - receiver_id
      type: object
    ShardDocument:
      additionalProperties: false
      description: Per-shard payload returned by neardata for a block.
      properties:
        chunk:
          $ref: "#/components/schemas/ChunkDocument"
        receipt_execution_outcomes:
          items:
            $ref: "#/components/schemas/ExecutionWithReceipt"
          type: array
        shard_id:
          format: uint64
          type: integer
        state_changes:
          items:
            $ref: "#/components/schemas/StateChangeItem"
          type: array
      required:
        - chunk
        - receipt_execution_outcomes
        - shard_id
        - state_changes
      type: object
    SignedTransactionDocument:
      additionalProperties: false
      properties:
        actions:
          items:
            $ref: "#/components/schemas/ActionDocument"
          type: array
        hash:
          type: string
        nonce:
          format: uint64
          type: integer
        priority_fee:
          format: uint64
          type: integer
        public_key:
          type: string
        receiver_id:
          type: string
        signature:
          type: string
        signer_id:
          type: string
      required:
        - actions
        - hash
        - nonce
        - priority_fee
        - public_key
        - receiver_id
        - signature
        - signer_id
      type: object
    StateChangeCause:
      oneOf:
        - $ref: "#/components/schemas/StateChangeCauseTransactionProcessing"
        - $ref: "#/components/schemas/StateChangeCauseReceiptProcessing"
        - $ref: "#/components/schemas/StateChangeCauseActionReceiptGasReward"
    StateChangeCauseActionReceiptGasReward:
      additionalProperties: false
      properties:
        receipt_hash:
          type: string
        type:
          type: string
      required:
        - receipt_hash
        - type
      type: object
    StateChangeCauseReceiptProcessing:
      additionalProperties: false
      properties:
        receipt_hash:
          type: string
        type:
          type: string
      required:
        - receipt_hash
        - type
      type: object
    StateChangeCauseTransactionProcessing:
      additionalProperties: false
      properties:
        tx_hash:
          type: string
        type:
          type: string
      required:
        - tx_hash
        - type
      type: object
    StateChangeItem:
      additionalProperties: false
      description: State change entry returned by neardata for a shard.
      properties:
        cause:
          $ref: "#/components/schemas/StateChangeCause"
        change:
          $ref: "#/components/schemas/StateChangeValue"
        type:
          type: string
      required:
        - cause
        - change
        - type
      type: object
    StateChangeValue:
      oneOf:
        - $ref: "#/components/schemas/StateChangeValueAccountUpdate"
        - $ref: "#/components/schemas/StateChangeValueAccessKeyUpdate"
        - $ref: "#/components/schemas/StateChangeValueDataUpdate"
        - $ref: "#/components/schemas/StateChangeValueDataDeletion"
    StateChangeValueAccessKeyUpdate:
      additionalProperties: false
      properties:
        access_key:
          additionalProperties: true
          type: object
        account_id:
          type: string
        public_key:
          type: string
      required:
        - access_key
        - account_id
        - public_key
      type: object
    StateChangeValueAccountUpdate:
      additionalProperties: false
      properties:
        account_id:
          type: string
        amount:
          type: string
        code_hash:
          type: string
        locked:
          type: string
        storage_paid_at:
          format: uint64
          type: integer
        storage_usage:
          format: uint64
          type: integer
      required:
        - account_id
        - amount
        - code_hash
        - locked
        - storage_paid_at
        - storage_usage
      type: object
    StateChangeValueDataDeletion:
      additionalProperties: false
      properties:
        account_id:
          type: string
        key_base64:
          type: string
      required:
        - account_id
        - key_base64
      type: object
    StateChangeValueDataUpdate:
      additionalProperties: false
      properties:
        account_id:
          type: string
        key_base64:
          type: string
        value_base64:
          type: string
      required:
        - account_id
        - key_base64
        - value_base64
      type: object
info:
  description: Cached and archived NEAR block data with redirect helpers for first-block and latest-block workflows. Some block-family routes may redirect depending on archive or freshness topology.
  title: NEAR Data API
  version: 3.0.3
openapi: 3.0.3
paths:
  /health:
    get:
      description: "Ping the neardata service for liveness — returns `{status: ok}` when healthy, errors otherwise."
      operationId: get_health
      parameters:
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                status: ok
              schema:
                $ref: "#/components/schemas/HealthResponse"
          description: Health payload
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Get service health
      tags:
        - system
      x-fastnear-slug: health
      x-fastnear-title: NEAR Data API - Health
  /v0/block/{block_height}:
    get:
      description: Fetch a finalized block's full document at a chosen height — header plus every chunk and shard payload.
      operationId: get_block
      parameters:
        - description: NEAR block height to retrieve.
          example: "50000000"
          in: path
          name: block_height
          required: true
          schema:
            type: string
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockDocument"
                nullable: true
          description: Requested document, or `null` when the selected slice is absent
        "302":
          description: Redirect to a canonical archive or finalized block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "404":
          content:
            application/json:
              example:
                error: The block does not exist in this archive range
                type: BLOCK_DOES_NOT_EXIST
              schema:
                $ref: "#/components/schemas/BlockErrorResponse"
          description: Structured block-height error
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Fetch a finalized block by height
      tags:
        - blocks
      x-fastnear-slug: block
      x-fastnear-title: NEAR Data API - Block
  /v0/block/{block_height}/chunk/{shard_id}:
    get:
      description: Fetch one chunk — a single shard's transactions and incoming receipts — at a chosen block height.
      operationId: get_chunk
      parameters:
        - description: NEAR block height to retrieve.
          example: "50000000"
          in: path
          name: block_height
          required: true
          schema:
            type: string
        - description: Shard ID whose chunk should be returned.
          example: "0"
          in: path
          name: shard_id
          required: true
          schema:
            type: string
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChunkDocument"
                nullable: true
          description: Requested document, or `null` when the selected slice is absent
        "302":
          description: Redirect to a canonical archive or finalized block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "404":
          content:
            application/json:
              example:
                error: The block does not exist in this archive range
                type: BLOCK_DOES_NOT_EXIST
              schema:
                $ref: "#/components/schemas/BlockErrorResponse"
          description: Structured block-height error
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Fetch one chunk from a finalized block
      tags:
        - blocks
      x-fastnear-slug: block_chunk
      x-fastnear-title: NEAR Data API - Block Chunk
  /v0/block/{block_height}/headers:
    get:
      description: Fetch only a finalized block's header and chunk summaries — no per-shard payload.
      operationId: get_block_headers
      parameters:
        - description: NEAR block height to retrieve.
          example: "50000000"
          in: path
          name: block_height
          required: true
          schema:
            type: string
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockEnvelope"
                nullable: true
          description: Requested document, or `null` when the selected slice is absent
        "302":
          description: Redirect to a canonical archive or finalized block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "404":
          content:
            application/json:
              example:
                error: The block does not exist in this archive range
                type: BLOCK_DOES_NOT_EXIST
              schema:
                $ref: "#/components/schemas/BlockErrorResponse"
          description: Structured block-height error
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Fetch the block-level object for a finalized block
      tags:
        - blocks
      x-fastnear-slug: block_headers
      x-fastnear-title: NEAR Data API - Block Headers
  /v0/block/{block_height}/shard/{shard_id}:
    get:
      description: Fetch one shard's full payload at a chosen block — chunk plus state changes and produced receipts.
      operationId: get_shard
      parameters:
        - description: NEAR block height to retrieve.
          example: "50000000"
          in: path
          name: block_height
          required: true
          schema:
            type: string
        - description: Shard ID to return.
          example: "0"
          in: path
          name: shard_id
          required: true
          schema:
            type: string
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShardDocument"
                nullable: true
          description: Requested document, or `null` when the selected slice is absent
        "302":
          description: Redirect to a canonical archive or finalized block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "404":
          content:
            application/json:
              example:
                error: The block does not exist in this archive range
                type: BLOCK_DOES_NOT_EXIST
              schema:
                $ref: "#/components/schemas/BlockErrorResponse"
          description: Structured block-height error
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Fetch one shard from a finalized block
      tags:
        - blocks
      x-fastnear-slug: block_shard
      x-fastnear-title: NEAR Data API - Block Shard
  /v0/block_opt/{block_height}:
    get:
      description: Fetch an optimistic (not-yet-final) block at a chosen height — may redirect once the optimistic window has finalized.
      operationId: get_block_optimistic
      parameters:
        - description: NEAR block height to retrieve.
          example: "50000000"
          in: path
          name: block_height
          required: true
          schema:
            type: string
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockDocument"
                nullable: true
          description: Requested document, or `null` when the selected slice is absent
        "302":
          description: Redirect to a canonical archive or finalized block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "404":
          content:
            application/json:
              example:
                error: The block does not exist in this archive range
                type: BLOCK_DOES_NOT_EXIST
              schema:
                $ref: "#/components/schemas/BlockErrorResponse"
          description: Structured block-height error
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Fetch an optimistic block by height
      tags:
        - blocks
      x-fastnear-slug: block_optimistic
      x-fastnear-title: NEAR Data API - Optimistic Block
  /v0/first_block:
    get:
      description: Redirect to the chain's first post-genesis block — a starting cursor for indexers backfilling from the beginning.
      operationId: get_first_block
      parameters:
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockDocument"
                nullable: true
          description: Full block document returned after automatic redirect following
        "302":
          description: Redirect to the canonical first block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
      summary: Redirect to the first block after genesis
      tags:
        - blocks
      x-fastnear-slug: first_block
      x-fastnear-title: NEAR Data API - First Block
  /v0/last_block/final:
    get:
      description: Redirect to the most recent finalized block — the chain-tip cursor once consensus has settled.
      operationId: get_last_block_final
      parameters:
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockDocument"
                nullable: true
          description: Full block document returned after automatic redirect following
        "302":
          description: Redirect to the latest block block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Redirect to the latest finalized block
      tags:
        - blocks
      x-fastnear-slug: last_block_final
      x-fastnear-title: NEAR Data API - Last Final Block
  /v0/last_block/optimistic:
    get:
      description: Redirect to the most recent optimistic block — the freshest-possible tip, ahead of final settlement.
      operationId: get_last_block_optimistic
      parameters:
        - description: Optional FastNEAR subscription API key. Invalid values may return `401` before redirect handling.
          in: query
          name: apiKey
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockDocument"
                nullable: true
          description: Full block document returned after automatic redirect following
        "302":
          description: Redirect to the latest block block URL
          headers:
            Location:
              schema:
                type: string
        "401":
          content:
            text/plain:
              example: Unauthorized
              schema:
                type: string
          description: Invalid or unauthorized API key
        "500":
          content:
            application/json:
              schema:
                type: string
          description: Cache or internal data error
      summary: Redirect to the latest optimistic block
      tags:
        - blocks
      x-fastnear-slug: last_block_optimistic
      x-fastnear-title: NEAR Data API - Last Optimistic Block
servers:
  - description: Mainnet
    url: https://mainnet.neardata.xyz
  - description: Testnet
    url: https://testnet.neardata.xyz