Skip to main content
GET
/
accountStates
Get Account States
curl --request GET \
  --url https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/accountStates
{
  "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 you own node endpoint todayStart 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 pricing is the same for full, archive, v2, v3There’s no difference between a full node an archive node in data availability or pricing. All data is always available and all node requests are consumed as 1 request unit.

​
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: 
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[]
​
address_book
object

Address book mapping