Subscribe to real-time blockchain events over SSE or WebSocket. Both transports use a decorator-based handler API and multiplex all subscriptions over a single connection.Documentation Index
Fetch the complete documentation index at: https://toncenter.ness.su/llms.txt
Use this file to discover all available pages before exploring further.
API key is required — unauthenticated connections are rejected. Get a key from the @toncenter bot.
| Transport | Description |
|---|---|
ToncenterSSE | One-way stream. Single POST request, server pushes events. |
ToncenterWebSocket | Bidirectional. Dynamic subscribe/unsubscribe after connect. |
Endpoints
- SSE
- WebSocket
| Network | URL |
|---|---|
| Mainnet | https://toncenter.com/api/streaming/v2/sse |
| Testnet | https://testnet.toncenter.com/api/streaming/v2/sse |
Quick Example
Event Models
All models are PydanticBaseModel subclasses from toncenter.streaming.
TransactionsNotification
TransactionsNotification
| Field | Type | Description |
|---|---|---|
type | Literal["transactions"] | Always "transactions". |
finality | str | "pending", "confirmed", "finalized". |
trace_external_hash_norm | str | Links related notifications for a trace. |
transactions | list[dict] | Transaction objects (LT descending). |
address_book | dict | None | Address -> name mapping. |
metadata | dict | None | Token metadata. |
ActionsNotification
ActionsNotification
| Field | Type | Description |
|---|---|---|
type | Literal["actions"] | Always "actions". |
finality | str | "pending", "confirmed", "finalized". |
trace_external_hash_norm | str | Links related notifications for a trace. |
actions | list[dict] | Classified action objects. |
address_book | dict | None | Address -> name mapping. |
metadata | dict | None | Token metadata. |
TraceNotification
TraceNotification
| Field | Type | Description |
|---|---|---|
type | Literal["trace"] | Always "trace". |
finality | str | Finality level. |
trace_external_hash_norm | str | Trace identifier. |
trace | dict | None | Trace tree structure. |
transactions | dict | None | Hash -> transaction object map. |
actions | list[dict] | None | Classified actions for this trace. |
address_book | dict | None | Address -> name mapping. |
metadata | dict | None | Token metadata. |
AccountStateNotification
AccountStateNotification
| Field | Type | Description |
|---|---|---|
type | Literal["account_state_change"] | Always "account_state_change". |
finality | str | "confirmed" or "finalized" only. |
account | str | Address in raw format. |
state | AccountState | None | Account state snapshot. |
AccountState fields: hash, balance, account_status, data_hash, code_hash.JettonsNotification
JettonsNotification
| Field | Type | Description |
|---|---|---|
type | Literal["jettons_change"] | Always "jettons_change". |
finality | str | "confirmed" or "finalized" only. |
jetton | JettonWallet | None | Jetton wallet snapshot. |
address_book | dict | None | Address -> name mapping. |
metadata | dict | None | Token metadata. |
JettonWallet fields: address, balance, owner, jetton, last_transaction_lt.TraceInvalidatedNotification
TraceInvalidatedNotification
| Field | Type | Description |
|---|---|---|
type | Literal["trace_invalidated"] | Always "trace_invalidated". |
trace_external_hash_norm | str | Hash of the invalidated trace. |
trace_external_hash_norm. No invalidation after finalized.No invalidation for
account_state_change or jettons_change. Use Finality.FINALIZED for irreversible balance data.Action Types
All ActionType values (22)
All ActionType values (22)
| Enum member | Wire value |
|---|---|
ActionType.TON_TRANSFER | ton_transfer |
ActionType.JETTON_TRANSFER | jetton_transfer |
ActionType.JETTON_SWAP | jetton_swap |
ActionType.JETTON_BURN | jetton_burn |
ActionType.JETTON_MINT | jetton_mint |
ActionType.NFT_MINT | nft_mint |
ActionType.CALL_CONTRACT | call_contract |
ActionType.CONTRACT_DEPLOY | contract_deploy |
ActionType.STAKE_DEPOSIT | stake_deposit |
ActionType.STAKE_WITHDRAWAL | stake_withdrawal |
ActionType.STAKE_WITHDRAWAL_REQUEST | stake_withdrawal_request |
ActionType.DEX_DEPOSIT_LIQUIDITY | dex_deposit_liquidity |
ActionType.DEX_WITHDRAW_LIQUIDITY | dex_withdraw_liquidity |
ActionType.ELECTION_DEPOSIT | election_deposit |
ActionType.ELECTION_RECOVER | election_recover |
ActionType.AUCTION_BID | auction_bid |
ActionType.CHANGE_DNS | change_dns |
ActionType.DELETE_DNS | delete_dns |
ActionType.RENEW_DNS | renew_dns |
ActionType.TICK_TOCK | tick_tock |
ActionType.SUBSCRIBE | subscribe |
ActionType.UNSUBSCRIBE | unsubscribe |