Skip to main content

/extended/v1/address/{principal}/balances REST API Endpoint

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.

Updated on
Oct 4, 2023

/extended/v1/address/{principal}/balances REST API Endpoint

Path Parameters

principal
string
REQUIRED
Stacks address or a Contract identifier (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info)

Query Parameters

unanchored
boolean
Include transaction data from unanchored (i.e. unconfirmed) microblocks.
until_block
string
returned data representing the state up until that point in time, rather than the current block.

Returns

object
array
GET request that returns address balances
stx
object
The native cryptocurrency
balance
string
The current balance of STX associated with the principal (address)
total_sent
string
The total amount of STX sent from the principal's address
total_received
string
The total amount of STX received by the principal's address
total_fees_sent
string
The total amount of STX used as transaction fees by the principal
total_miner_rewards_received
string
The total amount of STX received as miner rewards by the principal
lock_tx_id
string
The transaction ID where the lock event occurred. It is empty if no tokens are locked
locked
string
The amount of locked STX (quoted in micro-STX). It is zero if no tokens are locked
lock_height
integer
The STX chain block height when the lock event occurred. It is zero if no tokens are locked
burnchain_lock_height
integer
The burnchain block height when the lock event occurred. It is zero if no tokens are locked
burnchain_unlock_height
integer
The burnchain block height when the tokens unlock. It is zero if no tokens are locked
fungible_tokens
object
Information about the fungible tokens associated with the principal:
FtBalance
object
An object containing information about the balance of fungible tokens:
balance
string
The current balance of the fungible token associated with the principal
total_sent
string
The total amount of the fungible token sent from the principal's address
total_received
string
The total amount of the fungible token received by the principal's address
non_fungible_tokens
object
Information about the non-fungible tokens associated with the principal:
NftBalance
object
An object containing information about the balance of non-fungible tokens:
count
string
The total count of non-fungible tokens associated with the principal
total_sent
string
The total amount of non-fungible tokens sent from the principal's address
total_received
string
The total amount of non-fungible tokens received by the principal's address
token_offering_locked
object
Information about token offering locked amounts:
total_locked
string
The micro-STX amount still locked at the current block height
total_unlocked
string
The micro-STX amount still unlocked at the current block height
unlock_schedule
array
An array containing objects representing the scheduled unlocking of token offering amounts:
amount
string
The micro-STX amount locked at this block height
block_height
integer
The block height when the token offering amount will be unlocked
Request
1
curl -X 'GET' \
2
    'https://docs-demo.stacks-mainnet.quiknode.pro/extended/v1/address/SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9/balances' \
3
    -H 'Content-Type: application/json'
Don't have an account yet?
Create your QuickNode endpoint in seconds and start building
Get started for free