Cardano » Blocks API

openapi: 3.2.0
info:
  version: 0.1.89
  title: Blockfrost.io ~ API Documentation Cardano » Blocks API
  x-logo:
    url: https://staging.blockfrost.io/images/logo.svg
    altText: Blockfrost
  contact:
    name: Blockfrost Team
    url: https://blockfrost.io
    email: contact@blockfrost.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://blockfrost.io/terms
  description: Blockfrost is an API as a service that allows users to interact with the Cardano blockchain, Midnight blockchain, and parts of their ecosystems.
servers:
- url: https://cardano-mainnet.blockfrost.io/api/v0
  description: Cardano Mainnet network
- url: https://cardano-preprod.blockfrost.io/api/v0
  description: Cardano Preprod network
- url: https://cardano-preview.blockfrost.io/api/v0
  description: Cardano Preview network
- url: https://localhost:3000
  description: local
security:
- project_id: []
tags:
- name: Cardano » Blocks
paths:
  /blocks/latest:
    get:
      tags:
      - Cardano » Blocks
      summary: Latest block
      description: 'Return the latest block available to the backends, also known as the

        tip of the blockchain.'
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksLatest
      x-operation-id-source: derived
  /blocks/latest/txs:
    get:
      tags:
      - Cardano » Blocks
      summary: Latest block transactions
      description: Return the transactions within the latest block.
      parameters:
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Ordered by tx index in the block.

          The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_txs'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksLatestTxs
      x-operation-id-source: derived
  /blocks/latest/txs/cbor:
    get:
      tags:
      - Cardano » Blocks
      summary: Latest block transactions with CBOR data
      description: Return the transactions within the latest block, including CBOR representations.
      parameters:
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Ordered by tx index in the block.

          The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return the contents of the block with CBOR data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_txs_cbor'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksLatestTxsCbor
      x-operation-id-source: derived
  /blocks/{hash_or_number}:
    get:
      tags:
      - Cardano » Blocks
      summary: Specific block
      description: Return the content of a requested block.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash or number of the requested block.
        example: 4ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumber
      x-operation-id-source: derived
  /blocks/{hash_or_number}/next:
    get:
      tags:
      - Cardano » Blocks
      summary: Listing of next blocks
      description: Return the list of blocks following a specific block.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash of the requested block.
        example: 5ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_array'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumberNext
      x-operation-id-source: derived
  /blocks/{hash_or_number}/previous:
    get:
      tags:
      - Cardano » Blocks
      summary: Listing of previous blocks
      description: Return the list of blocks preceding a specific block.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash of the requested block
        example: '4873401'
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_array'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumberPrevious
      x-operation-id-source: derived
  /blocks/slot/{slot_number}:
    get:
      tags:
      - Cardano » Blocks
      summary: Specific block in a slot
      description: Return the content of a requested block for a specific slot.
      parameters:
      - in: path
        name: slot_number
        required: true
        schema:
          type: integer
          format: slot number
        description: Slot position for requested block.
        example: 30895909
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksSlotBySlotNumber
      x-operation-id-source: derived
  /blocks/epoch/{epoch_number}/slot/{slot_number}:
    get:
      tags:
      - Cardano » Blocks
      summary: Specific block in a slot in an epoch
      description: Return the content of a requested block for a specific slot in an epoch.
      parameters:
      - in: path
        name: epoch_number
        required: true
        schema:
          type: integer
          format: slot number
        description: Epoch for specific epoch slot.
        example: 219
      - in: path
        name: slot_number
        required: true
        schema:
          type: integer
          format: slot number
        description: Slot position for requested block.
        example: 30895909
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksEpochByEpochNumberSlotBySlotNumber
      x-operation-id-source: derived
  /blocks/{hash_or_number}/txs:
    get:
      tags:
      - Cardano » Blocks
      summary: Block transactions
      description: Return the transactions within the block.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash of the requested block.
        example: '4873401'
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Ordered by tx index in the block.

          The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_txs'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumberTxs
      x-operation-id-source: derived
  /blocks/{hash_or_number}/txs/cbor:
    get:
      tags:
      - Cardano » Blocks
      summary: Block transactions with CBOR data
      description: Return the transactions within the block, including CBOR representations.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash of the requested block.
        example: '4873401'
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Ordered by tx index in the block.

          The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return the contents of the block with CBOR data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_txs_cbor'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumberTxsCbor
      x-operation-id-source: derived
  /blocks/{hash_or_number}/addresses:
    get:
      tags:
      - Cardano » Blocks
      summary: Addresses affected in a specific block
      description: Return list of addresses affected in the specified block with additional information, sorted by the bech32 address, ascending.
      parameters:
      - in: path
        name: hash_or_number
        required: true
        schema:
          type: string
          format: 64-character case-sensitive hexadecimal string or block number.
        description: Hash of the requested block.
        example: '4873401'
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      responses:
        '200':
          description: Return the contents of the block
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/block_content_addresses'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      operationId: getBlocksByHashOrNumberAddresses
      x-operation-id-source: derived
components:
  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 400
              error:
                type: string
                example: Bad Request
              message:
                type: string
                example: Backend did not understand your request.
            required:
            - error
            - message
            - status_code
    '418':
      description: IP has been auto-banned for extensive sending of requests after usage limit has been reached
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 418
              error:
                type: string
                example: Requested Banned
              message:
                type: string
                example: IP has been auto-banned for flooding.
            required:
            - error
            - message
            - status_code
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 500
              error:
                type: string
                example: Internal Server Error
              message:
                type: string
                example: An unexpected response was received from the backend.
            required:
            - error
            - message
            - status_code
    '403':
      description: Authentication secret is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 403
              error:
                type: string
                example: Forbidden
              message:
                type: string
                example: Invalid project token.
            required:
            - error
            - message
            - status_code
    '404':
      description: Component not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 404
              error:
                type: string
                example: Not Found
              message:
                type: string
                example: The requested component has not been found.
            required:
            - error
            - message
            - status_code
    '429':
      description: Usage limit reached
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 429
              error:
                type: string
                example: Project Over Limit
              message:
                type: string
                example: Usage is over limit.
            required:
            - error
            - message
            - status_code
  schemas:
    block_content:
      type: object
      properties:
        time:
          type: integer
          example: 1641338934
          description: Block creation time in UNIX time
        height:
          type:
          - integer
          - 'null'
          example: 15243593
          description: Block number
        hash:
          type: string
          example: 4ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a
          description: Hash of the block
        slot:
          type:
          - integer
          - 'null'
          example: 412162133
          description: Slot number
        epoch:
          type:
          - integer
          - 'null'
          example: 425
          description: Epoch number
        epoch_slot:
          type:
          - integer
          - 'null'
          example: 12
          description: Slot within the epoch
        slot_leader:
          type: string
          example: pool1pu5jlj4q9w9jlxeu370a3c9myx47md5j5m2str0naunn2qnikdy
          description: Bech32 ID of the slot leader or specific block description in case there is no slot leader
        size:
          type: integer
          example: 3
          description: Block size in Bytes
        tx_count:
          type: integer
          example: 1
          description: Number of transactions in the block
        output:
          type:
          - string
          - 'null'
          example: '128314491794'
          description: Total output within the block in Lovelaces
        fees:
          type:
          - string
          - 'null'
          example: '592661'
          description: Total fees within the block in Lovelaces
        block_vrf:
          type:
          - string
          - 'null'
          example: vrf_vk1wf2k6lhujezqcfe00l6zetxpnmh9n6mwhpmhm0dvfh3fxgmdnrfqkms8ty
          description: VRF key of the block
          minLength: 65
          maxLength: 65
        op_cert:
          type:
          - string
          - 'null'
          example: da905277534faf75dae41732650568af545134ee08a3c0392dbefc8096ae177c
          description: The hash of the operational certificate of the block producer
        op_cert_counter:
          type:
          - string
          - 'null'
          example: '18'
          description: The value of the counter used to produce the operational certificate
        previous_block:
          type:
          - string
          - 'null'
          example: 43ebccb3ac72c7cebd0d9b755a4b08412c9f5dcb81b8a0ad1e3c197d29d47b05
          description: Hash of the previous block
        next_block:
          type:
          - string
          - 'null'
          example: 8367f026cf4b03e116ff8ee5daf149b55ba5a6ec6dec04803b8dc317721d15fa
          description: Hash of the next block
        confirmations:
          type: integer
          example: 4698
          description: Number of block confirmations
      required:
      - time
      - height
      - hash
      - slot
      - epoch
      - epoch_slot
      - slot_leader
      - size
      - tx_count
      - output
      - fees
      - block_vrf
      - op_cert
      - op_cert_counter
      - previous_block
      - next_block
      - confirmations
    block_content_txs_cbor:
      type: array
      items:
        type: object
        properties:
          tx_hash:
            type: string
            description: Hash of the transaction
          cbor:
            type: string
            description: CBOR representation of the transaction data
        required:
        - tx_hash
        - cbor
      example:
      - tx_hash: 8788591983aa73981fc92d6cddbbe643959f5a784e84b8bee0db15823f575a5b
        cbor: a10081825820cccfe2be401c85342497f6e1e4a241629790b0fb7f2af5f18441779d11f25b1f5840c38a93d63faac9335ecc2f24ead7ca2d46a6637f354ee707bb06eb8192af2fa6a676fb72f8772cd1c42b491ec6dfc798c76b61c55dc4eecab362e71ffab26305
      - tx_hash: 4eef6bb7755d8afbeac526b799f3e32a624691d166657e9d862aaeb66682c036
        cbor: bb06eb8192af2fa6a676fb72f8772cd1c42b491ec6dfc798c76b61c55dc4eecab362e71ffab26305
    block_content_txs:
      type: array
      items:
        type: string
        description: Hash of the transaction
      example:
      - 8788591983aa73981fc92d6cddbbe643959f5a784e84b8bee0db15823f575a5b
      - 4eef6bb7755d8afbeac526b799f3e32a624691d166657e9d862aaeb66682c036
      - 52e748c4dec58b687b90b0b40d383b9fe1f24c1a833b7395cdf07dd67859f46f
      - e8073fd5318ff43eca18a852527166aa8008bee9ee9e891f585612b7e4ba700b
    block_content_addresses:
      type: array
      items:
        type: object
        properties:
          address:
            type: string
            description: Address that was affected in the specified block
          transactions:
            type: array
            description: List of transactions containing the address either in their inputs or outputs. Sorted by transaction index within a block, ascending.
            items:
              type: object
              properties:
                tx_hash:
                  type: string
              required:
              - tx_hash
        required:
        - address
        - transactions
      example:
      - address: addr1q9ld26v2lv8wvrxxmvg90pn8n8n5k6tdst06q2s856rwmvnueldzuuqmnsye359fqrk8hwvenjnqultn7djtrlft7jnq7dy7wv
        transactions:
        - tx_hash: 1a0570af966fb355a7160e4f82d5a80b8681b7955f5d44bec0dce628516157f0
      - address: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
        transactions:
        - tx_hash: 1a0570af966fb355a7160e4f82d5a80b8681b7955f5d44bec0dce628516157d0
    block_content_array:
      type: array
      items:
        $ref: '#/components/schemas/block_content'
  securitySchemes:
    project_id:
      type: apiKey
      in: header
      name: project_id
      description: 'There are multiple token types available based on network you choose

        when creating a Blockfrost a project, for a list of token types

        see available networks.

        '