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:

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

Bearer eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9

2. 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 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.

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_account
• subscribe_trace
• subscribe_mempool

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

"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:

1. accountID - a string representing an account ID. In this case, TonAPI will stream all transactions that belong to the given account.
2. 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"
}

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.

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