# STONS: платёжный API

> Приём криптоплатежей через API и выплаты на адреса из вайтлиста. Приём работает в TRON, в EVM-сетях — Ethereum, BNB Smart Chain, Polygon, Base, Arbitrum, OP Mainnet, Avalanche, — в TON и в Solana, в USDT, USDT0, USDC и нативной монете каждой сети; выплаты сервис делает только в TRON. Не зашивайте этот список в код: какие активы доступны проекту прямо сейчас, отвечает GET /v1/assets. Инвойс в токене отдаёт адрес целиком и точную сумму для оплаты на своей странице; инвойс без токена оплачивается на странице оплаты сервиса, где покупатель выбирает монету и сеть. События приходят вебхуками с подписью HMAC-SHA256, а источник истины для любого статуса — API. API: https://api.stons.io/v1, ключ в заголовке X-Api-Key, суммы — десятичные строки.

Вся документация одним файлом: https://stons.io/ru/llms-full.txt. Маршруты /v1 в формате OpenAPI 3.1: https://api.stons.io/v1/openapi.json. Все ссылки ниже ведут на Markdown. Начните с документа «Интеграция под ключ с ИИ-ассистентом» по адресу https://stons.io/ru/docs/ai-integration.md и выполните его шаги; разделы ниже идут в порядке интеграции.

## Начало

- [Интеграция под ключ с ИИ-ассистентом](https://stons.io/ru/docs/ai-integration.md): Начните отсюда: словарь, что спросить у владельца проекта, шаги интеграции по порядку с правилами выбора и самопроверка.
- [Сети и токены](https://stons.io/ru/docs/networks.md): Сети и токены сервиса, что он делает в каждой сети, почему число знаков после запятой зависит от сети и где API сообщает, какие активы может предложить проект.

## API

- [Аутентификация](https://stons.io/ru/docs/authentication.md): Заголовок X-Api-Key и формат ключа, лимиты запросов и Retry-After, ротация ключей и почему клиенту нужен https.
- [Инвойсы](https://stons.io/ru/docs/invoices.md): Создание и получение инвойсов: в токене или с выбором токена покупателем, идемпотентность по order_id, статусы, комиссии и суммы строками.
- [Адреса для приёма платежей](https://stons.io/ru/docs/addresses.md): Постоянные адреса пользователей в режиме per_user, два режима адресов и режим на паузе, что зачисляется на адрес, проверка перевода по хэшу транзакции и показ адреса целиком.
- [Страница оплаты](https://stons.io/ru/docs/checkout.md): Страница оплаты сервиса по checkout_url: что видит покупатель, выбор токена, адреса возврата и подписанный редирект.
- [Вебхуки](https://stons.io/ru/docs/webhooks.md): Все события и когда они приходят, поля тела, проверка подписи HMAC-SHA256 на Node.js и Python и повторы доставки.
- [Баланс](https://stons.io/ru/docs/balance.md): Деньги проекта: баланс каждого актива по реестру, что ещё не подтверждено, и те же деньги в долларах по принятым курсам.
- [Выплаты](https://stons.io/ru/docs/payouts.md): Выплаты на адреса из вайтлиста: запрос, идемпотентность по reference, статусы, комиссия, лимиты и подтверждение человеком.
- [Коды ошибок](https://stons.io/ru/docs/errors.md): Тело ошибки, каждый error.code с HTTP-статусом и тем, что делать клиенту, и X-Request-Id.

## Перед запуском

- [Чек-лист перед продом](https://stons.io/ru/docs/checklist.md): Проверки перед приёмом реальных платежей: ключи, вебхуки, суммы, показ адреса, страница оплаты и выплаты.

## Optional

- [Журнал изменений API](https://stons.io/ru/docs/changelog.md): Изменения API, событий вебхуков и кодов ошибок по датам, с отметкой несовместимых изменений.