TON Api
Streaming API

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
  1. 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 transactions

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

A response example:

event: heartbeat

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

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":"te6ccgEBBAEAtwABRYgBvVXMoxQj+kmDtTinWnFdumvpTNo33p48YQKOWyTtUkAMAQGcMZ6id5dkoDZImQ4UC5SqZSN04h/xNpKaEsESJQivKW01aMcWW4qeUUjKm/iZ2nszwBj3uFVcsIr9xFomQvY3DCmpoxdkQjldAAAAcAADAgFkQgAoPvU+sDeRbPQrPGn3bxzd8JnUNGlQcfA/qoFluFxSiRE4gAAAAAAAAAAAAAAAAAEDABIAAAAAaGVsbG8="}

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

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_mempool

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

"subscribe_account" method

subscribe_account takes in a list of account IDs as "params" argument and starts streaming transactions that belong to the given list of accounts. A request example:

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

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_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).

API v2Tonkeeper Messages