Hiro Search API
Read-only endpoints to search for accounts, blocks, smart contracts, and transactions
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Search 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: Search
description: Read-only endpoints to search for accounts, blocks, smart contracts, and transactions
paths:
/extended/v1/search/{id}:
get:
operationId: search_by_id
summary: Search
tags:
- Search
description: Search blocks, transactions, contracts, or accounts by hash/ID
parameters:
- schema:
default: false
type: boolean
in: query
name: include_metadata
required: false
description: This includes the detailed data for purticular hash in the response
- schema:
type: string
example: '0xcf8b233f19f6c07d2dc1963302d2436efd36e9afac127bf6582824a13961c06d'
in: path
name: id
required: true
description: The hex hash string for a block or transaction, account address, or contract address
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
found:
type: boolean
enum:
- true
result:
anyOf:
- title: AddressSearchResult
description: Address search result
type: object
properties:
entity_id:
description: The id used to search this query.
type: string
entity_type:
type: string
enum:
- standard_address
metadata:
title: AddressStxBalance
description: GET request that returns address balances
type: object
allOf:
- title: StxBalance
type: object
properties:
balance:
type: string
estimated_balance:
description: Total STX balance considering pending mempool transactions
type: string
pending_balance_inbound:
description: Inbound STX balance from pending mempool transactions
type: string
pending_balance_outbound:
description: Outbound STX balance from pending mempool transactions
type: string
total_sent:
type: string
total_received:
type: string
total_fees_sent:
type: string
total_miner_rewards_received:
type: string
lock_tx_id:
description: The transaction where the lock event occurred. Empty if no tokens are locked.
type: string
locked:
description: The amount of locked STX, as string quoted micro-STX. Zero if no tokens are locked.
type: string
lock_height:
description: The STX chain block height of when the lock event occurred. Zero if no tokens are locked.
type: integer
burnchain_lock_height:
description: The burnchain block height of when the lock event occurred. Zero if no tokens are locked.
type: integer
burnchain_unlock_height:
description: The burnchain block height of when the tokens unlock. Zero if no tokens are locked.
type: integer
required:
- balance
- total_miner_rewards_received
- lock_tx_id
- locked
- lock_height
- burnchain_lock_height
- burnchain_unlock_height
- type: object
properties:
token_offering_locked:
title: AddressTokenOfferingLocked
description: Token Offering Locked
type: object
properties:
total_locked:
description: Micro-STX amount still locked at current block height.
type: string
total_unlocked:
description: Micro-STX amount unlocked at current block height.
type: string
unlock_schedule:
type: array
items:
title: AddressUnlockSchedule
description: Unlock schedule amount and block height
type: object
properties:
amount:
description: Micro-STX amount locked at this block height.
type: string
block_height:
type: integer
required:
- amount
- block_height
required:
- total_locked
- total_unlocked
- unlock_schedule
required:
- entity_id
- entity_type
- title: BlockSearchResult
description: Block search result
type: object
properties:
entity_id:
description: The id used to search this query.
type: string
entity_type:
type: string
enum:
- block_hash
block_data:
type: object
properties:
canonical:
type: boolean
hash:
type: string
parent_block_hash:
type: string
burn_block_time:
type: integer
height:
type: integer
required:
- canonical
- hash
- parent_block_hash
- burn_block_time
- height
metadata:
title: Block
description: A block
type: object
properties:
canonical:
description: Set to `true` if block corresponds to the canonical chain tip
type: boolean
height:
description: Height of the block
type: integer
hash:
description: Hash representing the block
type: string
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
tenure_height:
description: The tenure height (AKA coinbase height) of this block
type: integer
index_block_hash:
description: The only hash that can uniquely identify an anchored block or an unconfirmed state trie
type: string
parent_block_hash:
description: Hash of the parent block
type: string
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
burn_block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.
type: string
burn_block_hash:
description: Hash of the anchor chain block
type: string
burn_block_height:
description: Height of the anchor chain block
type: integer
miner_txid:
description: Anchor chain transaction ID
type: string
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
txs:
description: List of transactions included in the block
type: array
items:
description: Transaction ID
type: string
parent_microblock_hash:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: string
parent_microblock_sequence:
description: The hash of the last streamed block that precedes this block to which this block is to be appended. Not every anchored block will have a parent microblock stream. An anchored block that does not have a parent microblock stream has the parent microblock hash set to an empty string, and the parent microblock sequence number set to -1.
type: integer
microblocks_accepted:
description: List of microblocks that were accepted in this anchor block. Not every anchored block will have a accepted all (or any) of the previously streamed microblocks. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblocks_streamed:
description: List of microblocks that were streamed/produced by this anchor block's miner. This list only includes microblocks that were accepted in the following anchor block. Microblocks that were orphaned are not included in this list.
type: array
items:
description: Microblock hash
type: string
microblock_tx_count:
description: List of txs counts in each accepted microblock
type: object
additionalProperties:
type: integer
required:
- canonical
- height
- hash
- block_time
- block_time_iso
- tenure_height
- index_block_hash
- parent_block_hash
- burn_block_time
- burn_block_time_iso
- burn_block_hash
- burn_block_height
- miner_txid
- execution_cost_read_count
- execution_cost_read_length
- execution_cost_runtime
- execution_cost_write_count
- execution_cost_write_length
- txs
- parent_microblock_hash
- parent_microblock_sequence
- microblocks_accepted
- microblocks_streamed
- microblock_tx_count
required:
- entity_id
- entity_type
- block_data
- title: ContractSearchResult
description: Contract search result
type: object
properties:
entity_id:
description: The id used to search this query.
type: string
entity_type:
type: string
enum:
- contract_address
tx_data:
type: object
properties:
canonical:
type: boolean
block_hash:
type: string
burn_block_time:
type: integer
block_height:
type: integer
tx_type:
type: string
tx_id:
type: string
required:
- tx_type
- tx_id
metadata:
anyOf:
- 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:
# --- truncated at 32 KB (695 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-search-api-openapi.yml