> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# accountStates | TON v3

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

# 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.

<Note>
  **TON billing: full (1 RU)**

  This method is always billed as full. See [Request units — TON method scope](/docs/request-units#ton-method-scope).
</Note>

## 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:

<CodeGroup>
  ```shell shell theme={"system"}
  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'
  ```
</CodeGroup>

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


## OpenAPI

````yaml openapi/ton_node_api/v3/getAccountStates.json GET /accountStates
openapi: 3.0.0
info:
  title: TON API
  version: 3.0.0
  description: API for interacting with The Open Network (TON) blockchain
servers:
  - url: >-
      https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3
security: []
paths:
  /accountStates:
    get:
      tags:
        - Accounts
      summary: Get Account States
      description: Query account states with historical data
      operationId: getAccountStates
      parameters:
        - name: account_address
          in: query
          description: Account address to query
          schema:
            type: string
            default: EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
        - name: include_boc
          in: query
          description: Include account state BoC in response
          schema:
            type: boolean
            default: false
        - name: limit
          in: query
          description: Maximum number of states to return
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          description: Number of states to skip
          schema:
            type: integer
            default: 0
        - name: sort
          in: query
          description: Sort order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_states:
                    type: array
                    items:
                      type: object
                      properties:
                        account:
                          type: string
                          description: Account address
                        hash:
                          type: string
                          description: State hash
                        balance:
                          type: string
                          description: Account balance in nanotons
                        account_status:
                          type: string
                          description: Account status (active, uninit, frozen)
                        last_trans_lt:
                          type: integer
                          description: Last transaction logical time
                        last_trans_hash:
                          type: string
                          description: Last transaction hash
                        frozen_hash:
                          type: string
                          description: Frozen hash if account is frozen
                        code_hash:
                          type: string
                          description: Code cell hash
                        data_hash:
                          type: string
                          description: Data cell hash
                        code_boc:
                          type: string
                          description: Code BoC if include_boc is true
                        data_boc:
                          type: string
                          description: Data BoC if include_boc is true
                  address_book:
                    type: object
                    description: Address book mapping

````