Skip to main content

​
Event types

Once a subscription is established, the server sends event messages (notifications) matching the selected types and min_finality. Each message is a JSON object representing a single event. The type field in each notification identifies the notification schema:
  • "transactions" — subscribe to transactions and their finality levels.
  • "actions" — subscribe to certain actions by setting action_types.
  • "trace" — subscribe to a transaction trace.
  • "account_state_change" — emitted for each matching confirmed or finalized account transaction.
  • "jettons_change" — emitted for each matching confirmed or finalized jetton wallet transaction.
  • "trace_invalidated" — emitted when earlier trace data becomes invalid.

​
Notification schemas

Trace-related notifications, such as "transactions", "actions", and "trace" are grouped by the trace. They use the same trace_external_hash_norm value across all events generated from one external message. Transactions and actions in the same trace are ordered by logical time (LT) in descending order. The "trace" event includes the full trace tree and a map of all transactions in that trace.

​
"transactions"

Subscriptions that include "transactions" can receive multiple notifications for the same trace as finality increases. Trace is determined by its trace_external_hash_norm.
FieldTypeDescription
typestringAlways "transactions".
finalitystring"pending", "confirmed", or "finalized".
trace_external_hash_normstringNormalized external message hash for the trace.
transactionsTransaction[]Transactions in the trace, ordered by descending logical time.
address_bookobjectOptional mapping of addresses to a friendly format and a TON DNS domain.
metadataobjectOptional mapping of token addresses to metadata (jetton or NFT).
Notification example
{
  "type": "transactions",
  "finality": "pending",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "transactions": [ /* transaction objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}

​
"actions"

Subscriptions that include "actions" can receive multiple notifications for the same trace as finality increases. Trace is determined by its trace_external_hash_norm.
FieldTypeDescription
typestringAlways "actions".
finalitystring"pending", "confirmed", or "finalized".
trace_external_hash_normstringNormalized external message hash for the trace.
actionsAction[]Classified actions for the trace.
address_bookobjectOptional mapping of addresses to a friendly format and a TON DNS domain.
metadataobjectOptional mapping of token addresses to metadata (jetton or NFT).
Notification example
{
  "type": "actions",
  "finality": "confirmed",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "actions": [ /* action objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}

​
"trace"

Subscriptions that include "trace" receive trace-wide payloads. These payloads are not filtered by account address and include all transactions and actions in the trace. Trace is determined by its trace_external_hash_norm.
FieldTypeDescription
typestringAlways "trace".
finalitystring"pending", "confirmed", or "finalized".
trace_external_hash_normstringNormalized external message hash for the trace.
traceTraceNodeTrace tree.
transactionsobjectMap of transaction hash to transaction object.
actionsAction[]Optional classified actions for the trace.
address_bookobjectOptional mapping of addresses to a friendly format and a TON DNS domain.
metadataobjectOptional mapping of token addresses to metadata (jetton or NFT).
Notification example
{
  "type": "trace",
  "finality": "confirmed",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH",
  "trace": {},
  "transactions": { /* mappings */ },
  "actions": [ /* action objects */ ],
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}

​
"account_state_change"

Subscriptions that include "account_state_change" receive notifications for each transaction executed on a subscribed account address. This event is emitted only for "confirmed" and "finalized" finality levels.
FieldTypeDescription
typestringAlways "account_state_change".
finalitystring"confirmed" or "finalized".
accountstringAccount address in raw format, e.g., 0:abc...RAW_ADDRESS.
stateAccountStateAccount state without full code and data BoCs. Includes state hash, nanoToncoin balance, account status, data and code hashes. All hashes are given in the Base64 format.
Notification example
{
  "type": "account_state_change",
  "finality": "finalized",
  "account": "0:18AA...RAW_ADDRESS",
  "state": {
    "hash": "P0Gc...BASE64_HASH",
    "balance": "42...NANOTON_BALANCE",
    "account_status": "active",
    "data_hash": "7qNe...BASE64_HASH",
    "code_hash": "ow8E...BASE64_HASH"
  }
}

​
"jettons_change"

Subscriptions that include "jettons_change" receive notifications for each transaction on a jetton wallet contract when the subscribed address is its own address or its owner’s TON wallet address. This event is emitted only for "confirmed" and "finalized" finality levels.
FieldTypeDescription
typestringAlways "jettons_change".
finalitystring"confirmed" or "finalized".
jettonJettonWalletJetton wallet data. Includes its raw address, jetton balance, owner’s raw address, jetton master (minter) raw address, and logical time of its last transaction.
address_bookobjectOptional mapping of addresses to a friendly format and a TON DNS domain.
metadataobjectOptional mapping of token addresses to metadata (jetton or NFT).
Notification example
{
  "type": "jettons_change",
  "finality": "finalized",
  "jetton": {
    "address": "0:88DA...RAW_ADDRESS",
    "balance": "42...JETTON_BALANCE",
    "owner": "0:18AA...RAW_ADDRESS",
    "jetton": "0:B113...RAW_ADDRESS",
    "last_transaction_lt": "61664...LT_UNIX_TIME",
  },
  "address_book": { /* mapping of known addresses */ },
  "metadata": { /* mapping of known token addresses to metadata */ }
}

​
"trace_invalidated"

The "trace_invalidated" notification signals that previously emitted speculative or intermediate trace data is no longer valid. Typical causes include:
  • external message was not accepted by the blockchain;
  • later state change invalidated previous emulation result;
  • confirmed shard block was replaced by another block, and the trace did not end up in the finalized block.
Trace in the notification is determined by its trace_external_hash_norm.
FieldTypeDescription
typestringAlways "trace_invalidated".
trace_external_hash_normstringNormalized external message hash for the invalidated trace.
Notification example
{
  "type": "trace_invalidated",
  "trace_external_hash_norm": "E7...NORMALIZED_EXTERNAL_MSG_HASH"
}
Upon receiving this notification, remove any stored "trace", "transactions", and "actions" data for the affected trace_external_hash_norm. The "trace_invalidated" notification cannot be sent for the "finalized" finality level of the trace.

​
Delivery semantics

TypeFinality valuesDelivery behavior
transactions"pending", "confirmed", "finalized"Emitted per trace as finality increases.
actions"pending", "confirmed", "finalized"Emitted per trace as action classification and finality progress.
trace"pending", "confirmed", "finalized"Emitted per trace with the full trace payload.
account_state_change"confirmed", "finalized"Emitted for each matching confirmed or finalized account transaction.
jettons_change"confirmed", "finalized"Emitted for each matching confirmed or finalized jetton wallet transaction.
trace_invalidatedNot applicableEmitted when earlier trace-based data becomes invalid.

​
min_finality behavior

For trace-based events:
  • min_finality = "pending" returns "pending", "confirmed", and "finalized" snapshots.
  • min_finality = "confirmed" skips pure emulation and starts at "confirmed" or later.
  • min_finality = "finalized" returns only finalized trace-based events.
For non-trace events:
  • "account_state_change" and "jettons_change" are emitted only with "confirmed" and "finalized" finality levels.

​
Event invalidation

Subscriptions that allow speculative states can later receive "trace_invalidated". If the finality level reaches "finalized", the server is guaranteed not to emit "trace_invalidated" for the trace.

​
See also