📖 WebSocket API документация

• Конечная точка для подключения: wss://mainnet.tonstream.io/ws/v1/
• Коммуникация происходит по протоколу JSON-RPC
• Рекомендуется использование WebSocket расширения permessage-deflate для минимизации трафика.

Авторизация

Все методы стриминга (временно) доступны без API ключа. Вы можете получить ключ Telegram боте @tonstreamapibot

Указывать API ключ нужно в GET параметре api_key при подключении, например:

wss://mainnet.tonstream.io/ws/v1/?api_key=zZGnfDrkbRRsfkcluHvA5F6VhUC_jOoZe29VmHNnIesdYWN7VEkyBQb_-E5HbmVe

Подписка на блоки

В этой подписке передаются новые блоки из воркчейнов -1 и 0 упорядоченно по возрастанию seqno. Вы можете настроить получение данных только из определенного воркчейна и выбрать, какие именно данные блока получать.

Параметры подписки

Поле	Тип	Обязательное	Описание
subscription	string	Да	Имя подписки. По умолчанию всегда block.
workchains	int[]	Нет	Список воркчейнов.
include_block_header	bool	Нет	Включать ли заголовок блока в уведомления.
include_transactions	bool	Нет	Включать ли транзакции блока в уведомления.
include_account_states	bool	Нет	Включать ли состояния аккаунтов блока в уведомления.

Создание подписки

Подписка на все воркчейны

Для подписки на все воркчейны укажите null в параметре workchains, передайте список [0, -1] или вовсе опустите этот параметр:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "subscription": "block"
    },
    "id": 1
}

Подписка на конкретный воркчейн

Чтобы подписаться на определенный воркчейн, укажите его номер в параметре workchains:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "subscription": "block",
        "workchains": [0]
    },
    "id": 1
}

Настройка получаемых данных

Чтобы получать только определенные данные блока, установите true для нужного параметра include_*:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "subscription": "block",
        "workchains": [0],
        "include_block_header": false,
        "include_transactions": true
    },
    "id": 1
}

Ответ сервера

В ответ вы получите сообщение с текущими параметрами подписки:

{
    "jsonrpc": "2.0",
    "result": {
        "subscription": "block",
        "workchains": [0, -1],
        "include_block_header": false,
        "include_transactions": true,
        "include_account_states": false
    },
    "id": 1
}

Структура уведомления

Когда новый блок будет сформирован, вы получите уведомление:

{
    "jsonrpc": "2.0",
    "method": "block",
    "params": {
        "id": {
            "@type": "tonNode.blockIdExt",
            "workchain": 0,
            "shard": "-9223372036854775808",
            "seqno": 1234567890,
            "root_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
            "file_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
        },
        "header": {
            /* TL-B схема 'BlockInfo' в 'block.tlb' */
        },
        "transactions": {
            "0000000000000000000000000000000000000000000000000000000000000000": {
                /* TL-B схема 'Transaction' в 'block.tlb' */
            }
        },
        "account_states": {
            "0000000000000000000000000000000000000000000000000000000000000000": {
                /* TL-Bschema 'ShardAccount' in 'block.tlb' */
            }
        }
    }
}

Поле	Тип	Обязательное	Описание
id	object	Да	Расширенный идентификатор блока. TL-схема tonNode.blockIdExt.
header	object	Нет	Заголовок блока. TL-B схема BlockInfo. Поле присутствует, если include_block_header установлен в true.
transactions	object	Нет	Список обработанных транзакций в блоке. Ключ - хэш транзакции, значение - TL-B схема Transaction. Поле присутствует, если include_transactions установлен true.
account_states	object	Нет	Список измененных состояний аккаунтов. Ключ - хэш аккаунта (часть адреса аккаунта), значение - TL-B схема ShardAccount. Поле присутствует, если include_account_states установлен true.

Управление подпиской

Добавление параметров

Допустим, у вас есть подписка на воркчейн -1 с параметром include_transactions. Чтобы добавить еще один воркчейн, укажите его в параметре workchains:

{
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "subscription": "block",
        "workchains": [0]
    },
    "id": 1
}

Удаление параметров

Допустим, у вас есть подписка на все воркчейны с параметрами include_transactions и include_account_states. Чтобы убрать из подписки один воркчейн:

{
    "jsonrpc": "2.0",
    "method": "unsubscribe",
    "params": {
        "subscription": "block",
        "workchains": [0]
    },
    "id": 1
}

Полное удаление подписки

Чтобы полностью удалить подписку, укажите в параметре workchains значение null или все воркчейны:

{
    "jsonrpc": "2.0",
    "method": "unsubscribe",
    "params": {
        "subscription": "block"
    },
    "id": 1
}