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
Jun 13, 2025

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
Don't have an account yet?
Create your Quicknode endpoint in seconds and start building
Get started for free