Skip to main content
Subscribe to transactions, blocks, traces, and mempool messages in real time. The SDK provides a unified client with two transports and configurable reconnection policy.
API key is required by the SDK constructor. Get one at tonconsole.com.

​
Architecture

ComponentDescription
TonapiStreamingUnified client — manages session, exposes .sse and .ws transports.
TonapiSSEOne-way stream. HTTP GET, server pushes SSE events.
TonapiWebSocketBidirectional. JSON-RPC 2.0 protocol over WebSocket.

​
Subscriptions

Both transports expose the same four subscription methods with identical signatures:
MethodEvent modelDescription
subscribe_transactions()TransactionEventFinalized account transactions.
subscribe_blocks()BlockEventNew blocks (filterable by workchain).
subscribe_traces()TraceEventCompleted traces for account groups.
subscribe_mempool()MempoolEventPending inbound messages.

​
Endpoints

NetworkURL
Mainnethttps://tonapi.io/v2/sse/...
Testnethttps://testnet.tonapi.io/v2/sse/...

​
Quick Example

import asyncio

from pytonapi.streaming import TonapiStreaming
from pytonapi.types import Network
from pytonapi.exceptions import TONAPIConnectionLostError


async def main() -> None:
    async with TonapiStreaming("YOUR_API_KEY", Network.MAINNET) as streaming:
        try:
            async for event in streaming.sse.subscribe_transactions(
                accounts=["EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"],
            ):
                print(event.tx_hash)
        except TONAPIConnectionLostError as e:
            print(f"Connection lost after {e.attempts} reconnect attempts")


if __name__ == "__main__":
    asyncio.run(main())
Replace streaming.sse with streaming.ws to switch to WebSocket — the API is identical.

​
Event Models

All models are Pydantic BaseModel subclasses. 
from pytonapi.streaming import TransactionEvent, BlockEvent, TraceEvent, MempoolEvent
FieldTypeDescription
account_idstrAccount address.
ltintLogical time.
tx_hashstrTransaction hash.
{
  "account_id": "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b",
  "lt": 49739623000001,
  "tx_hash": "653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
}
FieldTypeDescription
workchainintWorkchain ID.
shardstrShard identifier.
seqnointBlock sequence number.
root_hashstrBlock root hash.
file_hashstrBlock file hash.
{
  "workchain": -1,
  "shard": "8000000000000000",
  "seqno": 42075901,
  "root_hash": "a1b2c3d4e5f6...",
  "file_hash": "f6e5d4c3b2a1..."
}
FieldTypeDescription
accountslist[str]Involved account addresses.
hashstrTrace hash.
{
  "accounts": [
    "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b"
  ],
  "hash": "653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
}
FieldTypeDescription
bocstrBase64-encoded BOC.
involved_accountslist[str] | NoneInvolved account addresses, if available.
{
  "boc": "te6cckEBAQEADgAAGEhlbGxvIFRPTiEN",
  "involved_accounts": [
    "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b"
  ]
}
Streaming events are finalized on-chain. Mempool events (MempoolEvent) represent pending messages — they may or may not result in a transaction.