Supra Block API

openapi: 3.2.0
info:
  title: Supra RPC Node Block API
  description: '0.5.0

    tag:supra_rpc_v11.5.2

    commit_hash:5e9ea652

    build_time:2026-08-25 08:38:29 +00:00

    build_env:rustc 1.97.1 (8bab26f4f 2026-07-14),1.97.1-x86_64-unknown-linux-gnu'
  contact:
    name: Supra Labs
    url: https://supra.com
  version: 5e9ea652457cd48aba6b1505bdd59da27fec13f6
servers:
- url: /
tags:
- name: Block
  description: Block Api
paths:
  /rpc/v2/block:
    get:
      tags:
      - Block
      summary: Get the latest block (v2)
      description: Get the header of the most recently finalized block.
      operationId: latest_block_v2
      responses:
        '200':
          description: Returns the header of the most recently finalized block.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeaderInfo'
      deprecated: true
  /rpc/v2/block/height/{height}:
    get:
      tags:
      - Block
      summary: Get block by height (v2)
      description: Get information about the block that has been finalized at the given height.
      operationId: block_by_height_v2
      parameters:
      - name: height
        in: path
        description: Block height
        required: true
        schema:
          type: integer
          format: u-int64
          minimum: 0
      - name: with_finalized_transactions
        in: query
        description: 'If true, returns all transactions that were finalized by this block in the order that they

          were executed.'
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Information about the block that has been finalized at the given height.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '404':
          description: Requested data is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
        '410':
          description: Requested data has been pruned and is no longer available.
          headers:
            x-supra-oldest-block:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Height of the oldest available block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
      deprecated: true
  /rpc/v2/block/{block_hash}:
    get:
      tags:
      - Block
      summary: Get block by hash (v2)
      description: Get the header of the block with the given hash.
      operationId: block_header_info_v2
      parameters:
      - name: block_hash
        in: path
        description: Hex encoded block hash
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The header of the block with the given hash.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeaderInfo'
      deprecated: true
  /rpc/v3/block:
    get:
      tags:
      - Block
      summary: Get latest block (v3)
      description: Get the meta information of the most recently finalized and executed block.
      operationId: latest_block_v3
      responses:
        '200':
          description: Returns the header of the most recently finalized block.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutedBlockInfo'
  /rpc/v3/block/height/{height}:
    get:
      tags:
      - Block
      summary: Get block by height (v3)
      description: Get information about the block that has been finalized at the given height.
      operationId: block_by_height_v3
      parameters:
      - name: height
        in: path
        description: Block height
        required: true
        schema:
          type: integer
          format: u-int64
          minimum: 0
      - name: with_finalized_transactions
        in: query
        description: 'If true, returns all transactions that were finalized by this block in the order that they

          were executed.'
        required: false
        schema:
          type: boolean
      - name: type
        in: query
        description: Transaction type to query. If missing any/all type of transactions will be looked for.
        required: false
        schema:
          type: string
          description: Type of the transaction to be queried.
          enum:
          - auto
          - user
          - meta
          - record
      responses:
        '200':
          description: Information about the block that has been finalized at the given height.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockV3'
        '404':
          description: Requested data is not available.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
        '410':
          description: Requested data has been pruned and is no longer available.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
            x-supra-oldest-block:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Height of the oldest available block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
  /rpc/v3/block/{block_hash}:
    get:
      tags:
      - Block
      summary: Get block by hash (v3)
      description: Get the header and execution output statistics of the block with the given hash.
      operationId: block_info_by_hash_v3
      parameters:
      - name: block_hash
        in: path
        description: Hex encoded block hash
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The header of the block with the given hash.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutedBlockInfo'
  /rpc/v3/block/{block_hash}/transactions:
    get:
      tags:
      - Block
      summary: Get transactions by block hash (v3)
      description: 'Get a list containing the hashes of the transactions that were finalized in the block with

        the given hash in the order that they were executed.'
      operationId: txs_by_block_v3
      parameters:
      - name: type
        in: query
        description: Transaction type to query. If missing any/all type of transactions will be looked for.
        required: false
        schema:
          type: string
          description: Type of the transaction to be queried.
          enum:
          - auto
          - user
          - meta
          - record
      - name: block_hash
        in: path
        description: Hex encoded block hash
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of the hashes of the transactions contained in the block.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Hash'
  /rpc/v4/block/height/{height}:
    get:
      tags:
      - Block
      summary: Get block by height (v4)
      description: Get information about the block that has been finalized at the given height.
      operationId: block_by_height_v4
      parameters:
      - name: height
        in: path
        description: Block height
        required: true
        schema:
          type: integer
          format: u-int64
          minimum: 0
      - name: with_finalized_transactions
        in: query
        description: 'If set to `true`, includes all transactions that were finalized in this block,

          returned in the order in which they were executed.'
        required: false
        schema:
          type: boolean
      - name: include_proof
        in: query
        description: 'If set to `true`, includes the Merkle proof for the related transactions'' inclusion in the

          executed transaction log.'
        required: false
        schema:
          type: boolean
      - name: type
        in: query
        description: Transaction type to query. If missing any/all type of transactions will be looked for.
        required: false
        schema:
          type: string
          description: Type of the transaction to be queried.
          enum:
          - auto
          - user
          - meta
          - record
      responses:
        '200':
          description: Information about the block that has been finalized at the given height.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockV4'
        '404':
          description: Requested data is not available.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
        '410':
          description: Requested data has been pruned and is no longer available.
          headers:
            x-supra-chain-id:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Chain ID of the current chain.
            x-supra-oldest-block:
              schema:
                type: integer
                format: u-int8
                minimum: 0
              description: Height of the oldest available block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrResp'
components:
  schemas:
    EventV1:
      type: object
      description: On-chain event.
      required:
      - guid
      - sequence_number
      - type
      - data
      properties:
        guid:
          $ref: '#/components/schemas/Guid'
          description: The globally unique identifier of this event stream.
        sequence_number:
          type: string
        type:
          type: string
          description: The `MoveType` of the event
        data:
          description: The JSON representation of the event
    TxExecutionStatus:
      type: string
      enum:
      - Success
      - Fail
      - Invalid
      - PendingAfterExecution
      - Pending
    BlockMetadataInfoV4:
      type: object
      description: Details of block metadata transaction execution
      required:
      - hash
      - output
      - status
      properties:
        hash:
          $ref: '#/components/schemas/Hash'
        block_header:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BlockHeaderInfo'
            description: 'Metadata about the block containing the transaction, if any.

              This field will not be set for transactions that are returned as a part of a block.'
        output:
          $ref: '#/components/schemas/TransactionOutputV4'
        status:
          $ref: '#/components/schemas/TxExecutionStatus'
        inclusion_proof:
          $ref: '#/components/schemas/TransactionInclusionProof'
    EvmTransferKind:
      type: string
      enum:
      - call
      - create
      - create2
      - selfdestruct
    Hash:
      type: string
      description: Hex encoded hash
    Block:
      type: object
      description: The API representation of a Supra block.
      required:
      - header
      properties:
        header:
          $ref: '#/components/schemas/BlockHeaderInfo'
          description: Metadata about the block.
        transactions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TransactionInfoV2'
          description: 'The API representations of all transactions contained in the block, in the order that

            they were executed.'
    BlockMetadataInfoV3:
      type: object
      description: Details of block metadata transaction execution
      required:
      - hash
      - output
      - status
      properties:
        hash:
          $ref: '#/components/schemas/Hash'
        block_header:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BlockHeaderInfo'
            description: 'Metadata about the block containing the transaction, if any.

              This field will not be set for transactions that are returned as a part of a block.'
        output:
          $ref: '#/components/schemas/TransactionOutputV1'
        status:
          $ref: '#/components/schemas/TxExecutionStatus'
    TransactionOutputV1:
      oneOf:
      - type: object
        required:
        - Dkg
        properties:
          Dkg:
            $ref: '#/components/schemas/TxExecutionStatus'
      - type: string
        enum:
        - Empty
      - type: object
        required:
        - Move
        properties:
          Move:
            $ref: '#/components/schemas/MoveTransactionOutputV1'
      - type: object
        required:
        - Oracle
        properties:
          Oracle:
            $ref: '#/components/schemas/TxExecutionStatus'
      - type: object
        required:
        - Evm
        properties:
          Evm:
            $ref: '#/components/schemas/EvmTransactionOutput'
      description: '[crate::v1::TransactionOutputV1] with all fields in human-readable format.'
    EventV2:
      type: object
      description: On-chain event v2.
      required:
      - guid
      - sequence_number
      - type
      - data
      - hash
      properties:
        guid:
          $ref: '#/components/schemas/Guid'
          description: The globally unique identifier of this event stream.
        sequence_number:
          type: string
        type:
          type: string
          description: The `MoveType` of the event
        data:
          description: The JSON representation of the event
        hash:
          type: string
          description: The hash of the event, derived from `RLP(event)` + `keccak256`.
    BlockV4:
      type: object
      description: The API representation of a Supra block.
      required:
      - header
      properties:
        header:
          $ref: '#/components/schemas/BlockHeaderInfo'
          description: Metadata about the block.
        execution_statistics:
          oneOf:
          - type: object
            description: Executed block statistics collected based on execution results.
            properties:
              automated_txn_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the automated transactions executed/finalized in scope of the block.
                minimum: 0
              automated_txn_gas_unit_price:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Gas unit price defined by the chain for all automated transactions.
                minimum: 0
              block_gas_unit_price_min:
                type:
                - integer
                - 'null'
                description: Minimum gas unit price of the transactions included in the block.
                minimum: 0
              block_gas_unit_price_max:
                type:
                - integer
                - 'null'
                description: Maximum gas unit price of the transactions included in the block.
                minimum: 0
              block_total_user_gas_used:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Total used gas by user submitted transactions in the block.
                minimum: 0
              block_total_automated_gas_used:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Total used gas by automated transactions executed in scope of the block.
                minimum: 0
              user_txn_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the user submitted transactions executed/finalized in scope of the block.
                minimum: 0
              automation_record_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the automation registry records executed/finalized in scope of the block.
                minimum: 0
          - type: 'null'
        transactions:
          oneOf:
          - type: array
            items:
              oneOf:
              - allOf:
                - $ref: '#/components/schemas/TransactionInfoV4'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - user
              - allOf:
                - $ref: '#/components/schemas/TransactionInfoV4'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - automated
              - allOf:
                - $ref: '#/components/schemas/BlockMetadataInfoV4'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - block_metadata
              - allOf:
                - $ref: '#/components/schemas/AutomationRecordInfoV4'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - automation_record
          - type: 'null'
    BlockV3:
      type: object
      description: The API representation of a Supra block.
      required:
      - header
      properties:
        header:
          $ref: '#/components/schemas/BlockHeaderInfo'
          description: Metadata about the block.
        execution_statistics:
          oneOf:
          - type: object
            description: Executed block statistics collected based on execution results.
            properties:
              automated_txn_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the automated transactions executed/finalized in scope of the block.
                minimum: 0
              automated_txn_gas_unit_price:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Gas unit price defined by the chain for all automated transactions.
                minimum: 0
              block_gas_unit_price_min:
                type:
                - integer
                - 'null'
                description: Minimum gas unit price of the transactions included in the block.
                minimum: 0
              block_gas_unit_price_max:
                type:
                - integer
                - 'null'
                description: Maximum gas unit price of the transactions included in the block.
                minimum: 0
              block_total_user_gas_used:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Total used gas by user submitted transactions in the block.
                minimum: 0
              block_total_automated_gas_used:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Total used gas by automated transactions executed in scope of the block.
                minimum: 0
              user_txn_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the user submitted transactions executed/finalized in scope of the block.
                minimum: 0
              automation_record_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the automation registry records executed/finalized in scope of the block.
                minimum: 0
          - type: 'null'
        transactions:
          oneOf:
          - type: array
            items:
              oneOf:
              - allOf:
                - $ref: '#/components/schemas/TransactionInfoV2'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - user
              - allOf:
                - $ref: '#/components/schemas/TransactionInfoV2'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - automated
              - allOf:
                - $ref: '#/components/schemas/BlockMetadataInfoV3'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - block_metadata
              - allOf:
                - $ref: '#/components/schemas/AutomationRecordInfoV3'
                - type: object
                  required:
                  - txn_type
                  properties:
                    txn_type:
                      type: string
                      enum:
                      - automation_record
          - type: 'null'
    EvmTransferOperation:
      type: object
      description: This is a convenience structure wrapping [`TransferOperation`] to implement (de)serialization logic.
      required:
      - kind
      - from
      - to
      - value
      properties:
        kind:
          $ref: '#/components/schemas/EvmTransferKind'
          description: Source of the transfer call.
        from:
          type: string
          description: Sender of the transfer.
        to:
          type: string
          description: Receiver of the transfer.
        value:
          type: string
          description: Value of the transfer.
    TransactionOutputV4:
      oneOf:
      - type: object
        required:
        - Dkg
        properties:
          Dkg:
            $ref: '#/components/schemas/TxExecutionStatus'
      - type: string
        enum:
        - Empty
      - type: object
        required:
        - Move
        properties:
          Move:
            $ref: '#/components/schemas/MoveTransactionOutputV4'
      - type: object
        required:
        - Oracle
        properties:
          Oracle:
            $ref: '#/components/schemas/TxExecutionStatus'
      - type: object
        required:
        - Evm
        properties:
          Evm:
            $ref: '#/components/schemas/EvmTransactionOutput'
      description: '[crate::v4::TransactionOutputV4] with all fields in human-readable format.'
    AccumulatorProof:
      type: object
      description: 'A proof that can be used authenticate an element in an accumulator given trusted root hash. For

        example, both `TransactionInclusionProof` and `EventEmissionProof` can be constructed on top of

        this structure.'
      required:
      - siblings
      properties:
        siblings:
          type: array
          items:
            $ref: '#/components/schemas/Hash'
          description: 'All siblings in this proof, including the default ones. Siblings are ordered from the bottom

            level to the root level.'
    MoveTransactionOutputV1:
      type: object
      description: The execution output of a Move transaction.
      required:
      - gas_used
      - events
      - vm_status
      properties:
        gas_used:
          type: integer
          format: u-int64
          description: The gas used by the transaction.
          minimum: 0
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventV1'
        vm_status:
          type: string
          description: A message summarizing the execution result produced by the MoveVM.
    EpochId:
      type: object
      required:
      - chain_id
      - epoch
      properties:
        chain_id:
          oneOf:
          - type: integer
            format: u-int8
            minimum: 0
          description: Unique identifier for this instance of the SMR.
        epoch:
          oneOf:
          - type: integer
            format: u-int64
            minimum: 0
          description: Identifier of the epoch within the context of `chain_id`.
    Guid:
      type: object
      description: A globally unique identifier derived from the sender's address and a counter
      required:
      - creation_number
      - account_address
      properties:
        creation_number:
          type: string
          description: If creation_num is `i`, this is the `i+1`th GUID created by `addr`
        account_address:
          $ref: '#/components/schemas/AccountAddress'
          description: Address that created the GUID
    BlockHeaderInfo:
      type: object
      description: Metadata about a Supra block.
      required:
      - author
      - hash
      - height
      - parent
      - timestamp
      - view
      properties:
        author:
          $ref: '#/components/schemas/Identity'
        hash:
          $ref: '#/components/schemas/Hash'
        height:
          oneOf:
          - type: integer
            format: u-int64
            minimum: 0
          description: Number of blocks before this block in the chain (including the genesis block).
        parent:
          $ref: '#/components/schemas/Hash'
        timestamp:
          $ref: '#/components/schemas/SmrTimestamp'
        view:
          $ref: '#/components/schemas/View'
    MoveTransactionOutputV4:
      type: object
      description: The execution output of a Move transaction.
      required:
      - gas_used
      - events
      - vm_status
      properties:
        gas_used:
          type: integer
          format: u-int64
          description: The gas used by the transaction.
          minimum: 0
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventV2'
        vm_status:
          type: string
          description: A message summarizing the execution result produced by the MoveVM.
    u64:
      type: integer
      format: u-int64
      minimum: 0
    ErrResp:
      type: object
      required:
      - message
      properties:
        message:
          type: string
    SmrTimestamp:
      type: object
      required:
      - timestamp
      properties:
        timestamp:
          type: integer
          format: u-int64
          description: The timestamp as measured in the number of microseconds since the unix epoch.
          minimum: 0
    AccountAddress:
      type: string
      description: Hex encoded account address.
    TransactionInclusionProof:
      type: object
      description: Proof of a transaction's inclusion in the merkle accumulator tree.
      required:
      - proof
      - leaf_hash_value
      - merkle_root_hash_value
      - leaf_index
      - certified_at_height
      properties:
        proof:
          $ref: '#/components/schemas/AccumulatorProof'
          description: The accumulator proof for the transaction.
        leaf_hash_value:
          $ref: '#/components/schemas/Hash'
          description: Hex encoded hash value of the leaf node.
        merkle_root_hash_value:
          $ref: '#/components/schemas/Hash'
          description: Hex encoded merkle root hash value.
        leaf_index:
          type: integer
          format: u-int64
          description: The leaf index in the accumulator tree.
          minimum: 0
        events_tree_merkle_root_hash_value:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Hash'
            description: Hex encoded merkle root hash value of the events tree, if available.
        events_leaves_hash_values:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Hash'
          description: Hex encoded hash values of the events tree leaves, if available.
        certified_at_height:
          $ref: '#/components/schemas/u64'
          description: Block height at which the Merkle root was certified.
    ExecutedBlockInfo:
      type: object
      description: Block metadata and existing statistics collected on executed block output.
      required:
      - header
      properties:
        header:
          $ref: '#/components/schemas/BlockHeaderInfo'
          description: Metadata about the block.
        execution_statistics:
          oneOf:
          - type: object
            description: Executed block statistics collected based on execution results.
            properties:
              automated_txn_count:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Number of the automated transactions executed/finalized in scope of the block.
                minimum: 0
              automated_txn_gas_unit_price:
                type:
                - integer
                - 'null'
                format: u-int64
                description: Gas unit price defined by the chain for all automated transactions.
                minimum: 0
              block_gas_unit_price_min:
                type:
                - integer
                - 'null'
                description: Minimum gas unit price of the transactions included in the block.


# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/supra/refs/heads/main/openapi/supra-block-api-openapi.yml