Сети и токены
Этот документ перечисляет сети и токены STONS и показывает, где API сообщает интеграции, какие активы она может предложить. Прочитайте его, прежде чем выбирать токены для своего продукта.
Что сервис делает в каждой сети
| Семейство | Сети | Приём платежей | Выплаты |
|---|---|---|---|
| TRON | TRON | да | да |
| EVM | Ethereum, BNB Smart Chain, Polygon, Base, Arbitrum, OP Mainnet, Avalanche | да | нет |
| TON | TON | да | нет |
| Solana | Solana | да | нет |
- Эта таблица говорит, что умеет сервис. Что доступно вашему проекту прямо сейчас, говорит
GET /v1/assets— он учитывает каталог, переключатели оператора и настройки проекта в кабинете. Берите список оттуда, а не отсюда: сеть или токен могут выключить, например на обслуживание, и тогда их активов в ответе не будет — см. какие активы можно предложить. - Сеть в API — идентификатор из реестра сетей сервиса:
tron,ethereum,bsc,polygon,base,arbitrum,optimism,avalanche,ton,solana, — вместе с названием для людей вnetwork_name. - Выплаты сервис делает только в сети TRON. Выплата в активе любой другой сети отклоняется с
422 asset_not_payable. - Что сервис делает с деньгами после их прихода — держит их и остаётся должен проекту или пересылает на собственный кошелёк проекта — на суммы, адреса и статусы инвойсов не влияет ни в одном из случаев; это описано в куда уходят деньги.
Токены
Токены — это каталог активов сервиса: контракты, число знаков после запятой, минимальные депозиты и число подтверждений берутся из него, а не из кода. Сейчас это стейблкоины USDT, USDT0 и USDC и нативные монеты сетей. Контракты, знаки и минимальные депозиты всех активов — в активах.
| Токены | Где |
|---|---|
| USDT | USDT_TRON, USDT_ETHEREUM, USDT_BSC, USDT_AVALANCHE, USDT_TON, USDT_SOLANA. Выплаты — только в USDT_TRON |
| USDT0 | USDT0_POLYGON, USDT0_ARBITRUM, USDT0_OPTIMISM: в этих сетях USDT выпущен как USDT0, и это другой контракт |
| USDC | USDC_ETHEREUM, USDC_BSC, USDC_POLYGON, USDC_BASE, USDC_ARBITRUM, USDC_OPTIMISM, USDC_AVALANCHE, USDC_SOLANA |
USDC в TRON: USDC_TRON |
Выключен оператором целиком: Circle прекратила выпуск USDC в сети TRON. В новых счетах он не принимается, и выплаты в нём тоже выключены. Уже открытые счета в нём оплачиваются, а перевод на постоянный адрес зачисляется — см. что приходит на адрес |
| Нативные монеты | TRX_TRON, GRAM_TON, SOL_SOLANA, ETH_ETHEREUM, BNB_BSC, POL_POLYGON, ETH_BASE, ETH_ARBITRUM, ETH_OPTIMISM, AVAX_AVALANCHE. Цена в долларах США переводится в монету по курсу; выплат в них нет. Засчитывается и перевод, который сделал смарт-контракт, — см. ниже |
| Другие токены | Каталог расширяет оператор, токен за токеном: контракт, число знаков, минимальный депозит и подтверждения читаются из сети, а не записаны в коде. Токен принимается к оплате, пока он либо привязан к доллару США, либо у него есть монета, по курсу которой он оценивается, — тогда цена в долларах США переводится по этому курсу. Выплатам нужна привязка, поэтому их нет в нативных монетах |
Нативная монета EVM-сети засчитывается, отправил её кошелёк или смарт-контракт — суммой самой транзакции или переводом, который сделал внутри неё смарт-контракт (смарт-кошелёк, мультиподпись, вывод с биржи). Перевод из контракта сервис находит трейсом блока и засчитывает, только если трейс объясняет весь рост баланса адреса. Перевод, который объяснить не удалось, автоматически не засчитывается: инвойс остаётся неоплаченным, вебхука нет. Такой перевод оператор сервиса разбирает вручную. Токен засчитывается по событию перевода, как бы его ни отправили.
Идентификаторы и знаки после запятой
Актив — это токен в сети: USDT_TRON — это USDT в сети TRON. Один и тот же токен в разных сетях — разные активы, с разными контрактами и, возможно, разным числом знаков после запятой: у USDT в TRON 6 знаков, а в BNB Smart Chain — 18.
- Не вшивайте число знаков в код: у суммы в ответе API ровно столько цифр после точки, сколько знаков у её актива — см. суммы.
- Показывайте покупателю сеть вместе с активом и полным адресом — см. чек-лист. Адрес в TON записан в user-friendly форме, которую принимает кошелёк, — см. адреса в TON.
Адрес в Solana — base58, от 32 до 44 знаков, и он регистрозависимый. В base58 строчные и заглавные буквы латиницы — разные символы, поэтому So11… и so11… — разные адреса. Никогда не приводите адрес этой сети к нижнему или верхнему регистру и не нормализуйте его иначе — ни в своей базе, ни в URL, ни при сравнении, ни в QR-коде. После такой правки это адрес, ключа к которому ни у кого нет, и отправленные туда деньги потеряны. Храните и сравнивайте адрес ровно таким, каким его вернул API, и показывайте целиком. То же относится к подписи транзакции Solana, которую сервис возвращает в tx_hash: это base58 из 86–88 знаков, а не 64 шестнадцатеричных знака, — см. адреса в Solana.
Какие активы можно предложить
Какие активы проект может предложить в данный момент, решают каталог сервиса, сети, которые включил оператор, переключатели оператора и настройки проекта в кабинете. API применяет их в этих местах:
| Где | Что даёт |
|---|---|
GET /v1/assets |
Все активы, в которых проект может выставить инвойс сейчас, с сетью, контрактом, числом знаков и минимальным депозитом — см. список активов. Актив, выключенный оператором или настройками проекта, в ответе не появляется |
POST /v1/addresses, поле assets |
Активы, которые можно предложить пользователю для оплаты на этот адрес в момент запроса — см. постоянный адрес пользователя |
POST /v1/invoices без asset |
Покупатель выбирает монету и сеть на странице оплаты из активов, которые принимает проект и для которых есть курс; цена переводится в выбранный по курсу, а currencies сужает список — см. токен выбирает покупатель |
GET /checkout/v1/invoices/{id}, поле choices |
Активы, которые покупатель может выбрать сейчас, с суммой к оплате в каждом — см. прочитать инвойс для страницы |
Актив, которым нельзя воспользоваться, POST /v1/invoices отклоняет: 422 asset_not_supported — сервис не принимает его для платежей, 422 asset_payments_disabled — оператор выключил приём в нём, 422 asset_disabled_by_merchant — его выключили настройки проекта — см. коды ошибок.
Когда список меняется
Новая сеть или новый токен записываются в журнал изменений и появляются в этом документе. Но список, на который опирается ваш код, — это ответ GET /v1/assets: он меняется и без записи в журнале, когда оператор выключает актив или сеть, например на обслуживание. Читайте его перед тем, как показать покупателю выбор сети, и не зашивайте сети в код.