Hiro Accounts API
Read-only endpoints to obtain Stacks account details
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