Архитектура API Tonhub
Основные группы API
Backend API Tonhub делятся на 8 основных функциональных групп:- Основные данные TON и Solana: история транзакций, статусы операций, сетевые и кошельковые настройки, информация о контрактах. Сюда же входит TON RPC, то есть
mainnet-v4и testnet-v4.tonhubapi.com, для чтения состояния блокчейна. Эти API обеспечивают отображение балансов, историю операций и расчет комиссий. - Информация об активах: данные о токенах, включая hints, полную информацию, metadata, rates и транзакции кошелька, а также цены и курсы через
v2/price,v2/rates,token/info. Это все, что нужно для списков активов, их фиатной оценки и выбора токенов при переводах. - Стейкинг: информация об участии в пулах, включая
member/info,member/liquid/info, параметры ликвидного пула и данные по USDe, такие как курс, APY и состояние участника. Дополнительно используется отдельный сервис staking-indexer.whales-api.com для статуса выборов, номинаторов и APY пулов. - Gasless-переводы: настройки, включая список поддерживаемых токенов и relayer, расчет комиссий в токенах и отправка подписанных транзакций через relayer. Работает только для поддерживаемых токенов и кошельков W5.
- TON Connect и взаимодействие с кошельком: bridge TON Connect, то есть
/tonconnect, команды подключенияconnect/command,grant,revoke,answer, а также управление wallet-request, включая create, respond и list. Эта группа обеспечивает связь dApp с кошельком и обработку входящих запросов на подпись и перевод. - Настройки приложения и каталоги: конфигурация приложения, версии, metadata и каталог приложений, отзывы и жалобы, баннеры, включая tonhub, Holders и рекламные, а также список разрешенных доменов через protect. Эти API определяют доступные функции, показываемые приложения и содержимое браузера.
- Обмен валют: интеграция Changelly — валюты, оценка курса, создание обменной операции и отслеживание ее статуса. Это отдельная функция внутри приложения.
- Интеграция с Holders: карты, профиль, аккаунты, OTP на отдельном хосте card-prod.whales-api.com и staging-хосте. Это специальные API продукта Holders, не относящиеся к основному backend connect.tonhubapi.com.
storage/read и storage/write для синхронизации настроек, push-уведомления register, отчеты об ошибках client-error/report, проверку адресов service-address, конфигурацию по адресу и старые балансы balances/old. Эти API предназначены для внутренней работы приложения, а не для внешних интеграций.
Публичные и внутренние API
Публичные API для внешних разработчиков:- TON Connect: bridge, то есть
/tonconnect, и протокол подключения для обмена сообщениями с кошельком. Спецификация TON Connect и manifest приложения являются публичными — dApp подключаются к кошельку именно через этот интерфейс. - Публично документированные endpoint-ы Tonhub, если они официально объявлены в документации для разработчиков dApp или партнеров.
v1/v2/v3, hints, токены, Solana, включая account, tokens, transactions, fees, staking, включая member/info, liquid и usde, gasless, включая config, estimate и send, команды connect, wallet-request, storage, appconfig, banners, rates, Changelly, push, client-error, service-address, balances/old, protect/allowed-domains и другие.
Важно: формат запросов и ответов, лимиты и контракты внутренних API могут меняться без предупреждения. Гарантии стабильности и обратной совместимости предоставляются только для публичных API, то есть TON Connect и официально задокументированных endpoint-ов.
TON: транзакции и статус
GET /transactions/{address}
Назначение: получение истории транзакций по TON-адресу, версия API v1. Используется как один из источников для отображения списка операций в кошельке.
GET /transactions/v2/{address}
Назначение: история транзакций по TON-адресу, версия v2. Это более новый формат ответа; приложение может использовать его для тех же целей, что и v1.
POST /transactions/v3
Назначение: единая история операций для TON и Solana в одном ответе. Тело запроса содержит account, например tonAddress, solanaAddress, solanaATAaddress при необходимости, а также network, cursor и limit. Этот endpoint нужен для единого списка транзакций в кошельке, то есть TON + SOL + SPL, с пагинацией.
POST /ton/transactions/status/{network}
Назначение: проверка статуса конкретной TON-транзакции по ее хэшу, где в теле передается txHash. Используется, чтобы понять, подтверждена отправленная операция или все еще обрабатывается.
TON: конфигурация и контракты
GET /config
Назначение: получение глобальной конфигурации сети TON, включая gas fees, storage, message limits и другие параметры. Нужно для локального расчета комиссии перед отправкой транзакции, то есть estimateFees.
GET /config/{address}
Назначение: конфигурация кошелька по адресу, включая версию контракта, например v4 или v5, и его тип. Используется для корректного формирования транзакций и понимания ограничений кошелька, например количества сообщений в одной транзакции.
GET /contract/info/{address}
Назначение: общая информация о контракте по адресу, включая state и code. Используется при разборе контрактов и проверке их типов, в том числе токенов.
GET /metadata/{address}
Назначение: metadata контракта по адресу, например name, symbol, image и другие поля. Используется для отображения данных о токенах и других контрактах, когда приложению нужны не только балансы, но и описания активов.
GET /net/{network}/elections/latest
Назначение: данные о последних выборах валидаторов в сети TON, где network может быть mainnet, sandbox или testnet. Нужны для стейкинга: чтобы понимать текущий цикл, периоды разблокировки и другие параметры.
GET /net/{network}/elections/{id}
Назначение: данные о выборах по конкретному id. Используется для деталей цикла, например при отображении истории выборов в стейкинге.
GET /net/{network}/elections/latest/apy
Назначение: годовая доходность, то есть APY, по последним выборам. Показывается в разделе стейкинга как ориентир по доходности.
TON-токены
GET /hints/{address}?version=1
Назначение: краткие token hints для указанного TON-адреса, версия 1. Используется в сценариях, где достаточно компактного списка без полной metadata.
GET /hints/full/{address}
Назначение: полный список токенов по адресу с балансами, названиями, символами, иконками и флагами верификации, а также с query-параметром isTestnet=true для testnet. Это основной источник для экрана активов: список токенов, блок “Savings” и выбор токенов при переводах. В ответе также есть addressesIndex для быстрого поиска по master-адресу.
GET /hints/extra/{address}
Назначение: дополнительные “валюты” или hints по адресу, то есть extra currency hints. Отображаются в том же блоке, что и токены, как отдельный тип карточек в списке активов.
GET /jettons/metadata?address={master}
Назначение: metadata master-контракта jetton, включая name, symbol, decimals, image и при необходимости LP-данные. Используется, когда приложению нужны актуальные название, логотип и точное количество decimal places для отображения и расчетов.
POST /jettons/wallet/address
Назначение: расчет адреса token-wallet пользователя для заданного master-контракта. Тело: address владельца, master, isTestnet, seqno. Нужен при формировании переводов токенов и проверке, существует ли у пользователя кошелек для данного токена.
GET /jettons/wallet/{walletAddress}
Назначение: данные jetton-wallet по адресу кошелька, с query-параметром isTestnet. Используется для получения баланса и metadata конкретного token-wallet, когда известен только адрес контракта.
POST /jettons/wallet/transactions
Назначение: история транзакций конкретного token-wallet. Тело содержит адрес и параметры пагинации или фильтрации. Нужен для экрана истории транзакций по отдельному токену.
GET /jettons/rates/{key}?isTestnet=
Назначение: курсы токенов по ключу, которым обычно является master-адрес. Используется для отображения баланса в фиате и для сортировки и фильтрации токенов по стоимости.
GET /mintless/jettons/{address}
Назначение: список “mintless” токенов по адресу владельца, то есть токенов без отдельного mint. Нужен для полноты списка активов и корректного отображения таких токенов.
GET /mintless/jettons/... (payload)
Назначение: получение payload для операций с mintless-токенами, используется в fetchJettonPayload. Нужен при формировании переводов или запросов к таким контрактам.
Solana
POST /solana/account/{network}
Назначение: баланс SOL по адресу. Тело: { address }. Используется для отображения нативного Solana-баланса в кошельке и проверки достаточности средств перед отправкой.
POST /solana/tokens/{network}
Назначение: список SPL-токенов по адресу. Тело: { address }. Это основной источник для экрана активов Solana: какие токены есть у пользователя, их балансы, символы и логотипы.
POST /solana/transactions/{network}
Назначение: история транзакций Solana по адресу. Тело: { address, ...query }. Нужна для общего списка операций Solana и экрана истории Solana-кошелька.
POST /solana/transaction/{network}
Назначение: статус конкретной транзакции Solana по подписи, где в теле передается { signature }. Используется для проверки подтверждения отправленных операций, например pending, confirmed или failed.
POST /solana/transaction/fees/{network}
Назначение: оценка комиссии транзакции. Тело: { transaction }, то есть сериализованная транзакция. Результат показывается пользователю перед подтверждением перевода SOL или SPL как “Network fee”.
WebSocket wss://connect.tonhubapi.com/solana/{network}/account/{address}/ws
Назначение: подписка на обновления Solana-аккаунта, например баланса и новых транзакций. Приложение переподписывается на данные при изменении баланса или появлении новых операций, чтобы не делать постоянный REST-поллинг.
Стейкинг (connect.tonhubapi.com)
POST /staking/member/info
Назначение: состояние участника сразу по нескольким стейкинг-пулам. Тело: isTestnet, address, pools[]. Используется на экране стейкинга для отображения balance, pendingDeposit, pendingWithdraw, withdraw по каждому известному пулу без отдельных запросов get_member к TON.
POST /staking/member/liquid/info
Назначение: состояние пользователя в ликвидном стейкинге, то есть wsTON. Тело: { isTestnet, address }. Возвращает баланс wsTON, pendingWithdrawals и другие данные. Нужно для карточки “Whales Liquid” и операций пополнения и вывода.
GET /staking/{network}/pool/liquid/info
Назначение: параметры и курсы ликвидного пула: rateDeposit, rateWithdraw, extras, например minStake, комиссии, roundEnd, proxyStakeUntil и другие, а также balances. Используется для отображения курсов TON ↔ wsTON и комиссий при пополнении и выводе.
GET /usde/{network}/rate
Назначение: текущий курс USDe, то есть Ethena. Используется в разделе USDe Liquid для показа курса и расчета эквивалентов.
GET /usde/{network}/apy
Назначение: APY для USDe. Показывается в карточке USDe Liquid как ориентир по доходности.
POST /usde/staking/member/liquid/info
Назначение: данные участника по USDe liquid staking, где в теле передаются адрес и другие параметры. Нужен для отображения баланса и состояния в продукте USDe.
Staking indexer, отдельный хост
Base URL:https://staking-indexer.whales-api.com
GET /status/{network}
Назначение: статус выборов и пулов, где network пустой для mainnet и testnet для testnet. Используется как источник данных о текущем стейкинговом цикле, периодах разблокировки и списке валидаторов; если он недоступен, приложение может перейти на fallback через fetchStakingStatusV4 по данным TON.
POST /indexer/nominator
Назначение: данные номинатора по пулу и адресу, включая депозиты, выводы и прибыль за период. В теле указываются пул, адрес и периоды. Нужен для детальной аналитики и истории стейкинговых операций.
POST /indexer/pool/apy
Назначение: APY пула. Тело: { address, fixedPeriod: 'week' } и аналогичные параметры. Показывается в карточке пула как ориентир по доходности.
Gasless
GET /gasless/{network}/config
Назначение: конфигурация gasless-отправки: список token master, для которых доступен gasless, и адрес relayer, то есть relay_address. На основе этого конфига приложение решает, показывать ли пользователю опцию “оплатить комиссию токеном” при переводах, только для W5 и перечисленных токенов.
POST /gasless/{network}/estimate
Назначение: оценка gasless-отправки: комиссия в токене, итоговые сообщения, адрес relayer и valid_until. В теле передаются data, включая master, wallet_address, wallet_public_key, messages, и отдельно master. Результат показывается пользователю перед подтверждением; при ошибках, таких как not-enough, try-later, cooldown, отображаются соответствующие сообщения.
POST /gasless/{network}/send
Назначение: отправка подписанного пользователем BOC через relayer. Тело: { wallet_public_key, boc }. Relayer оплачивает gas в TON и списывает комиссию с пользователя в токене.Основной backend base URL:
https://connect.tonhubapi.comСеть: у многих endpoint-ов есть параметр
network или суффикс в пути, например mainnet или testnet, а для Solana также devnet.
TON Connect и подключения приложений
Base URL /tonconnect
Назначение: корневой путь bridge TON Connect, то есть SSE/bridge. Используется клиентами TON Connect для установления сессии и обмена сообщениями с кошельком.
POST /connect/command
Назначение: команда подключения в legacy-сценарии, то есть ton-x. Используется при подключении по старому сценарию, например в части кейсов с внешним браузером.
POST /connect/grant
Назначение: подтверждение выданной сессии. Тело: { key }. Вызывается после того, как пользователь подтвердил подключение в кошельке, чтобы приложение, то есть dApp, получило сессию.
POST /connect/revoke
Назначение: отзыв сессии подключения. Тело: { key }. Вызывается при нажатии “Revoke access” в списке подключенных приложений; после этого сессия становится недействительной.
POST https://connect.tonhubapi.com/connect/answer
Назначение: отправка ответа на запрос подключения на сервер, то есть в reportEndpoint. В теле содержатся key, appPublicKey, address, walletType, walletConfig, walletSig, endpoint, testnet, kind. Используется для уведомления backend о том, что подключение прошло успешно, и о параметрах кошелька в TON Connect и совместимых сценариях.
Wallet requests
GET /wallet-request/{address}/{network}/list
Назначение: список ожидающих wallet request, например на подпись или перевод. Query: type. Используется для показа входящих запросов и уведомлений пользователю.
POST /wallet-request/create
Назначение: создание нового wallet request, например запроса на подпись. Используется в сценариях, где инициируются внешние запросы к кошельку.
POST /wallet-request/respond
Назначение: ответ на запрос, то есть подпись или отклонение. Отправляется после того, как пользователь подтвердил или отклонил запрос в приложении.
Storage, облачное key-value хранилище
POST /storage/read
Назначение: чтение данных по ключу, например по publicKey в base64. Используется для синхронизации настроек между устройствами, включая список скрытых токенов tokens-disabled.
POST /storage/write
Назначение: запись данных по ключу. Используется при сохранении настроек в облако, например скрытых токенов, списка подключенных приложений и других данных, чтобы они были доступны после переустановки или на другом устройстве.
Конфигурация приложения и баннеры
GET /appconfig/{network}
Назначение: конфигурация приложения для сети, включая включение и отключение функций, например features.ethena для USDe, ограничения, URL и другие параметры. Определяет, какие экраны и опции показывать пользователю.
GET /appconfig/versions/{network}
Назначение: информация о версии приложения и обновлениях, включая минимальную версию, обязательное обновление и другие параметры. Используется для проверки необходимости обновления и показа соответствующих сообщений.
GET /apps/metadata?url=
Назначение: metadata приложения, то есть dApp, по его URL: name, icon, domain. Используется при открытии приложений в браузере и в списке подключенных приложений.
GET /apps/catalog
Назначение: каталог приложений. Query: url. Используется для показа информации о приложении в каталоге и при поиске по URL.
GET /apps/reviews?url=&address=
Назначение: отзывы пользователей о приложении по url и, при необходимости, по адресу. Показываются в карточке приложения в браузере и каталоге.
POST /apps/reviews
Назначение: отправка пользовательского отзыва о приложении. Тело: { url, input }. Сохраняет оценку и текст отзыва на backend.
POST /apps/reports
Назначение: отправка жалобы на приложение. Тело: { url, input }. Используется для модерации и блокировки вредоносных приложений или приложений, нарушающих правила.
GET /tonhub/banners
Назначение: баннеры в браузере приложений, например на основном экране браузера и в promo-блоках. Определяет, какие карточки и ссылки показывать в разделе приложений.
GET /tonhub/holders/banners
Назначение: баннеры, связанные с Holders, например карты и промо. Показываются в соответствующем разделе или на экране Holders.
GET /ads/banners
Назначение: рекламные баннеры с параметрами. Используются для показа рекламных блоков в разрешенных местах приложения.
GET /protect/allowed-domains
Назначение: список доменов, разрешенных для навигации во WebView, то есть защита от фишинга и переходов на нежелательные сайты. Приложение сверяет с этим списком, можно ли открыть ссылку во встроенном браузере.
Курсы и токены
GET /v2/price
Назначение: текущие цены активов, таких как TON и SOL, в фиатных валютах. Используется для отображения балансов и сумм в USD и другой выбранной валюте по всему приложению.
POST /v2/rates
Назначение: валютные курсы с учетом сети. Тело: { network }. Используется для конвертации сумм и отображения эквивалентов в выбранной валюте.
POST /token/info
Назначение: подробная информация о токене по идентификаторам, где в теле передаются адреса и типы. Используется в сценариях, где требуется расширенная информация сверх той, что приходит из hints.
Разное
GET /balances/old/{pubkey}
Назначение: получение балансов “старых” кошельков по публичному ключу в hex-формате. Используется во время миграции или восстановления старых адресов, чтобы показать остатки и при необходимости предложить перевод средств.
POST /service-address/check
Назначение: проверка, является ли адрес сервисным, например контрактом, с которым не рекомендуется взаимодействовать. Тело: { address }. Может использоваться для предупреждения пользователя перед отправкой на такие адреса.
POST /push/register
Назначение: регистрация устройства для push-уведомлений. В теле передаются токен и параметры устройства. Нужно для доставки уведомлений о входящих транзакциях и других событиях.
POST /client-error/report
Назначение: отправка отчета об ошибке клиента, включая логи, тип ошибки и контекст. Используется для диагностики и повышения стабильности приложения; при этом ключи и seed-фраза не передаются.
Changelly, обмен
GET /changelly/currencies
Назначение: список валют, доступных для обмена через Changelly. Используется при выборе пары для обмена и проверке поддерживаемых активов.
POST /changelly/estimate
Назначение: оценка суммы обмена, включая курс, комиссию и итоговую сумму. Используется до создания обменной транзакции, чтобы показать пользователю ожидаемый результат.
POST /changelly/transaction/create
Назначение: создание обменной транзакции. Инициирует сделку на стороне Changelly и возвращает параметры, необходимые для отправки средств пользователем.
POST /changelly/transaction/details
Назначение: получение деталей созданной обменной транзакции, включая статус, суммы и адреса. Используется для отображения статуса обмена в приложении.
POST /changelly/transaction/resolve
Назначение: завершение, обновление или запрос статуса обменной транзакции. Используется при завершении обмена или проверке результата.
POST /changelly/transactions
Назначение: список обменных транзакций пользователя, где в теле запроса передаются адрес, сеть и другие параметры. Используется для истории обменов в разделе Changelly.
Holders, отдельный хост
Сервисы Holders работают на card-prod.whales-api.com для mainnet и card-staging.whales-api.com для testnet. Ниже перечислены основные API и их назначение.POST https://{holdersEndpoint}/v2/user/wallet/connect
Назначение: подключение кошелька к Holders: передача TON и Solana proof и получение пользовательского токена. Вызывается при первом входе в Holders, то есть enroll; затем этот токен используется для запроса аккаунтов, карт и профиля.
POST https://{holdersEndpoint}/account/state
Назначение: состояние Holders-аккаунта, включая список аккаунтов, карт и других сущностей, по токену. Используется для отображения карт и аккаунтов в разделе Holders.
POST https://{holdersEndpoint}/v2/profile/get
Назначение: профиль пользователя Holders, например имя и настройки. Показывается в настройках Holders и при необходимости на других экранах интеграции.
POST https://{holdersEndpoint}/card/get
Назначение: данные конкретной карты по id. Используется для отображения деталей карты и операций по ней.Другие endpoint-ы Holders, включая OTP, card transactions, IBAN, Apple Pay, invitations и так далее, используются в соответствующих сценариях; их список и описание можно найти в коде по пути
app/engine/api/holders/.
RPC TON (TonClient4)
Приложение использует TonClient4 для прямого чтения данных из блокчейна TON:
- mainnet:
https://mainnet-v4.tonhubapi.com - testnet:
https://testnet-v4.tonhubapi.com
getLastBlock и runMethod. Через них приложение читает параметры стейкинг-пулов, например get_params, get_member, балансы и состояния контрактов напрямую из TON, когда нужны актуальные on-chain данные без backend-кэша.