Skip to main content
GET
/
walletStates
Get Wallet States
curl --request GET \
  --url https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/walletStates
{
  "wallets": [
    {
      "address": "<string>",
      "is_wallet": true,
      "balance": "<string>",
      "status": "<string>",
      "code_hash": "<string>",
      "last_transaction_hash": "<string>",
      "last_transaction_lt": "<string>"
    }
  ],
  "address_book": {}
}

​
Wallet States

The walletStates endpoint queries wallet state information for addresses, including balance, status, and whether the address is a recognized wallet contract.
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

  • address (string, required) — The wallet address to query.
  • limit (integer, optional) — Maximum number of results. Default: 10.
  • offset (integer, optional) — Number of results to skip. Default: 0.

​
Response

  • wallets (array) — Array of wallet state objects:
    • address (string) — Wallet address.
    • is_wallet (boolean) — Whether the address is a recognized wallet contract.
    • balance (string) — Balance in nanotons.
    • status (string) — Account status (active, uninit, frozen).
    • code_hash (string) — Hash of the code cell.
    • last_transaction_hash (string) — Hash of last transaction.
    • last_transaction_lt (string) — Logical time of last transaction.
  • address_book (object) — Address book mapping with names for known addresses.

​
Use case

The walletStates endpoint is useful for applications working with wallet contracts:
  1. Wallet applications displaying account status and balance.
  2. Portfolio trackers monitoring multiple addresses.
  3. Payment systems verifying wallet state before transactions.
  4. Block explorers identifying wallet types.
  5. Analytics tools categorizing addresses as wallets vs contracts.
Here’s an example of getting wallet state: 
curl -X GET \
  'https://ton-mainnet.core.chainstack.com/f2a2411bce1e54a2658f2710cd7969c3/api/v3/walletStates?address=EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs' \
  -H 'accept: application/json'
The is_wallet field indicates whether the contract matches a known wallet implementation (v3, v4, etc.). Jetton masters and other contracts will show false.

Query Parameters

​
address
string
default:EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
required

Wallet address to query

​
limit
integer
default:10

Maximum number of results

​
offset
integer
default:0

Number of results to skip

Response

200 - application/json

Successful response

​
wallets
object[]
​
address_book
object

Address book mapping