Get address state

Returns the lifecycle state of an account. Possible values: uninitialized (address has no deployed contract but can receive TON), active (contract is deployed and working), frozen (contract suspended due to zero balance, send TON to unfreeze). Refer to the account lifecycle states documentation for details. Check this before interacting with a contract.

GET /api/v2/getAddressState

Get address state

cURL

curl --request GET \
  --url https://toncenter.com/api/v2/getAddressState \
  --header 'X-API-Key: <api-key>'

200

{
  "ok": true,
  "result": "uninitialized",
  "@extra": "<string>"
}

Authorizations

APIKeyHeaderAPIKeyQuery

X-API-Key · string · header · required

API key header of the form X-API-Key: <token>, where <token> is the API key. Requests without a key are limited to 1 RPS. Refer to the authentication guide for details.

Query Parameters

address · string · required

The account address to query. Account address in raw format (e.g., 0:ca6e321c...) or user-friendly format (e.g., EQDKbjIcfM...). All formats are automatically detected.

seqno · integer<int32>

Query state at a specific block height. If omitted, returns the current state. Use this to look up historical data at a specific point in time.

Response

200

application/json

Returns the account lifecycle state: uninit, active, or frozen. Refer to the account lifecycle states documentation for details.

ok · boolean · default: true · required

Returns true if the request succeeded; otherwise false. See the error field for details.

result · enum<string> · required

Response data. Present only when ok is true.

Available options: uninitialized, active, frozen

@extra · string

Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses.