openapi: 3.0.3
info:
  title: Transactions API - Block Lookup
  version: 3.0.3
  description: Fetch a block row by height or hash and optionally expand its transactions and receipts.
paths:
  /v0/block:
    post:
      description: Fetch a block row by height or hash and optionally expand its transactions and receipts.
      operationId: get_block
      requestBody:
        content:
          application/json:
            example:
              block_id: 130000000
              with_receipts: true
              with_transactions: true
            schema:
              $ref: "#/components/schemas/BlockInput"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockResponse"
          description: Block lookup result
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
          description: Bad request
        "500":
          content:
            application/json:
              schema:
                type: string
          description: ClickHouse query failure
      summary: Fetch a block by height or hash
      tags:
        - blocks
servers:
  - description: Mainnet
    url: https://tx.main.fastnear.com
  - description: Testnet
    url: https://tx.test.fastnear.com
components:
  schemas:
    ApiError:
      additionalProperties: false
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
      type: object
    BlockInput:
      additionalProperties: false
      properties:
        block_id:
          description: Block height (integer) or base58-encoded block hash (string) to fetch.
          oneOf:
            - minimum: 0
              type: integer
            - type: string
        with_receipts:
          description: Include the block's receipts in the response when true.
          nullable: true
          type: boolean
        with_transactions:
          description: Include the block's transactions in the response when true.
          nullable: true
          type: boolean
      required:
        - block_id
      type: object
    BlockResponse:
      additionalProperties: false
      properties:
        block:
          additionalProperties: false
          nullable: true
          properties:
            author_id:
              type: string
            block_hash:
              type: string
            block_height:
              format: uint64
              minimum: 0
              type: integer
            block_ordinal:
              format: uint64
              minimum: 0
              nullable: true
              type: integer
            block_timestamp:
              type: string
            chunks_included:
              format: uint64
              minimum: 0
              type: integer
            epoch_id:
              type: string
            gas_burnt:
              type: string
            gas_price:
              type: string
            next_epoch_id:
              type: string
            num_receipts:
              format: uint32
              minimum: 0
              type: integer
            num_transactions:
              format: uint32
              minimum: 0
              type: integer
            prev_block_hash:
              type: string
            prev_block_height:
              format: uint64
              minimum: 0
              nullable: true
              type: integer
            protocol_version:
              format: uint32
              minimum: 0
              type: integer
            tokens_burnt:
              type: string
            total_supply:
              type: string
          required:
            - block_height
            - block_hash
            - prev_block_hash
            - block_timestamp
            - epoch_id
            - next_epoch_id
            - chunks_included
            - author_id
            - protocol_version
            - gas_price
            - total_supply
            - num_transactions
            - num_receipts
            - gas_burnt
            - tokens_burnt
          type: object
        block_receipts:
          items:
            $ref: "#/components/schemas/ReceiptTxRow"
          type: array
        block_txs:
          items:
            $ref: "#/components/schemas/BlockTxRow"
          type: array
      required:
        - block
        - block_txs
        - block_receipts
      type: object
    BlockTxRow:
      additionalProperties: false
      properties:
        gas_burnt:
          format: uint64
          minimum: 0
          type: integer
        is_completed:
          type: boolean
        is_relayed:
          type: boolean
        is_success:
          type: boolean
        last_block_height:
          format: uint64
          minimum: 0
          type: integer
        nonce:
          format: uint64
          minimum: 0
          type: integer
        priority_fee:
          format: uint64
          minimum: 0
          type: integer
        real_receiver_id:
          type: string
        real_signer_id:
          type: string
        receiver_id:
          type: string
        shard_id:
          format: uint64
          minimum: 0
          type: integer
        signer_id:
          type: string
        signer_public_key:
          type: string
        tokens_burnt:
          type: string
        transaction_hash:
          type: string
        tx_block_hash:
          type: string
        tx_block_height:
          format: uint64
          minimum: 0
          type: integer
        tx_block_timestamp:
          type: string
        tx_index:
          format: uint32
          minimum: 0
          type: integer
      required:
        - transaction_hash
        - signer_id
        - tx_block_height
        - tx_index
        - tx_block_hash
        - tx_block_timestamp
        - last_block_height
        - is_completed
        - shard_id
        - receiver_id
        - signer_public_key
        - priority_fee
        - nonce
        - is_relayed
        - real_signer_id
        - real_receiver_id
        - is_success
        - gas_burnt
        - tokens_burnt
      type: object
    ReceiptTxRow:
      additionalProperties: false
      properties:
        appear_block_height:
          format: uint64
          minimum: 0
          type: integer
        appear_receipt_index:
          format: uint32
          minimum: 0
          type: integer
        block_height:
          format: uint64
          minimum: 0
          type: integer
        block_timestamp:
          type: string
        is_success:
          type: boolean
        predecessor_id:
          type: string
        priority:
          format: uint64
          minimum: 0
          type: integer
        receipt_id:
          type: string
        receipt_index:
          format: uint32
          minimum: 0
          type: integer
        receipt_type:
          type: string
        receiver_id:
          type: string
        shard_id:
          format: uint64
          minimum: 0
          type: integer
        transaction_hash:
          type: string
        tx_block_height:
          format: uint64
          minimum: 0
          type: integer
        tx_block_timestamp:
          type: string
        tx_index:
          format: uint32
          minimum: 0
          type: integer
      required:
        - receipt_id
        - block_height
        - block_timestamp
        - receipt_index
        - appear_block_height
        - appear_receipt_index
        - transaction_hash
        - tx_block_height
        - tx_block_timestamp
        - tx_index
        - predecessor_id
        - receiver_id
        - receipt_type
        - priority
        - shard_id
        - is_success
      type: object