> ## Documentation Index
> Fetch the complete documentation index at: https://whalescorp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API

Приложение Tonhub подключается к backend [**connect.tonhubapi.com**](http://connect.tonhubapi.com) и связанным сервисам для получения истории транзакций, балансов токенов, данных по стейкингу, gasless-переводов, TON Connect и других функций. Ниже приведен **список используемых API с описанием каждого**: зачем он нужен и как применяется в приложении.

# Архитектура API Tonhub

## Основные группы API

Backend API Tonhub делятся на 8 основных функциональных групп:

1. **Основные данные TON и Solana:** история транзакций, статусы операций, сетевые и кошельковые настройки, информация о контрактах. Сюда же входит TON RPC, то есть `mainnet-v4` и [testnet-v4.tonhubapi.com](http://testnet-v4.tonhubapi.com), для чтения состояния блокчейна. Эти API обеспечивают отображение балансов, историю операций и расчет комиссий.
2. **Информация об активах:** данные о токенах, включая hints, полную информацию, metadata, rates и транзакции кошелька, а также цены и курсы через `v2/price`, `v2/rates`, `token/info`. Это все, что нужно для списков активов, их фиатной оценки и выбора токенов при переводах.
3. **Стейкинг:** информация об участии в пулах, включая `member/info`, `member/liquid/info`, параметры ликвидного пула и данные по USDe, такие как курс, APY и состояние участника. Дополнительно используется отдельный сервис [**staking-indexer.whales-api.com**](http://staking-indexer.whales-api.com) для статуса выборов, номинаторов и APY пулов.
4. **Gasless-переводы:** настройки, включая список поддерживаемых токенов и relayer, расчет комиссий в токенах и отправка подписанных транзакций через relayer. Работает только для поддерживаемых токенов и кошельков W5.
5. **TON Connect и взаимодействие с кошельком:** bridge TON Connect, то есть `/tonconnect`, команды подключения `connect/command`, `grant`, `revoke`, `answer`, а также управление wallet-request, включая create, respond и list. Эта группа обеспечивает связь dApp с кошельком и обработку входящих запросов на подпись и перевод.
6. **Настройки приложения и каталоги:** конфигурация приложения, версии, metadata и каталог приложений, отзывы и жалобы, баннеры, включая tonhub, Holders и рекламные, а также список разрешенных доменов через protect. Эти API определяют доступные функции, показываемые приложения и содержимое браузера.
7. **Обмен валют:** интеграция Changelly — валюты, оценка курса, создание обменной операции и отслеживание ее статуса. Это отдельная функция внутри приложения.
8. **Интеграция с Holders:** карты, профиль, аккаунты, OTP на отдельном хосте [**card-prod.whales-api.com**](http://card-prod.whales-api.com) и staging-хосте. Это специальные API продукта Holders, не относящиеся к основному backend [connect.tonhubapi.com](http://connect.tonhubapi.com).

Вспомогательные API включают облачное хранилище `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 или партнеров.

**Внутренние API, используемые только приложением Tonhub:** все остальные API применяются исключительно внутри Tonhub: транзакции `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 и другие.

<Info>
  Важно: формат запросов и ответов, лимиты и контракты внутренних API могут меняться без предупреждения. Гарантии стабильности и обратной совместимости предоставляются только для публичных API, то есть TON Connect и официально задокументированных endpoint-ов.
</Info>

# 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`

**Назначение:** это не REST API, а JSON-RPC и HTTP endpoint-ы для методов вроде `getLastBlock` и `runMethod`. Через них приложение читает параметры стейкинг-пулов, например `get_params`, `get_member`, балансы и состояния контрактов напрямую из TON, когда нужны актуальные on-chain данные без backend-кэша.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.