Stacks Blockchain API
REST API for Stacks blockchain data: blocks, transactions, mempool, accounts, smart contracts, BNS names, fungible/non-fungible tokens, microblocks, faucets, fee rates.
OpenAPI Specification
openapi: 3.0.3
info:
title: Stacks Blockchain API
description: >-
Welcome to the API reference overview for the [Stacks Blockchain
API](https://docs.hiro.so/stacks-blockchain-api).
[Download Postman collection](https://hirosystems.github.io/stacks-blockchain-api/collection.json)
version: v8.14.2
components:
schemas: {}
paths:
/extended:
get:
operationId: get_status
summary: API status
tags:
- Info
description: Retrieves the running status of the Stacks Blockchain API,
including the server version and current chain tip information.
responses:
"200":
description: Default Response
content:
application/json:
schema:
title: Api Status Response
type: object
properties:
server_version:
description: the server version that is currently running
type: string
status:
description: the current server status
type: string
pox_v1_unlock_height:
anyOf:
- type: integer
- type: "null"
pox_v2_unlock_height:
anyOf:
- type: integer
- type: "null"
pox_v3_unlock_height:
anyOf:
- type: integer
- type: "null"
chain_tip:
anyOf:
- type: object
properties:
block_height:
description: the current block height
type: integer
block_hash:
description: the current block hash
type: string
index_block_hash:
description: the current index block hash
type: string
microblock_hash:
description: the current microblock hash
type: string
microblock_sequence:
description: the current microblock sequence number
type: integer
burn_block_height:
description: the current burn chain block height
type: integer
required:
- block_height
- block_hash
- index_block_hash
- burn_block_height
- type: "null"
required:
- server_version
- status
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/tx/:
get:
operationId: get_transaction_list
summary: Get recent transactions
tags:
- Transactions
description: Retrieves all recently mined transactions
parameters:
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: Result offset
- schema:
minimum: 0
default: 20
maximum: 50
title: Limit
type: integer
in: query
name: limit
required: false
description: Results per page
- schema:
type: array
items:
anyOf:
- type: string
enum:
- coinbase
- type: string
enum:
- token_transfer
- type: string
enum:
- smart_contract
- type: string
enum:
- contract_call
- type: string
enum:
- poison_microblock
- type: string
enum:
- tenure_change
in: query
name: type
required: false
- schema:
default: false
type: boolean
example: true
in: query
name: unanchored
required: false
description: Include data from unanchored (i.e. unconfirmed) microblocks
- schema:
anyOf:
- type: string
enum:
- asc
- type: string
enum:
- desc
in: query
name: order
required: false
- schema:
default: block_height
anyOf:
- type: string
enum:
- block_height
- type: string
enum:
- burn_block_time
- type: string
enum:
- fee
in: query
name: sort_by
required: false
description: Option to sort results by block height, timestamp, or fee
- schema:
type: string
in: query
name: from_address
required: false
description: Option to filter results by sender address
- schema:
type: string
in: query
name: to_address
required: false
description: Option to filter results by recipient address
- schema:
type: integer
example: 1704067200
in: query
name: start_time
required: false
description: Filter by transactions after this timestamp (unix timestamp in
seconds)
- schema:
type: integer
example: 1706745599
in: query
name: end_time
required: false
description: Filter by transactions before this timestamp (unix timestamp in
seconds)
- schema:
type: string
example: SP000000000000000000002Q6VF78.pox-4
in: query
name: contract_id
required: false
description: Option to filter results by contract ID
- schema:
type: string
example: delegate-stx
in: query
name: function_name
required: false
description: Filter by contract call transactions involving this function name
- schema:
minimum: 0
maximum: 9007199254740991
type: integer
example: 123
in: query
name: nonce
required: false
description: Filter by transactions with this nonce
- schema:
default: false
type: boolean
examples:
"true":
value: true
"false":
value: false
in: query
name: exclude_function_args
required: false
description: Exclude function_args from contract call responses for smaller
transaction sizes.
responses:
"200":
description: List of transactions
content:
application/json:
schema:
description: List of transactions
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
total:
type: integer
example: 1
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:
hex:
type: string
repr:
# --- truncated at 32 KB (5017 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-stacks-blockchain-api-openapi.yaml