Streaming API

TonAPI V2 offers real-time updates about events in the blockchain.

Authorization

All methods of the Streaming API are available without a private API key, but TonAPI limits a number of concurrent requests in this case. You should consider getting a personal API key at https://tonconsole.com/ (opens in a new tab). It's crucial for any production usage.

TonAPI looks for an API key in two places in the following order:

In the Authorization header with the "Bearer scheme". For example:

Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

In the "token" parameter of the query string. For example:

https://tonapi.io/v2/sse/accounts/transactions?accounts=ALL&token=eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

Server-Sent Events

SSE methods response with text/event-stream Content-Type and communications happen in a text format. Each API method sends two types of events: heartbeat and message. The "heartbeat" event occurs every 5 seconds when nothing else happens and is a signal that everything is OK with an underlying TCP connection. The "message" event carries important information and its "data" always contains a JSON representation of a message.

A golang example (opens in a new tab) of working with SSE method.

Real-time notifications about new blocks

API method GET https://tonapi.io/v2/sse/blocks?workchain=<...> sends notifications about new blocks in the given workchain. The workchain parameter is optional and TonAPI will stream blocks from all workchains if it's not provided.

A response example:

event: message
id: 1702660194645470966
data: {"workchain":0,"shard":"8000000000000000","seqno":40695756,"root_hash":"4506cf117b96acf84717ec4b57d5d46011e94d5722681c3e4ecc8eb54932e7f8","file_hash":"97d993d43df9da463b349a6008baf3b7df229686489150a770a9fd1ffcb2d3f5"}

Real-time notifications about finalized transactions

API method GET https://tonapi.io/v2/sse/accounts/transactions?accounts=<list-of-accounts>&operations=<list-of-operations> takes in a list of account IDs and an optional list of operations.

Query parameter Description

accounts A comma-separated list of account IDs. A special value of "accounts" is ALL. TonAPI will stream transactions for all accounts in this case.

operations A comma-separated list of operations, which makes it possible to get transactions based on the first 4 bytes of a message body of an inbound message (opens in a new tab).

Each operation is a string containing either one of the supported names or a hex string representing a message operation opcode which is an unsigned 32-bit integer.

A hex string must start with "0x" prefix and have exactly 8 hex digits.
An example of "operations" is &operations=JettonTransfer,0x0524c7ae,StonfiSwap.

The advantage of using hex strings is that it's possible to get transactions for operations that are not yet present on the list.

Query parameter	Description
accounts	A comma-separated list of account IDs. A special value of "accounts" is ALL. TonAPI will stream transactions for all accounts in this case.
operations	A comma-separated list of operations, which makes it possible to get transactions based on the first 4 bytes of a message body of an inbound message (opens in a new tab). Each operation is a string containing either one of the supported names or a hex string representing a message operation opcode which is an unsigned 32-bit integer. A hex string must start with "0x" prefix and have exactly 8 hex digits. An example of "operations" is `&operations=JettonTransfer,0x0524c7ae,StonfiSwap`. The advantage of using hex strings is that it's possible to get transactions for operations that are not yet present on the list.

Then it starts streaming finalized transactions that belong to the given list of accounts.

A response example:

event: heartbeat

event: message
id: 1682407879253338019
data: {"account_id":"-1:5555555555555555555555555555555555555555555555555555555555555555","lt":37121532000003,"tx_hash":"076a457ace46c6bcea6ef0644d65a4b866d25a5fd52349f08a6ccfbf7cb99ddb"}

Real-time notifications about traces

A trace in the TON blockchain is a series of transactions caused by one inbound message. It usually consists of multiple transactions on different accounts. Once a trace completes, TonAPI sends the trace's hash and a list of involved accounts to all subscribers who are interested in any of these accounts.

API method GET https://tonapi.io/v2/sse/accounts/traces?accounts=<comma-separated-list-of-accounts> takes in a comma-separated list of account IDs as "accounts" query parameter. A special value of "accounts" is ALL. TonAPI will stream all traces in this case.

A response example:

event: heartbeat

event: message
id: 1682407879253338019
data: {"accounts":["0:67a8fc0aea189d79e26f50fa9184842a1ab4f19951286d498ea5a106af375044","0:dd61300e0060f80233363b3b4a0f3b27ad03b19cc4bec6ec798aab0b3e479eba","0:d7907ea9bb1fa580aa82489680004e75fbf2842246219e7dac1cf9ea90fb5cf9","0:8c61ced898b13b6aca6f4cada44080e22aacc49680082cb51c66901cdae57451"],"hash":"6176c9b1690a7b6beebd09ff118761ee47f1a8be716506874ed0a1c06bb0fc83"}

Real-time notifications about pending messages (Mempool).

API method GET 'https://tonapi.io/v2/sse/mempool (opens in a new tab)' immediately starts streaming BOCs of pending inbound messages:

event: heartbeat

event: message
id: 1682342934235516717
data: {"boc":"te6cc..."}

"boc" parameter is a serialized instance of a tlb.Message (opens in a new tab).

Subscribe to a list of accounts

Because a flow of pending messages could be quite high, TonAPI has a way to provide a list of accounts that you are interested in by using "accounts" query parameter:

GET 'https://tonapi.io/v2/sse/mempool?accounts=comma-separated-list-of-accounts (opens in a new tab)'.

In this case, TonAPI emulates a message to get a list of involved accounts. If any of them is on the list you provided, TonAPI will send a message to you along with a full list of accounts involved in this trace.

event: message
id: 1682407879253338019
data: {"boc":"...","involved_accounts":["0:67a8fc0aea189d79e26f50fa9184842a1ab4f19951286d498ea5a106af375044","0:6ccd325a858c379693fae2bcaab1c2906831a4e10a6c3bb44ee8b615bca1d220"]}

Websocket

TonAPI supports a JSON-RPC protocol over a websocket connection. It is available at wss://tonapi.io/v2/websocket. Supported methods are:

subscribe_block
subscribe_account
subscribe_trace
subscribe_mempool

A golang example (opens in a new tab) of working with websocket.

"subscribe_block" method

subscribe_block starts streaming new blocks. It is possible to specify a workchain by using "params" argument to limit the stream to a specific workchain.

A request example:

 {
   "id": 1,
   "jsonrpc": "2.0",
   "method": "subscribe_block",
   "params": [
     "workchain=-1"
   ]
 }

A response:

{
   "id": 1,
   "jsonrpc": "2.0",
   "method": "subscribe_block",
   "result": "success! you have subscribed to blocks"
 }

A notification about a new block looks as follows:

{
   "jsonrpc": "2.0",
   "method": "block",
   "params": {
     "workchain": -1,
     "shard": "8000000000000000",
     "seqno": 34832412,
     "root_hash": "2a6595467ba53f63b1b3528762e0ccf396a135348519a1d08d4d5d9efa9f0521",
     "file_hash": "e6a4f3283fd27531fbda844ec480aa23b12e3ee38e21bc5856dee2a1d4f5328a"
   }
 }

"subscribe_account" method

subscribe_account takes in a list of string items as "params" argument and starts streaming finalized transactions.

Each string item has one of the following formats:

accountID - a string representing an account ID. In this case, TonAPI will stream all transactions that belong to the given account.
accountID;operations=operation1,operation2,...,operationN - a string representing an account ID and a list of operations. In this case, TonAPI will stream transactions that belong to the given account and have one of the given operations.

An operation is the first 4 bytes of a message body of an inbound message (opens in a new tab).

An example of "operations" is operations=JettonTransfer,0x0524c7ae,StonfiSwap. It is a comma-separated list. Each item is an operation name or a hex string representing a message operation opcode which is an unsigned 32-bit integer. A hex string must start with "0x" prefix and have exactly 8 hex digits. The advantage of using hex strings is that it's possible to get transactions for operations that are not yet present on the list.

A request example:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_account",
  "params":[
    "-1:5555555555555555555555555555555555555555555555555555555555555555",
    "-1:3333333333333333333333333333333333333333333333333333333333333333;operations=JettonTransfer,0x0524c7ae"
  ]
}

A response:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_account",
  "result":"success! 2 new subscriptions created"
}

When a transaction is committed to the blockchain, TonAPI will send a short summary about it:

 {
  "jsonrpc":"2.0",
  "method":"account_transaction",
  "params":{
    "account_id":"-1:5555555555555555555555555555555555555555555555555555555555555555",
    "lt":37121758000003,
    "tx_hash":"586e176bdead2a37d9e372c3725e27c4eab90f5b213c6099c6aadeafc8e4fbc9"
  }
}

It is possible to subscribe up to 1000 accounts per a websocket connection.

"subscribe_trace" method

subscribe_trace takes in a list of account IDs as "params" argument and starts streaming traces that involve any of the given list of accounts. A request example:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_trace",
  "params":[
    "-1:5555555555555555555555555555555555555555555555555555555555555555",
    "-1:3333333333333333333333333333333333333333333333333333333333333333"
  ]
}

A response:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_trace",
  "result":"success! 2 new subscriptions created"
}

When a trace completes, TonAPI will send a short summary about it:

 {
  "jsonrpc":"2.0",
  "method":"trace",
  "params":{
      "accounts":[
          "0:67a8fc0aea189d79e26f50fa9184842a1ab4f19951286d498ea5a106af375044",
          "0:dd61300e0060f80233363b3b4a0f3b27ad03b19cc4bec6ec798aab0b3e479eba",
          "0:d7907ea9bb1fa580aa82489680004e75fbf2842246219e7dac1cf9ea90fb5cf9",
          "0:8c61ced898b13b6aca6f4cada44080e22aacc49680082cb51c66901cdae57451"
      ],
      "hash":"6176c9b1690a7b6beebd09ff118761ee47f1a8be716506874ed0a1c06bb0fc83"
  }
}

It is possible to subscribe up to 1000 accounts per a websocket connection.

"subscribe_mempool" method

subscribe_mempool subscribes you to notifications about pending inbound messages. A request example:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_mempool"
}

A response:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_mempool",
  "result":"success! you have subscribed to mempool"
}

An example of a new-pending-message event:

{
  "jsonrpc":"2.0",
  "method":"mempool_message",
  "params":{
    "boc":"te6ccgEBBAEAtwABRYgBvVXMoxQj+kmDtTinWnFdumvpTNo33p48YQKOWyTtUkAMAQGcMZ6id5dkoDZImQ4UC5SqZSN04h/xNpKaEsESJQivKW01aMcWW4qeUUjKm/iZ2nszwBj3uFVcsIr9xFomQvY3DCmpoxdkQjldAAAAcAADAgFkQgAoPvU+sDeRbPQrPGn3bxzd8JnUNGlQcfA/qoFluFxSiRE4gAAAAAAAAAAAAAAAAAEDABIAAAAAaGVsbG8="
  }
}

"boc" parameter is a serialized instance of a tlb.Message (opens in a new tab).

Subscribe to a list of accounts

Because a flow of pending messages could be quite high, TonAPI has a way to provide a list of accounts that you are interested in by using "accounts" as a parameter:

{
  "id":1,
  "jsonrpc":"2.0",
  "method":"subscribe_mempool",
  "params": ["accounts=comma-separated-list-of-accounts"]
}

Please notice that the "params" argument is an array of strings.

{
  "jsonrpc":"2.0",
  "method":"mempool_message",
  "params":{
    "boc":"...",
    "involved_accounts":["0:67a8fc0aea189d79e26f50fa9184842a1ab4f19951286d498ea5a106af375044","0:6ccd325a858c379693fae2bcaab1c2906831a4e10a6c3bb44ee8b615bca1d220"]
  }
}

API v2 SDK