accountStates | TON v3

The accountStates endpoint queries account states from the TON blockchain, including historical state data. TON v3 via Chainstack.

GET /accountStates

Get Account States

cURL

curl --request GET \
  --url https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/accountStates

200

{
  "account_states": [
    {
      "account": "<string>",
      "hash": "<string>",
      "balance": "<string>",
      "account_status": "<string>",
      "last_trans_lt": 123,
      "last_trans_hash": "<string>",
      "frozen_hash": "<string>",
      "code_hash": "<string>",
      "data_hash": "<string>",
      "code_boc": "<string>",
      "data_boc": "<string>"
    }
  ],
  "address_book": {}
}

Account States

The accountStates endpoint queries account states from the TON blockchain, including historical state data. This endpoint provides detailed information about account balances, status, and optionally the code and data cells.

Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.

You can sign up with your GitHub, X, Google, or Microsoft account.

TON billing: full (1 RU)

This method is always billed as full. See Request units — TON method scope.

Parameters

• account_address (string, optional) — Account address to query.
• include_boc (boolean, optional) — Include code and data BoC in response. Default: false.
• limit (integer, optional) — Maximum number of states to return. Default: 10.
• offset (integer, optional) — Number of states to skip for pagination. Default: 0.
• sort (string, optional) — Sort order: asc or desc. Default: desc.

Response

• account_states (array) — Array of account state objects:

  • account (string) — Account address.
  • hash (string) — State hash.
  • balance (string) — Account balance in nanotons.
  • account_status (string) — Account status (active, uninit, frozen).
  • last_trans_lt (integer) — Logical time of last transaction.
  • last_trans_hash (string) — Hash of last transaction.
  • frozen_hash (string) — Hash if account is frozen.
  • code_hash (string) — Hash of the code cell.
  • data_hash (string) — Hash of the data cell.
  • code_boc (string) — Code BoC (if include_boc is true).
  • data_boc (string) — Data BoC (if include_boc is true).

• address_book (object) — Address book mapping.

Use case

The accountStates endpoint is useful for applications that need detailed account information:

1. Block explorers displaying account history and state changes.
2. Smart contract analysis tools examining code and data.
3. Wallet applications showing detailed account information.
4. Auditing tools tracking account state over time.
5. Research applications studying account behavior patterns.

Here’s an example of querying account state:

shell

curl -X GET \
  'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/accountStates?account_address=EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs&include_boc=true&limit=1' \
  -H 'accept: application/json'

Set include_boc to true only when you need the actual code and data cells, as this significantly increases response size.

Query Parameters

account_address · string · default: EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs

Account address to query

include_boc · boolean · default: false

Include account state BoC in response

limit · integer · default: 10

Maximum number of states to return

offset · integer · default: 0

Number of states to skip

sort · enum<string> · default: desc

Sort order

Available options: asc, desc

Response

200 - application/json

Successful response

account_states · object[]

Show child attributes

address_book · object

Address book mapping