Tonlib type identifiers

Every object returned by API v2 includes a @type field that identifies the object’s structure. These values originate from two sources:

1. Tonlib types such as raw.fullAccountState and tvm.cell come from the tonlib TL schema, the type definition language used by the C++ library powering this API.
2. Extended types, which are prefixed with ext., are added by TON Center to provide parsed representations with additional decoded fields that are not available in the base tonlib schema.

The @type field acts as a discriminator: when a response can return different object shapes, the @type value indicates which fields to expect. This pattern is useful for type-safe deserialization in statically typed languages.

{
  "@type": "raw.fullAccountState",
  "balance": "1000000000",
  "code": "te6cc...",
  "data": "te6cc...",
  "last_transaction_id": {
    "@type": "internal.transactionId",
    "lt": "12345678",
    "hash": "abc..."
  }
}

TL primitive types

The TL schema maps to JSON types as follows:

TL type	JSON type	Notes
int32	number	32-bit signed integer
int53	number	53-bit signed integer; safe for JavaScript Number
int64	string	64-bit signed integer as decimal string; exceeds JS safe range
int256	string	256-bit integer as decimal or hex string
bytes	string	Binary data, base64-encoded
string	string	UTF-8 text
Bool	boolean	true or false
vector<T>	array	Ordered list of elements of type T

Account state

When querying account information, the account_state field uses @type to indicate which kind of contract is deployed. The TL schema defines these as variants of AccountState:

raw.accountState code:bytes data:bytes frozen_hash:bytes = AccountState;
wallet.v3.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.v4.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.highload.v1.accountState wallet_id:int64 seqno:int32 = AccountState;
wallet.highload.v2.accountState wallet_id:int64 = AccountState;
dns.accountState wallet_id:int64 = AccountState;
rwallet.accountState wallet_id:int64 seqno:int32 unlocked_balance:int64 config:rwallet.config = AccountState;
pchan.accountState config:pchan.config state:pchan.State description:string = AccountState;
uninited.accountState frozen_hash:bytes = AccountState;

@type value	API schema	TL fields
raw.accountState	AccountStateRaw	code, data, frozen_hash
wallet.v3.accountState	AccountStateWalletV3	wallet_id, seqno
wallet.v4.accountState	AccountStateWalletV4	wallet_id, seqno
wallet.highload.v1.accountState	AccountStateWalletHighloadV1	wallet_id, seqno
wallet.highload.v2.accountState	AccountStateWalletHighloadV2	wallet_id
dns.accountState	AccountStateDns	wallet_id
rwallet.accountState	AccountStateRWallet	wallet_id, seqno, unlocked_balance, config
pchan.accountState	AccountStatePChan	config, state, description
uninited.accountState	AccountStateUninited	frozen_hash

Account information

Full account queries return one of these top-level types:

raw.fullAccountState balance:int64 extra_currencies:vector<extraCurrency> code:bytes data:bytes
    last_transaction_id:internal.transactionId block_id:ton.blockIdExt frozen_hash:bytes sync_utime:int53
    = raw.FullAccountState;

fullAccountState address:accountAddress balance:int64 extra_currencies:vector<extraCurrency>
    last_transaction_id:internal.transactionId block_id:ton.blockIdExt sync_utime:int53
    account_state:AccountState revision:int32
    = FullAccountState;

@type value	API schema	Description
raw.fullAccountState	AddressInformation	Raw state with balance, code, data, and frozen hash.
fullAccountState	ExtendedAddressInformation	Parsed state with identified contract type.
ext.accounts.walletInformation	WalletInformation	Wallet-specific: type, seqno, wallet_id; TON Center extension.

Address types

accountAddress account_address:string = AccountAddress;

@type value	API schema	TL fields
accountAddress	AccountAddress	account_address
addr_std	SmcAddr	workchain, id

Block identifiers

ton.blockIdExt workchain:int32 shard:int64 seqno:int32 root_hash:bytes file_hash:bytes = ton.BlockIdExt;

@type value	API schema	TL fields
ton.blockIdExt	TonBlockIdExt	workchain, shard, seqno, root_hash, file_hash

Block data

These types are returned by block query endpoints. The TL definitions:

blocks.masterchainInfo last:ton.BlockIdExt state_root_hash:bytes init:ton.BlockIdExt = blocks.MasterchainInfo;
blocks.shards shards:vector<ton.BlockIdExt> = blocks.Shards;
blocks.header id:ton.blockIdExt global_id:int32 version:int32 flags:# after_merge:Bool after_split:Bool
    before_split:Bool want_merge:Bool want_split:Bool validator_list_hash_short:int32 catchain_seqno:int32
    min_ref_mc_seqno:int32 is_key_block:Bool prev_key_block_seqno:int32 start_lt:int64 end_lt:int64
    gen_utime:int53 vert_seqno:# prev_blocks:vector<ton.blockIdExt> = blocks.Header;
blocks.transactions id:ton.blockIdExt req_count:int32 incomplete:Bool
    transactions:vector<blocks.shortTxId> = blocks.Transactions;
blocks.transactionsExt id:ton.blockIdExt req_count:int32 incomplete:Bool
    transactions:vector<raw.transaction> = blocks.TransactionsExt;
blocks.blockSignatures id:ton.blockIdExt signatures:(vector blocks.signature) = blocks.BlockSignatures;
blocks.shardBlockProof from:ton.blockIdExt mc_id:ton.blockIdExt
    links:(vector blocks.shardBlockLink) mc_proof:(vector blocks.blockLinkBack) = blocks.ShardBlockProof;
blocks.outMsgQueueSizes shards:(vector blocks.outMsgQueueSize)
    ext_msg_queue_size_limit:int32 = blocks.OutMsgQueueSizes;

@type value	API schema	Description
blocks.masterchainInfo	MasterchainInfo	Latest and genesis block references.
blocks.shards	Shards	Active shard block identifiers.
blocks.header	BlockHeader	Block metadata, merge or split flags, timing.
blocks.transactions	BlockTransactions	Short transaction IDs within a block.
blocks.transactionsExt	BlockTransactionsExt	Full transactions within a block.
blocks.shortTxId	ShortTxId	Compact reference: account, lt, hash.
blocks.blockSignatures	MasterchainBlockSignatures	Validator signatures for a block.
blocks.signature	BlockSignature	Single validator signature.
blocks.shardBlockProof	ShardBlockProof	Merkle proof chain to masterchain.
blocks.shardBlockLink	ShardBlockLink	Single link in a proof chain.
blocks.blockLinkBack	BlockLinkBack	Backward proof link between blocks.
blocks.outMsgQueueSize	OutMsgQueueSize	Per-shard queue size.
blocks.outMsgQueueSizes	OutMsgQueueSizes	Queue sizes across all shards.
ext.blocks.consensusBlock	ConsensusBlock	Latest finalized block; TON Center extension.

Transactions and messages

raw.transaction address:accountAddress utime:int53 data:bytes transaction_id:internal.transactionId
    fee:int64 storage_fee:int64 other_fee:int64 in_msg:raw.message
    out_msgs:vector<raw.message> = raw.Transaction;
raw.transactions transactions:vector<raw.transaction>
    previous_transaction_id:internal.transactionId = raw.Transactions;
raw.message hash:bytes source:accountAddress destination:accountAddress value:int64
    extra_currencies:vector<extraCurrency> fwd_fee:int64 ihr_fee:int64 created_lt:int64
    body_hash:bytes msg_data:msg.Data = raw.Message;
raw.extMessageInfo hash:bytes hash_norm:bytes = raw.ExtMessageInfo;
internal.transactionId lt:int64 hash:bytes = internal.TransactionId;

@type value	API schema	Description
raw.transaction	TransactionStd	Raw transaction with messages and fees.
raw.transactions	TransactionsStd	Paginated transaction list with cursor.
raw.message	MessageStd	Raw message with sender, recipient, value.
raw.extMessageInfo	ExtMessageInfo	External message hash after broadcast.
internal.transactionId	InternalTransactionId	Transaction reference: lt + hash.
ext.transaction	Transaction	Transaction with decoded comments; TON Center extension.
ext.message	Message	Message with decoded text comments; TON Center extension.

Message body types

The msg_data field on messages uses @type to indicate how to interpret the body:

msg.dataRaw body:bytes init_state:bytes = msg.Data;
msg.dataText text:bytes = msg.Data;
msg.dataDecryptedText text:bytes = msg.Data;
msg.dataEncryptedText text:bytes = msg.Data;

@type value	API schema	Description
msg.dataRaw	MsgDataRaw	Raw binary body + optional init state.
msg.dataText	MsgDataText	Plain text comment; base64-encoded UTF-8.
msg.dataEncryptedText	MsgDataEncryptedText	Encrypted message body.
msg.dataDecryptedText	MsgDataDecryptedText	Decrypted message body.

TVM types

Used as input and output for smart contract get methods: runGetMethod, runGetMethodStd.

Stack entries

Each stack entry wraps a value with a type tag:

tvm.stackEntryNumber number:tvm.Number = tvm.StackEntry;
tvm.stackEntryCell cell:tvm.cell = tvm.StackEntry;
tvm.stackEntrySlice slice:tvm.slice = tvm.StackEntry;
tvm.stackEntryTuple tuple:tvm.Tuple = tvm.StackEntry;
tvm.stackEntryList list:tvm.List = tvm.StackEntry;
tvm.stackEntryUnsupported = tvm.StackEntry;

@type value	API schema	Value field
tvm.stackEntryNumber	TvmStackEntryNumber	number (decimal string via tvm.numberDecimal)
tvm.stackEntryCell	TvmStackEntryCell	cell (base64 BoC via tvm.cell)
tvm.stackEntrySlice	TvmStackEntrySlice	slice (base64 BoC via tvm.slice)
tvm.stackEntryTuple	TvmStackEntryTuple	tuple (nested stack entries)
tvm.stackEntryList	TvmStackEntryList	list (nested stack entries)
tvm.stackEntryUnsupported	TvmStackEntryUnsupported	No value (type not representable)

Value types

tvm.cell bytes:bytes = tvm.Cell;
tvm.slice bytes:bytes = tvm.Slice;
tvm.numberDecimal number:string = tvm.Number;
tvm.tuple elements:vector<tvm.StackEntry> = tvm.Tuple;
tvm.list elements:vector<tvm.StackEntry> = tvm.List;

@type value	API schema	TL fields
tvm.cell	TvmCell	bytes (base64 BoC)
tvm.slice	TvmSlice	bytes (base64 BoC)
tvm.numberDecimal	TvmNumberDecimal	number (decimal string)
tvm.tuple	TvmTuple	elements (stack entries)
tvm.list	TvmList	elements (stack entries)

Get method result

smc.runResult gas_used:int53 stack:vector<tvm.StackEntry> exit_code:int32 = smc.RunResult;

@type value	API schema	TL fields
smc.runResult	RunGetMethodResult	gas_used, stack, exit_code
smc.runResult	RunGetMethodStdResult	Same fields, typed stack entries

Fees

fees in_fwd_fee:int53 storage_fee:int53 gas_fee:int53 fwd_fee:int53 = Fees;
query.fees source_fees:fees destination_fees:vector<fees> = query.Fees;

@type value	API schema	TL fields
fees	Fees	in_fwd_fee, storage_fee, gas_fee, fwd_fee
query.fees	QueryFees	source_fees, destination_fees

Configuration

configInfo config:tvm.cell = ConfigInfo;

@type value	API schema	TL fields
configInfo	ConfigInfo	config TVM cell with parameters

Libraries

smc.libraryEntry hash:int256 data:bytes = smc.LibraryEntry;
smc.libraryResult result:(vector smc.libraryEntry) = smc.LibraryResult;

@type value	API schema	TL fields
smc.libraryEntry	LibraryEntry	hash, data
smc.libraryResult	LibraryResult	result (entries)

Token types (TON Center extensions)

These types are not in the base tonlib TL schema. They are added by TON Center to provide parsed Jetton and NFT data via the getTokenData endpoint.

@type value	API schema	Description
ext.tokens.jettonMasterData	JettonMasterData	Jetton master: total supply, admin, metadata.
ext.tokens.jettonWalletData	JettonWalletData	Jetton wallet: balance, owner, master reference.
ext.tokens.nftCollectionData	NftCollectionData	NFT collection: item count, owner, metadata.
ext.tokens.nftItemData	NftItemData	NFT item: index, owner, collection reference.

DNS record types

DNS entries use @type to indicate the record type stored at a domain:

dns.entryDataNextResolver resolver:AccountAddress = dns.EntryData;
dns.entryDataSmcAddress smc_address:AccountAddress = dns.EntryData;
dns.entryDataAdnlAddress adnl_address:AdnlAddress = dns.EntryData;
dns.entryDataStorageAddress bag_id:int256 = dns.EntryData;

@type value	API schema	TL fields
dns.entryDataNextResolver	DnsRecordNextResolver	resolver (address)
dns.entryDataSmcAddress	DnsRecordSmcAddress	smc_address (address)
dns.entryDataAdnlAddress	DnsRecordAdnlAddress	adnl_address
dns.entryDataStorageAddress	DnsRecordStorageAddress	bag_id (int256)

Payment channel types

pchan.config alice_public_key:string alice_address:accountAddress bob_public_key:string
    bob_address:accountAddress init_timeout:int32 close_timeout:int32 channel_id:int64 = pchan.Config;
pchan.stateInit signed_A:Bool signed_B:Bool min_A:int64 min_B:int64
    expire_at:int53 A:int64 B:int64 = pchan.State;
pchan.stateClose signed_A:Bool signed_B:Bool min_A:int64 min_B:int64
    expire_at:int53 A:int64 B:int64 = pchan.State;
pchan.statePayout A:int64 B:int64 = pchan.State;

@type value	API schema	Description
pchan.config	PChanConfig	Channel parties, timeouts, ID
pchan.stateInit	PChanStateInit	Initialization phase (signing)
pchan.stateClose	PChanStateClose	Closing phase (signing)
pchan.statePayout	PChanStatePayout	Payout phase (final balances)

Restricted wallet types

rwallet.limit seconds:int32 value:int64 = rwallet.Limit;
rwallet.config start_at:int53 limits:vector<rwallet.limit> = rwallet.Config;

@type value	API schema	TL fields
rwallet.config	RWalletConfig	start_at, limits
rwallet.limit	RWalletLimit	seconds, value

Utility types

TON Center extensions.

@type value	API schema	Description
ext.utils.detectedAddress	DetectAddress	Address in all encoding formats
ext.utils.detectedAddressVariant	DetectAddressBase64Variant	Base64 and URL-safe base64 pair
ext.utils.detectedHash	DetectHash	Hash in hex, base64, URL-safe
extraCurrency	ExtraCurrencyBalance	Non-TON currency ID and balance
ok	ResultOk	Success with no return data

Reference

For background on the TL-B format used across the TON ecosystem, see the TL-B overview.

Types prefixed with ext. are TON Center extensions not present in the upstream TL schema.