openapi: 3.0.3
info:
  title: NEAR Data API - Block Chunk
  version: 3.0.3
  description: Fetch one chunk — a single shard's transactions and incoming receipts — at a chosen block height.
paths:
  /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
servers:
  - description: Mainnet
    url: https://mainnet.neardata.xyz
  - description: Testnet
    url: https://testnet.neardata.xyz
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
    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
    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
    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
    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