Hiro Accounts API
Read-only endpoints to obtain Stacks account details
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hiro-accounts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts 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: Accounts
description: Read-only endpoints to obtain Stacks account details
externalDocs:
description: Stacks Documentation - Accounts
url: https://docs.stacks.co/network-fundamentals/accounts
paths:
/extended/v1/address/{principal}/stx:
get:
operationId: get_account_stx_balance
summary: Get account STX balance
tags:
- Accounts
description: "**NOTE:** This endpoint is deprecated in favor of [Get address STX balance](/api/get-principal-stx-balance).\n\n Retrieves STX token balance for a given Address or Contract Identifier."
parameters:
- schema:
default: false
type: boolean
example: true
in: query
name: unanchored
required: false
description: Include data from unanchored (i.e. unconfirmed) microblocks
- schema:
type: string
examples:
'60000':
value: '60000'
'0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79':
value: '0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79'
in: query
name: until_block
required: false
description: Block hash or block height. Return data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
- schema:
anyOf:
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}
title: STX Address
description: STX Address
examples:
- SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP
type: string
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
title: Smart Contract ID
description: Smart Contract ID
examples:
- SP000000000000000000002Q6VF78.pox-3
type: string
in: path
name: principal
required: true
deprecated: true
responses:
'200':
description: GET request that returns address balances
content:
application/json:
schema:
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
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/address/{principal}/balances:
get:
operationId: get_account_balance
summary: Get account balances
tags:
- Accounts
description: "**NOTE:** This endpoint is deprecated in favor of [Get address FT balances](/api/get-principal-ft-balances).\n\n Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of STX Tokens, Fungible Tokens and Non-Fungible Tokens for the account."
parameters:
- schema:
default: false
type: boolean
example: true
in: query
name: unanchored
required: false
description: Include data from unanchored (i.e. unconfirmed) microblocks
- schema:
type: string
examples:
'60000':
value: '60000'
'0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79':
value: '0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79'
in: query
name: until_block
required: false
description: Block hash or block height. Return data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
- schema:
anyOf:
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}
title: STX Address
description: STX Address
examples:
- SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP
type: string
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
title: Smart Contract ID
description: Smart Contract ID
examples:
- SP000000000000000000002Q6VF78.pox-3
type: string
in: path
name: principal
required: true
deprecated: true
responses:
'200':
description: GET request that returns address balances
content:
application/json:
schema:
title: AddressBalanceResponse
description: GET request that returns address balances
type: object
properties:
stx:
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
fungible_tokens:
type: object
additionalProperties:
title: FtBalance
type: object
properties:
balance:
type: string
total_sent:
type: string
total_received:
type: string
required:
- balance
- total_sent
- total_received
non_fungible_tokens:
type: object
additionalProperties:
title: NftBalance
type: object
properties:
count:
type: string
total_sent:
type: string
total_received:
type: string
required:
- count
- total_sent
- total_received
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:
- stx
- fungible_tokens
- non_fungible_tokens
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/address/{principal}/transactions:
get:
operationId: get_account_transactions
summary: Get account transactions
tags:
- Accounts
description: "**NOTE:** This endpoint is deprecated in favor of [Get address transactions](/api/get-address-transactions).\n\n Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/transactions/how-transactions-work#types).\n\n If you need to actively monitor new transactions for an address or contract id, 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: 50
title: Limit
type: integer
in: query
name: limit
required: false
description: Results per page
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: Result offset
- schema:
type: integer
in: query
name: height
required: false
description: Filter for transactions only at this given block height
- schema:
default: false
type: boolean
example: true
in: query
name: unanchored
required: false
description: Include data from unanchored (i.e. unconfirmed) microblocks
- schema:
type: string
examples:
'60000':
value: '60000'
'0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79':
value: '0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79'
in: query
name: until_block
required: false
description: Block hash or block height. Return data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
- 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.
- schema:
anyOf:
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}
title: STX Address
description: STX Address
examples:
- SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP
type: string
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
title: Smart Contract ID
description: Smart Contract ID
examples:
- SP000000000000000000002Q6VF78.pox-3
type: string
in: path
name: principal
required: true
deprecated: true
responses:
'200':
description: GET request that returns account transactions
content:
application/json:
schema:
title: AddressTransactionsListResponse
description: GET request that returns account 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) in
# --- truncated at 32 KB (689 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-accounts-api-openapi.yml