Get address information

Returns the current state of any account on the TON blockchain. Includes the balance (in nanotons), smart contract code and data (if deployed), account status, and a reference to the last transaction. This is the primary endpoint for checking if an address exists and what’s deployed there.

GET /api/v2/getAddressInformation

Try it

Get address information

cURL

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

200

{
  "ok": true,
  "result": {
    "@type": "raw.fullAccountState",
    "balance": "<string>",
    "extra_currencies": [
      {
        "@type": "extraCurrency",
        "id": 123,
        "amount": "<string>"
      }
    ],
    "last_transaction_id": {
      "@type": "internal.transactionId",
      "lt": "<string>",
      "hash": "<string>"
    },
    "block_id": {
      "@type": "ton.blockIdExt",
      "workchain": 123,
      "shard": "<string>",
      "seqno": 123,
      "root_hash": "<string>",
      "file_hash": "<string>"
    },
    "code": "<string>",
    "data": "<string>",
    "frozen_hash": "<string>",
    "sync_utime": 123,
    "state": "uninitialized",
    "suspended": true
  },
  "@extra": "<string>"
}

Authorizations

X-API-Key · string · header · required

Query Parameters

address · string · required

The account address to query. You can use any format: raw (0:abcd), base64 (EQ), or base64url (UQ). The API automatically detects and converts the format. A TON account address. Accepts raw format (workchain:hex like 0:abc...), base64 bounceable (EQ...), base64 non-bounceable (UQ...), or base64url. 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

OK

Response containing account state, balance, code, and data.

ok · boolean · default: true · required

Indicates if the request succeeded. If false, check the error field for details.

result · object · required

The response data. Only present when ok is true.

Show child attributes

result. @type · enum<string> · default: raw.fullAccountState · required

Object type identifier.

Available options: raw.fullAccountState

result. balance · string · required

The account or token balance in the smallest unit (nanotons for TON, or base units for tokens). Divide by 10^decimals to get the human-readable amount.

result. extra_currencies · object[] · required

Non-TON currencies transferred. TON supports multiple native currencies.

Show child attributes

result.extra_currencies. @type · enum<string> · default: extraCurrency · required

Object type identifier.

Available options: extraCurrency

result.extra_currencies. id · integer<int32> · required

Request ID. Pass any string and it will be echoed in the response.

result.extra_currencies. amount · string · required

Balance amount as string.

result. last_transaction_id · object · required

Reference to the most recent transaction. Use as starting point for getTransactions.

Show child attributes

result.last_transaction_id. @type · enum<string> · default: internal.transactionId · required

Object type identifier.

Available options: internal.transactionId

result.last_transaction_id. lt · string · required

Logical time of this event. A globally unique counter that orders all blockchain events. Higher values are more recent.

result.last_transaction_id. hash · string · required

Unique identifier hash for this object.

result. block_id · object · required

Full block identifier where this event occurred.

Show child attributes

result.block_id. @type · enum<string> · default: ton.blockIdExt · required

Object type identifier.

Available options: ton.blockIdExt

result.block_id. workchain · integer · required

Workchain ID: -1 for masterchain, 0 for basechain. Most user transactions are on workchain 0.

result.block_id. shard · string · required

Shard identifier. A signed 64-bit integer. Masterchain uses -9223372036854775808.

result.block_id. seqno · integer · required

Block or wallet sequence number. For blocks, this is the block height. For wallets, increment this for each outgoing transaction.

result.block_id. root_hash · string · required

Merkle root hash of the block state tree. Used for cryptographic verification.

result.block_id. file_hash · string · required

Hash of the serialized block data. Together with root_hash, uniquely identifies a block.

result. code · string · required

Smart contract code in BOC format, base64 encoded.

result. data · string · required

Raw transaction or contract data in BOC (Bag of Cells) format, base64 encoded.

result. frozen_hash · string · required

Hash of the frozen contract state. Only present for frozen accounts.

result. sync_utime · integer<int64> · required

Unix timestamp when this data was synced.

result. state · enum<string> · required

Account state: uninit, active, or frozen.

Available options: uninitialized, active, frozen

result. suspended · boolean

True if the account is suspended.

@extra · string

Optional request ID that you can pass in the request and receive back in the response. Useful for matching async responses.