Skip to main content

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.

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.
API key is required — unauthenticated connections are rejected. Get a key from the @toncenter bot.
TransportDescription
ToncenterSSEOne-way stream. Single POST request, server pushes events.
ToncenterWebSocketBidirectional. Dynamic subscribe/unsubscribe after connect.

Endpoints

NetworkURL
Mainnethttps://toncenter.com/api/streaming/v2/sse
Testnethttps://testnet.toncenter.com/api/streaming/v2/sse

Quick Example

import asyncio

from toncenter.types import Network
from toncenter.streaming import Finality, ToncenterSSE, TransactionsNotification
from toncenter.exceptions import ToncenterConnectionLostError

sse = ToncenterSSE("YOUR_API_KEY", Network.MAINNET)


@sse.on_transactions(min_finality=Finality.FINALIZED)
async def on_tx(n: TransactionsNotification) -> None:
    for tx in n.transactions:
        print(tx.get("hash"))


async def main() -> None:
    try:
        await sse.start(addresses=["EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"])
    except ToncenterConnectionLostError as e:
        print(f"Connection lost after {e.attempts} reconnect attempts")
    finally:
        await sse.stop()


if __name__ == "__main__":
    asyncio.run(main())

Event Models

All models are Pydantic BaseModel subclasses from toncenter.streaming.
FieldTypeDescription
typeLiteral["transactions"]Always "transactions".
finalitystr"pending", "confirmed", "finalized".
trace_external_hash_normstrLinks related notifications for a trace.
transactionslist[dict]Transaction objects (LT descending).
address_bookdict | NoneAddress -> name mapping.
metadatadict | NoneToken metadata.
FieldTypeDescription
typeLiteral["actions"]Always "actions".
finalitystr"pending", "confirmed", "finalized".
trace_external_hash_normstrLinks related notifications for a trace.
actionslist[dict]Classified action objects.
address_bookdict | NoneAddress -> name mapping.
metadatadict | NoneToken metadata.
FieldTypeDescription
typeLiteral["trace"]Always "trace".
finalitystrFinality level.
trace_external_hash_normstrTrace identifier.
tracedict | NoneTrace tree structure.
transactionsdict | NoneHash -> transaction object map.
actionslist[dict] | NoneClassified actions for this trace.
address_bookdict | NoneAddress -> name mapping.
metadatadict | NoneToken metadata.
FieldTypeDescription
typeLiteral["account_state_change"]Always "account_state_change".
finalitystr"confirmed" or "finalized" only.
accountstrAddress in raw format.
stateAccountState | NoneAccount state snapshot.
AccountState fields: hash, balance, account_status, data_hash, code_hash.
FieldTypeDescription
typeLiteral["jettons_change"]Always "jettons_change".
finalitystr"confirmed" or "finalized" only.
jettonJettonWallet | NoneJetton wallet snapshot.
address_bookdict | NoneAddress -> name mapping.
metadatadict | NoneToken metadata.
JettonWallet fields: address, balance, owner, jetton, last_transaction_lt.
FieldTypeDescription
typeLiteral["trace_invalidated"]Always "trace_invalidated".
trace_external_hash_normstrHash of the invalidated trace.
Fires when a previously delivered pending or confirmed trace becomes invalid. Discard cached data for that 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

Enum memberWire value
ActionType.TON_TRANSFERton_transfer
ActionType.JETTON_TRANSFERjetton_transfer
ActionType.JETTON_SWAPjetton_swap
ActionType.JETTON_BURNjetton_burn
ActionType.JETTON_MINTjetton_mint
ActionType.NFT_MINTnft_mint
ActionType.CALL_CONTRACTcall_contract
ActionType.CONTRACT_DEPLOYcontract_deploy
ActionType.STAKE_DEPOSITstake_deposit
ActionType.STAKE_WITHDRAWALstake_withdrawal
ActionType.STAKE_WITHDRAWAL_REQUESTstake_withdrawal_request
ActionType.DEX_DEPOSIT_LIQUIDITYdex_deposit_liquidity
ActionType.DEX_WITHDRAW_LIQUIDITYdex_withdraw_liquidity
ActionType.ELECTION_DEPOSITelection_deposit
ActionType.ELECTION_RECOVERelection_recover
ActionType.AUCTION_BIDauction_bid
ActionType.CHANGE_DNSchange_dns
ActionType.DELETE_DNSdelete_dns
ActionType.RENEW_DNSrenew_dns
ActionType.TICK_TOCKtick_tock
ActionType.SUBSCRIBEsubscribe
ActionType.UNSUBSCRIBEunsubscribe
For the raw wire protocol, see the Streaming API v2 specification.