Hiro Microblocks API
Read-only endpoints to obtain microblocks details
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Microblocks API
description: Welcome to the API reference overview for the Signer Metrics API.
version: 1.0.3
servers:
- url: https://api.hiro.so/
description: mainnet
- url: https://api.testnet.hiro.so/
description: testnet
tags:
- name: Microblocks
description: Read-only endpoints to obtain microblocks details
externalDocs:
description: Stacks Documentation - Microblocks
url: https://docs.stacks.co/understand-stacks/microblocks
paths:
/extended/v1/microblock/:
get:
operationId: get_microblock_list
summary: Get recent microblocks
tags:
- Microblocks
description: "Retrieves a list of microblocks.\n\n If you need to actively monitor new microblocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates."
parameters:
- schema:
minimum: 0
default: 20
maximum: 200
title: Limit
type: integer
in: query
name: limit
required: false
description: Max number of microblocks to fetch
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: Result offset
responses:
'200':
description: GET request that returns microblocks
content:
application/json:
schema:
title: MicroblockListResponse
description: GET request that returns microblocks
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
total:
type: integer
example: 1
results:
type: array
items:
title: Microblock
description: A microblock
type: object
properties:
canonical:
description: Set to `true` if the microblock corresponds to the canonical chain tip.
type: boolean
microblock_canonical:
description: Set to `true` if the microblock was not orphaned in a following anchor block. Defaults to `true` if the following anchor block has not yet been created.
type: boolean
microblock_hash:
description: The SHA512/256 hash of this microblock.
type: string
microblock_sequence:
description: A hint to describe how to order a set of microblocks. Starts at 0.
type: integer
microblock_parent_hash:
description: The SHA512/256 hash of the previous signed microblock in this stream.
type: string
block_height:
description: The anchor block height that confirmed this microblock.
type: integer
parent_block_height:
description: The height of the anchor block that preceded this microblock.
type: integer
parent_block_hash:
description: The hash of the anchor block that preceded this microblock.
type: string
parent_burn_block_hash:
description: The hash of the Bitcoin block that preceded this microblock.
type: string
parent_burn_block_time:
description: The block timestamp of the Bitcoin block that preceded this microblock.
type: integer
parent_burn_block_time_iso:
description: The ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) formatted block time of the bitcoin block that preceded this microblock.
type: string
parent_burn_block_height:
description: The height of the Bitcoin block that preceded this microblock.
type: integer
block_hash:
anyOf:
- description: The hash of the anchor block that confirmed this microblock. This wil be empty for unanchored microblocks
type: string
- type: 'null'
txs:
description: List of transactions included in the microblock
type: array
items:
type: string
required:
- canonical
- microblock_canonical
- microblock_hash
- microblock_sequence
- microblock_parent_hash
- block_height
- parent_block_height
- parent_block_hash
- parent_burn_block_hash
- parent_burn_block_time
- parent_burn_block_time_iso
- parent_burn_block_height
- block_hash
- txs
required:
- limit
- offset
- total
- results
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/microblock/{hash}:
get:
operationId: get_microblock_by_hash
summary: Get microblock
tags:
- Microblocks
description: Retrieves a specific microblock by `hash`
parameters:
- schema:
type: string
example: '0x3bfcdf84b3012adb544cf0f6df4835f93418c2269a3881885e27b3d58eb82d47'
in: path
name: hash
required: true
description: Hash of the microblock
responses:
'200':
description: A microblock
content:
application/json:
schema:
title: Microblock
description: A microblock
type: object
properties:
canonical:
description: Set to `true` if the microblock corresponds to the canonical chain tip.
type: boolean
microblock_canonical:
description: Set to `true` if the microblock was not orphaned in a following anchor block. Defaults to `true` if the following anchor block has not yet been created.
type: boolean
microblock_hash:
description: The SHA512/256 hash of this microblock.
type: string
microblock_sequence:
description: A hint to describe how to order a set of microblocks. Starts at 0.
type: integer
microblock_parent_hash:
description: The SHA512/256 hash of the previous signed microblock in this stream.
type: string
block_height:
description: The anchor block height that confirmed this microblock.
type: integer
parent_block_height:
description: The height of the anchor block that preceded this microblock.
type: integer
parent_block_hash:
description: The hash of the anchor block that preceded this microblock.
type: string
parent_burn_block_hash:
description: The hash of the Bitcoin block that preceded this microblock.
type: string
parent_burn_block_time:
description: The block timestamp of the Bitcoin block that preceded this microblock.
type: integer
parent_burn_block_time_iso:
description: The ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) formatted block time of the bitcoin block that preceded this microblock.
type: string
parent_burn_block_height:
description: The height of the Bitcoin block that preceded this microblock.
type: integer
block_hash:
anyOf:
- description: The hash of the anchor block that confirmed this microblock. This wil be empty for unanchored microblocks
type: string
- type: 'null'
txs:
description: List of transactions included in the microblock
type: array
items:
type: string
required:
- canonical
- microblock_canonical
- microblock_hash
- microblock_sequence
- microblock_parent_hash
- block_height
- parent_block_height
- parent_block_hash
- parent_burn_block_hash
- parent_burn_block_time
- parent_burn_block_time_iso
- parent_burn_block_height
- block_hash
- txs
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/microblock/unanchored/txs:
get:
operationId: get_unanchored_txs
summary: Get the list of current transactions that belong to unanchored microblocks
tags:
- Microblocks
description: Retrieves transactions that have been streamed in microblocks but not yet accepted or rejected in an anchor block
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
total:
type: integer
results:
type: array
items:
anyOf:
- title: TokenTransferTransaction
type: object
properties:
tx_id:
description: Transaction ID
type: string
nonce:
description: Used for ordering the transactions originating from and paying from an account. The nonce ensures that a transaction is processed at most once. The nonce counts the number of times an account's owner(s) have authorized a transaction. The first transaction from an account will have a nonce value equal to 0, the second will have a nonce value equal to 1, and so on.
type: integer
fee_rate:
description: Transaction fee as Integer string (64-bit unsigned integer).
type: string
sender_address:
description: Address of the transaction initiator
type: string
sponsor_nonce:
type: integer
sponsored:
description: Denotes whether the originating account is the same as the paying account
type: boolean
sponsor_address:
type: string
post_condition_mode:
anyOf:
- type: string
enum:
- allow
- type: string
enum:
- deny
post_conditions:
type: array
items:
anyOf:
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent_equal_to
- type: string
enum:
- sent_greater_than
- type: string
enum:
- sent_greater_than_or_equal_to
- type: string
enum:
- sent_less_than
- type: string
enum:
- sent_less_than_or_equal_to
amount:
type: string
type:
type: string
enum:
- stx
required:
- principal
- condition_code
- amount
- type
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent_equal_to
- type: string
enum:
- sent_greater_than
- type: string
enum:
- sent_greater_than_or_equal_to
- type: string
enum:
- sent_less_than
- type: string
enum:
- sent_less_than_or_equal_to
amount:
type: string
type:
type: string
enum:
- fungible
asset:
type: object
properties:
asset_name:
type: string
contract_address:
type: string
contract_name:
type: string
required:
- asset_name
- contract_address
- contract_name
required:
- principal
- condition_code
- amount
- type
- asset
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent
- type: string
enum:
- not_sent
type:
type: string
enum:
- non_fungible
asset_value:
type: object
properties:
hex:
type: string
repr:
type: string
required:
- hex
- repr
asset:
type: object
properties:
asset_name:
type: string
contract_address:
type: string
contract_name:
type: string
required:
- asset_name
- contract_address
- contract_name
required:
- principal
- condition_code
- type
- asset_value
- asset
anchor_mode:
description: '`on_chain_only`: the transaction MUST be included in an anchored block, `off_chain_only`: the transaction MUST be included in a microblock, `any`: the leader can choose where to include the transaction.'
anyOf:
- type: string
enum:
- on_chain_only
- type: string
enum:
- off_chain_only
- type: string
enum:
- any
block_hash:
description: Hash of the blocked this transactions was associated with
type: string
block_height:
description: Height of the block this transactions was associated with
type: integer
block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.
type: string
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: integer
burn_block_height:
description: Height of the anchor burn block.
type: integer
burn_block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this block was mined.
type: string
parent_burn_block_time:
description: Unix timestamp (in seconds) indicating when this parent block was mined
type: integer
parent_burn_block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this parent block was mined.
type: string
canonical:
description: Set to `true` if block corresponds to the canonical chain tip
type: boolean
tx_index:
description: Index of the transaction, indicating the order. Starts at `0` and increases with each transaction
type: integer
tx_status:
description: Status of the transaction
anyOf:
- type: string
enum:
- success
- type: string
enum:
- abort_by_response
- type: string
enum:
- abort_by_post_condition
tx_result:
description: Result of the transaction. For contract calls, this will show the value returned by the call. For other transaction types, this will return a boolean indicating the success of the transaction.
additionalProperties: false
type: object
properties:
hex:
description: Hex string representing the value fo the transaction result
type: string
repr:
description: Readable string of the transaction result
type: string
required:
- hex
- repr
event_count:
description: Number of transaction events
type: integer
parent_block_hash:
description: Hash of the previous block.
type: string
is_unanchored:
description: True if the transaction is included in a microblock that has not been confirmed by an anchor block.
type: boolean
microblock_hash:
description: The microblock hash that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be an empty string.
type: string
microblock_sequence:
description: The microblock sequence number that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be 2147483647 (0x7fffffff, the max int32 value), this value preserves logical transaction ordering on (block_height, microblock_sequence, tx_index).
type: integer
microblock_canonical:
description: Set to `true` if microblock is anchored in the canonical chain tip, `false` if the transaction was orphaned in a micro-fork.
type: boolean
execution_cost_read_count:
description: Execution cost read count.
type: integer
execution_cost_read_length:
description: Execution cost read length.
type: integer
execution_cost_runtime:
description: Execution cost runtime.
type: integer
execution_cost_write_count:
description: Execution cost write count.
type: integer
execution_cost_write_length:
description: Execution cost write length.
type: integer
vm_error:
anyOf:
- description: Clarity VM error produced by this transaction
type: string
- type: 'null'
events:
type: array
items:
anyOf:
- title: SmartContractLogTransactionEvent
description: Only present in `smart_contract` and `contract_call` tx types.
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- smart_contract_log
tx_id:
type: string
contract_log:
type: object
properties:
contract_id:
type: string
topic:
type: string
value:
type: object
properties:
# --- truncated at 32 KB (222 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-microblocks-api-openapi.yml