Skip to main content

​
Overview

Every object returned by API v2 includes an @type field that identifies the object’s structure. These values originate from two sources:
  • TonLib types (e.g. raw.fullAccountState, tvm.cell) come from the TonLib TL schema, the type definition language used by the C++ library powering this API.
  • Extended types (prefixed with ext.) are added by TON Center to provide parsed, developer-friendly representations 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 typeJSON typeNotes
int32number32-bit signed integer
int53number53-bit signed integer (safe for JavaScript Number)
int64string64-bit signed integer as decimal string (exceeds JS safe range)
int256string256-bit integer as decimal or hex string
bytesstringBinary data, base64-encoded
stringstringUTF-8 text
Boolbooleantrue or false
vector<T>arrayOrdered 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 valueAPI schemaTL fields
raw.accountStateAccountStateRawcode, data, frozen_hash
wallet.v3.accountStateAccountStateWalletV3wallet_id, seqno
wallet.v4.accountStateAccountStateWalletV4wallet_id, seqno
wallet.highload.v1.accountStateAccountStateWalletHighloadV1wallet_id, seqno
wallet.highload.v2.accountStateAccountStateWalletHighloadV2wallet_id
dns.accountStateAccountStateDnswallet_id
rwallet.accountStateAccountStateRWalletwallet_id, seqno, unlocked_balance, config
pchan.accountStateAccountStatePChanconfig, state, description
uninited.accountStateAccountStateUninitedfrozen_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 valueAPI schemaDescription
raw.fullAccountStateAddressInformationRaw state with balance, code, data, and frozen hash
fullAccountStateExtendedAddressInformationParsed state with identified contract type
ext.accounts.walletInformationWalletInformationWallet-specific: type, seqno, wallet_id (TON Center extension)

​
Address types

accountAddress account_address:string = AccountAddress;
@type valueAPI schemaTL fields
accountAddressAccountAddressaccount_address
addr_stdSmcAddrworkchain, id

​
Block identifiers

ton.blockIdExt workchain:int32 shard:int64 seqno:int32 root_hash:bytes file_hash:bytes = ton.BlockIdExt;
@type valueAPI schemaTL fields
ton.blockIdExtTonBlockIdExtworkchain, 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 valueAPI schemaDescription
blocks.masterchainInfoMasterchainInfoLatest and genesis block references
blocks.shardsShardsActive shard block identifiers
blocks.headerBlockHeaderBlock metadata, merge/split flags, timing
blocks.transactionsBlockTransactionsShort transaction IDs within a block
blocks.transactionsExtBlockTransactionsExtFull transactions within a block
blocks.shortTxIdShortTxIdCompact reference: account, lt, hash
blocks.blockSignaturesMasterchainBlockSignaturesValidator signatures for a block
blocks.signatureBlockSignatureSingle validator signature
blocks.shardBlockProofShardBlockProofMerkle proof chain to masterchain
blocks.shardBlockLinkShardBlockLinkSingle link in a proof chain
blocks.blockLinkBackBlockLinkBackBackward proof link between blocks
blocks.outMsgQueueSizeOutMsgQueueSizePer-shard queue size
blocks.outMsgQueueSizesOutMsgQueueSizesQueue sizes across all shards
ext.blocks.consensusBlockConsensusBlockLatest 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 valueAPI schemaDescription
raw.transactionTransactionStdRaw transaction with messages and fees
raw.transactionsTransactionsStdPaginated transaction list with cursor
raw.messageMessageStdRaw message with sender, recipient, value
raw.extMessageInfoExtMessageInfoExternal message hash after broadcast
internal.transactionIdInternalTransactionIdTransaction reference: lt + hash
ext.transactionTransactionTransaction with decoded comments (TON Center extension)
ext.messageMessageMessage 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 valueAPI schemaDescription
msg.dataRawMsgDataRawRaw binary body + optional init state
msg.dataTextMsgDataTextPlain text comment (base64-encoded UTF-8)
msg.dataEncryptedTextMsgDataEncryptedTextEncrypted message body
msg.dataDecryptedTextMsgDataDecryptedTextDecrypted 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 valueAPI schemaValue field
tvm.stackEntryNumberTvmStackEntryNumbernumber (decimal string via tvm.numberDecimal)
tvm.stackEntryCellTvmStackEntryCellcell (base64 BoC via tvm.cell)
tvm.stackEntrySliceTvmStackEntrySliceslice (base64 BoC via tvm.slice)
tvm.stackEntryTupleTvmStackEntryTupletuple (nested stack entries)
tvm.stackEntryListTvmStackEntryListlist (nested stack entries)
tvm.stackEntryUnsupportedTvmStackEntryUnsupportedNo 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 valueAPI schemaTL fields
tvm.cellTvmCellbytes (base64 BoC)
tvm.sliceTvmSlicebytes (base64 BoC)
tvm.numberDecimalTvmNumberDecimalnumber (decimal string)
tvm.tupleTvmTupleelements (stack entries)
tvm.listTvmListelements (stack entries)

​
Get method result

smc.runResult gas_used:int53 stack:vector<tvm.StackEntry> exit_code:int32 = smc.RunResult;
@type valueAPI schemaTL fields
smc.runResultRunGetMethodResultgas_used, stack, exit_code
smc.runResultRunGetMethodStdResultSame 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 valueAPI schemaTL fields
feesFeesin_fwd_fee, storage_fee, gas_fee, fwd_fee
query.feesQueryFeessource_fees, destination_fees

​
Configuration

configInfo config:tvm.cell = ConfigInfo;
@type valueAPI schemaTL fields
configInfoConfigInfoconfig (TVM cell with parameters)

​
Libraries

smc.libraryEntry hash:int256 data:bytes = smc.LibraryEntry;
smc.libraryResult result:(vector smc.libraryEntry) = smc.LibraryResult;
@type valueAPI schemaTL fields
smc.libraryEntryLibraryEntryhash, data
smc.libraryResultLibraryResultresult (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 valueAPI schemaDescription
ext.tokens.jettonMasterDataJettonMasterDataJetton master: total supply, admin, metadata
ext.tokens.jettonWalletDataJettonWalletDataJetton wallet: balance, owner, master reference
ext.tokens.nftCollectionDataNftCollectionDataNFT collection: item count, owner, metadata
ext.tokens.nftItemDataNftItemDataNFT 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 valueAPI schemaTL fields
dns_next_resolverDnsRecordNextResolverresolver (address)
dns_smc_addressDnsRecordSmcAddresssmc_address (address)
dns_adnl_addressDnsRecordAdnlAddressadnl_address
dns_storage_addressDnsRecordStorageAddressbag_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 valueAPI schemaDescription
pchan.configPChanConfigChannel parties, timeouts, ID
pchan.stateInitPChanStateInitInitialization phase (signing)
pchan.stateClosePChanStateCloseClosing phase (signing)
pchan.statePayoutPChanStatePayoutPayout 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 valueAPI schemaTL fields
rwallet.configRWalletConfigstart_at, limits
rwallet.limitRWalletLimitseconds, value

​
Utility types

TON Center extensions.
@type valueAPI schemaDescription
ext.utils.detectedAddressDetectAddressAddress in all encoding formats
ext.utils.detectedAddressVariantDetectAddressBase64VariantBase64 and URL-safe base64 pair
ext.utils.detectedHashDetectHashHash in hex, base64, URL-safe
extraCurrencyExtraCurrencyBalanceNon-TON currency ID and balance
okResultOkSuccess 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.