Accounts

Endpoints for retrieving account information.

Get account info

get

/v2/accounts/{principal}

Get the account data for the provided principal

Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings.

For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.

Path parameters

principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$

Query parameters

proofinteger · enumOptional

Controls MARF proof inclusion in response. Set to 1 (default) to include proof, 0 to exclude. Invalid values default to 0 (no proof).

Default: 1Example: 1Possible values:

tipstring · max: 64Optional

Stacks chain tip to query from. Options:

• (empty/omitted): Use latest anchored tip (canonical confirmed state)
• latest: Use latest known tip including unconfirmed microblocks
• {block_id}: Use specific block ID (64 hex characters)

Example: latestPattern: ^(latest|[0-9a-f]{64})?$

Responses

200

Success

application/json

GET request for account data

balancestringRequired

lockedstringRequired

unlock_heightintegerRequired

Block height when locked balance unlocks (64-bit unsigned integer)

nonceintegerRequired

Account transaction nonce (64-bit unsigned integer)

balance_proofstringOptional

Merkle proof for the balance value

nonce_proofstringOptional

Merkle proof for the nonce value

400

Bad request

text/plain

404

Not found

text/plain

500

Internal Server Error

text/plain

get/v2/accounts/{principal}

GET /v2/accounts/{principal} HTTP/1.1
Host: localhost:20443
Accept: */*

{
  "balance": "0x0000000000000000000000000007a120",
  "locked": "0x0000000000000000000000000007a120",
  "unlock_height": 126,
  "nonce": 2867,
  "balance_proof": "0xabce",
  "nonce_proof": "0xabcd"
}