Skip to main content

/extended/v3/principals/{principal}/staking/bonds REST API Endpoint

Get a principal's bond positions — its enrollment, lock, status, and sBTC rewards in each bond it participates in.

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 bonds. Format: bond_index

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.

bond_index
integer

The index of the bond in the PoX-5 bond list

status
string

Current status of the transaction or record.

active
boolean

Whether the position is active

enrollment
object

Signer enrollment details.

tx_id
string

Transaction ID

btc_lockup
object

Bitcoin lockup details for the bond.

amount
string

The amount of BTC that is locked up for this principal

locked
object

Locked STX balance or lock details.

btc
string

The amount of BTC locked in this bond position

stx
string

The amount of STX locked in this bond position

rewards
object

Stacking reward details.

btc
object

Bitcoin lockup and reward details.

accrued
string

The lifetime sBTC reward sats accrued to this position

claimed
string

The lifetime sBTC reward sats already claimed against this position

claimable
string

The sBTC reward sats currently claimable (accrued minus claimed)

Request
Response
1
{
2
"total": 0,
3
"limit": 1,
4
"cursor": {
5
"next": null,
6
"previous": null,
7
"current": null
8
},
9
"results": []
10
}
1
{
2
"total": 0,
3
"limit": 1,
4
"cursor": {
5
"next": null,
6
"previous": null,
7
"current": null
8
},
9
"results": []
10
}
Don't have an account yet?
Create your Quicknode endpoint in seconds and start building
Get started for free