openapi: 3.2.0
info:
  description: API for Aeternity Middleware
  title: Aeternity Middleware Key Blocks API
  version: 1.108.2
servers:
- url: https://mainnet.aeternity.io/mdw/v3
  description: Mainnet middleware
- url: https://testnet.aeternity.io/mdw/v3
  description: Testnet middleware
tags:
- name: Key Blocks
paths:
  /key-blocks:
    get:
      deprecated: false
      description: Get multiple key blocks.
      operationId: GetKeyBlocks
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ScopeParam'
      - $ref: '#/components/parameters/DirectionParam'
      responses:
        '200':
          description: Returns paginated key blocks
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/KeyBlockExtended'
                - $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Key Blocks
      summary: Get key blocks
      x-summary-source: derived
  /key-blocks/{hash_or_kbi}:
    get:
      deprecated: false
      description: Get a single key block.
      operationId: GetKeyBlock
      parameters:
      - name: hash_or_kbi
        in: path
        description: The key block encoded hash or key block index
        required: true
        schema:
          oneOf:
          - $ref: '#/components/schemas/KeyBlockHash'
          - type: integer
            example: 123
      responses:
        '200':
          description: Returns a single key block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyBlockExtended'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
      tags:
      - Key Blocks
      summary: Get key block
      x-summary-source: derived
  /key-blocks/{hash_or_kbi}/micro-blocks:
    get:
      deprecated: false
      description: Get the key block micro blocks.
      operationId: GetKeyBlockMicroBlocks
      parameters:
      - name: hash_or_kbi
        in: path
        description: The key block encoded hash or key block index
        required: true
        schema:
          oneOf:
          - $ref: '#/components/schemas/KeyBlockHash'
          - type: integer
            example: 123
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/ScopeParam'
      - $ref: '#/components/parameters/DirectionParam'
      responses:
        '200':
          description: Returns paginated micro blocks
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/MicroBlockExtended'
                - $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Key Blocks
      summary: Get key block micro blocks
      x-summary-source: derived
components:
  schemas:
    KeyBlockExtended:
      example:
        beneficiary: ak_2MR38Zf355m6JtP13T3WEcUcSLVLCxjGvjk6zG95S2mfKohcSS
        beneficiary_reward: 5000000
        hash: kh_uoTGwc4HPzEW9qmiQR1zmVVdHmzU6YmnVvdFe6HvybJJRj7V6
        height: 123008
        info: cb_AAAAAfy4hFE=
        micro_blocks_count: 2
        miner: ak_Fqnmm5hRAMaVPWk8wzpodMopZgWghMns4mM7kSV1jgT89p9AV
        nonce: 9223756548132686000
        pow:
        - 12359907
        - 21243613
        - 31370838
        - 34911479
        - 39070315
        - 39375528
        - 45751339
        - 49864206
        - 56785423
        - 70282271
        - 89781776
        - 136985196
        - 140580763
        - 142415353
        - 145306210
        - 148449813
        - 156037609
        - 161568067
        - 170308922
        - 185345129
        - 192805579
        - 214115188
        - 220339679
        - 243288723
        - 258891016
        - 283001743
        - 284306909
        - 286457285
        - 326405486
        - 352963232
        - 377904500
        - 378120539
        - 380987399
        - 388675008
        - 447958786
        - 457602498
        - 465751225
        - 466823982
        - 475416389
        - 491255227
        - 530197445
        - 533633643
        prev_hash: kh_hwin2p8u87mqiK836FixGa1pL9eBkL1Ju37Yi6EUebCgAf8rm
        prev_key_hash: kh_hwin2p8u87mqiK836FixGa1pL9eBkL1Ju37Yi6EUebCgAf8rm
        state_hash: bs_9Dg6mTmiJLpbg9dzgjnNFVidQesvZYZG3dEviUCd4oE1hUcna
        target: 504082055
        time: 1565548832164
        transactions_count: 2
        version: 3
      title: Key Block Extended
      allOf:
      - $ref: '#/components/schemas/KeyBlock'
      - type: object
        required:
        - beneficiary_reward
        - flags
        - micro_blocks_count
        - transactions_count
        properties:
          beneficiary_reward:
            description: The beneficiary reward
            type: integer
          flags:
            $ref: '#/components/schemas/ByteArray'
          micro_blocks_count:
            description: The number of micro blocks
            type: integer
          transactions_count:
            description: The number of transactions
            type: integer
    EncodedPubkey:
      description: Base58Check encoded tagged pubkey
      type: string
    UInt64:
      oneOf:
      - type: integer
        minimum: 0
        maximum: 18446744073709552000
      - type: string
    NotFoundResponse:
      description: Resource not found on the API
      type: object
      example:
        error: 'not found: th_2Twp3pJeVuwQ7cMSdPQRfpAUWwdMiwx6coVMpRaNSuzFRnDZF'
      properties:
        error:
          description: The message of the error raised
          type: string
      required:
      - error
      title: Not found response
    EncodedHash:
      description: Base58Check encoded tagged hash
      type: string
    EncodedSignature:
      description: Base58Check encoded signature
      type: string
      example: sg_8hhU15cVMbukFj4FbdrFwwYnbzXYPnstu9PDnWZGbfQNpeHcB6tK1F3wvG1MPYySARgDRJYUh3YPJD3HctFwg6Y4rUGSR
      pattern: ^sg_\w+$
    Pow:
      type: array
      items:
        $ref: '#/components/schemas/UInt32'
      minItems: 42
      maxItems: 42
    MicroBlockHeader:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/EncodedHash'
        height:
          $ref: '#/components/schemas/UInt64'
        pof_hash:
          description: \"no_fraud\" or Base58Check encoded Proof of Fraud hash
          type: string
          pattern: ^(no_fraud|bf_\w+)$
          example: no_fraud
        prev_hash:
          $ref: '#/components/schemas/EncodedHash'
        prev_key_hash:
          $ref: '#/components/schemas/EncodedHash'
        state_hash:
          $ref: '#/components/schemas/EncodedHash'
        txs_hash:
          $ref: '#/components/schemas/EncodedHash'
        signature:
          $ref: '#/components/schemas/EncodedSignature'
        time:
          $ref: '#/components/schemas/UInt64'
        version:
          $ref: '#/components/schemas/UInt32'
        flags:
          $ref: '#/components/schemas/EncodedByteArray'
      required:
      - hash
      - height
      - pof_hash
      - prev_hash
      - prev_key_hash
      - state_hash
      - txs_hash
      - signature
      - time
      - version
    KeyBlockHash:
      description: Key block hash
      type: string
      example: kh_2Zfo2ALfRkKQxEaUj3HhcUGyMrTqYpDMgr2u15fPanYD1d55kz
      pattern: ^kh_\w{38,50}$
    UInt32:
      oneOf:
      - type: integer
        minimum: 0
        maximum: 4294967295
      - type: string
    KeyBlock:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/EncodedHash'
        height:
          $ref: '#/components/schemas/UInt64'
        prev_hash:
          $ref: '#/components/schemas/EncodedHash'
        prev_key_hash:
          $ref: '#/components/schemas/EncodedHash'
        state_hash:
          $ref: '#/components/schemas/EncodedHash'
        miner:
          $ref: '#/components/schemas/EncodedPubkey'
        beneficiary:
          $ref: '#/components/schemas/EncodedPubkey'
        flags:
          $ref: '#/components/schemas/EncodedByteArray'
        target:
          $ref: '#/components/schemas/UInt32'
        pow:
          $ref: '#/components/schemas/Pow'
        nonce:
          $ref: '#/components/schemas/UInt64'
        time:
          $ref: '#/components/schemas/UInt64'
        version:
          $ref: '#/components/schemas/UInt32'
        info:
          $ref: '#/components/schemas/EncodedContractByteArray'
      required:
      - hash
      - height
      - prev_hash
      - prev_key_hash
      - state_hash
      - miner
      - beneficiary
      - target
      - time
      - version
      - info
    EncodedByteArray:
      description: Base64Check encoded byte array
      type: string
      example: ba_AAAAAfy4hFE=
      pattern: ^ba_[0-9A-Za-z+/=]+$
    PaginatedResponse:
      type: object
      properties:
        next:
          type:
          - string
          - 'null'
          example: /blocks?cursor=123
        prev:
          type:
          - string
          - 'null'
          example: /blocks?cursor=234
      required:
      - next
      - prev
    ByteArray:
      type: string
      example: ba_wAAAAKv2ZV4=
      pattern: ^ba_\w+$
    ErrorResponse:
      description: Error response from the API
      type: object
      example:
        error: 'invalid id: th_2Twp3pJeVuwQ7cMSdPQRfpAUWwdMiwx6coVMpRaNSuzFRnDZF'
      properties:
        error:
          description: The message of the error raised
          type: string
      required:
      - error
      title: Error response
    MicroBlockExtended:
      example:
        micro_block_index: 64
        transactions_count: 1
        hash: mh_JryFr55GwbEbEJivkvHwBPzqbhu6AvpcZqCiBoXzgZdLmNn2K
        height: 685072
        pof_hash: no_fraud
        gas: 1950000
        prev_hash: mh_hH3qADCrnGvuup6JwjtNSacHLd9h3NJzAgr173jS9KUqijfTB
        prev_key_hash: kh_2rTj3FTZJ6fnuLFDJwAiDQZat2a23Lkp5uZQooxjwXEFhH4Vtw
        signature: sg_8hhU15cVMbukFj4FbdrFwwYnbzXYPnstu9PDnWZGbfQNpeHcB6tK1F3wvG1MPYySARgDRJYUh3YPJD3HctFwg6Y4rUGSR
        state_hash: bs_2bNSxvfhsPeAwN3LJU1oZLtUJ6GbeRdJYTEnFLAAazWtwPPqpN
        time: 1668435898477
        txs_hash: bx_2TAosDwRW2CwxbNiucN8hRfUHQcnJn2u3quDLPE9jAmgX26Qya
        version: 5
      title: Micro Block Extended
      allOf:
      - $ref: '#/components/schemas/MicroBlockHeader'
      - type: object
        required:
        - micro_block_index
        - transactions_count
        - gas
        - flags
        properties:
          micro_block_index:
            description: The index of the micro-block on the micro-block height, starting from 0
            type: integer
          transactions_count:
            description: The number of transactions
            type: integer
          gas:
            description: The gas used by the microblock
            type: integer
          flags:
            $ref: '#/components/schemas/ByteArray'
    EncodedContractByteArray:
      description: Base64Check encoded contract byte array
      type: string
      example: cb_AAAAAfy4hFE=
      pattern: ^cb_[0-9A-Za-z+/=]+$
  parameters:
    ScopeParam:
      in: query
      name: scope
      description: Scopes results in a generation range
      schema:
        type: string
        pattern: (gen):\d+(-\d+)?
    DirectionParam:
      in: query
      name: direction
      description: Sorts results in forwards or backwards direction
      schema:
        type: string
        enum:
        - forward
        - backward
    LimitParam:
      in: query
      name: limit
      description: Limit paginated resources (max 100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10