Skip to main content

/extended/v3/principals/{principal}/balance-changes REST API Endpoint

Returns the balance changes for a principal across one or more transactions, as a single paginated flat array ordered by chain position descending then by asset.

Updated on
Aug 18, 2026

Path Parameters

principal
string
REQUIRED

Stacks account or contract principal.

Query Parameters

limit
integer

Number of results per page

cursor
string

(Optional) Cursor for paginating principal balance changes across multiple transactions. Format: <block_height>:<microblock_sequence>:<tx_index>:<asset_type>:<asset_identifier>.

tx_id
array
REQUIRED

Transaction IDs to query balance changes for. Provide as repeated querystring values (?tx_id=A&tx_id=B) or as a single comma-separated value (?tx_id=A,B).

Returns

total
integer

Total number of matching records.

limit
integer

Number of results per page

cursor
object

Cursor metadata for this page of results.

next
string | null

Cursor for the next page, or null when there is no next page.

previous
string | null

Cursor for the previous page, or null when there is no previous page.

current
string

Cursor identifying the current page.

results
array

Items returned for the current page.

tx_id
string

Transaction ID

asset
object

Asset associated with the balance change.

Response variant.

type
string

Discriminator identifying the record or transaction variant.

type
string

Discriminator identifying the record or transaction variant.

balance_change
object

Change in the asset balance.

sent
string

Amount sent by the principal

received
string

Amount received by the principal

net
string

Net balance change for the principal

Request
Response
1
{
2
"total": 1,
3
"limit": 1,
4
"cursor": {
5
"next": null,
6
"previous": null,
7
"current": "8702017:2147483647:5:1:stx"
8
},
9
"results": [
10
{
11
"tx_id": "0x7793237893fe95cd64e8ba44c798ae7e42a51d90515f16d7bf4810a1f512c0a8",
12
"asset": {
13
"type": "stx"
14
},
15
"balance_change": {
16
"sent": "579",
17
"received": "0",
18
"net": "-579"
19
}
20
}
21
]
22
}
1
{
2
"total": 1,
3
"limit": 1,
4
"cursor": {
5
"next": null,
6
"previous": null,
7
"current": "8702017:2147483647:5:1:stx"
8
},
9
"results": [
10
{
11
"tx_id": "0x7793237893fe95cd64e8ba44c798ae7e42a51d90515f16d7bf4810a1f512c0a8",
12
"asset": {
13
"type": "stx"
14
},
15
"balance_change": {
16
"sent": "579",
17
"received": "0",
18
"net": "-579"
19
}
20
}
21
]
22
}
Don't have an account yet?
Create your Quicknode endpoint in seconds and start building
Get started for free