Обзор API

REST API с телами в JSON. Страницы справочника генерируются из его спецификации OpenAPI, поэтому всегда соответствуют сервису.

Адреса API

Окружение	Адрес	Ключи
Тестнеты: Sepolia, BSC testnet	https://api-testnet.portuna.io	ptn_test_…
Мейннет: Ethereum, BSC	скоро	ptn_live_…

См. Тестовые и боевые ключи.

Аутентификация

Передавайте API-ключ в каждом запросе:

curl "https://api-testnet.portuna.io/v1/balance" -H "Authorization: Bearer $PORTUNA_API_KEY"

Без ключа, с неизвестным или отозванным ключом ответ — 401 unauthorized; для отключённого аккаунта — 403 partner_disabled. GET /healthz и GET /v1/openapi.yaml ключа не требуют.

Форматы

• Запросы: JSON с Content-Type: application/json, до 64 КиБ. Неизвестные поля — ошибка 400 invalid_json, так что опечатка в имени поля не пройдёт незамеченной.
• Суммы: строки с целым числом в минимальных единицах токена, например "1000000": wei для нативной монеты, 10⁻⁶ для USDT в Ethereum. Строки — потому что суммы не помещаются в целые числа многих JSON-парсеров.
• Адреса: 0x-hex в любом регистре; в ответах — с контрольной суммой (EIP-55).
• Сети: chain_id, числовой id сети, например 11155111 для Sepolia.
• Время: RFC 3339 в UTC.
• Необязательные поля без значения в ответах не передаются.

Списки

GET /v1/sweeps, /v1/revocations, /v1/ledger и /v1/webhook/deliveries отдают страницы, новые записи первыми:

{ "items": [ … ], "next_cursor": "eyJ0Ijoi…" }

• limit задаёт размер страницы: до 200, по умолчанию 50.
• Чтобы получить следующую страницу, передайте next_cursor в cursor; на последней странице он null. Курсор непрозрачный.
• Записи, добавленные между запросами, не сдвигают страницы и не повторяются.
• Неверный параметр — 400 invalid_query, имя параметра — в message.
• SDK проходят страницы сами: AllSweeps и другие в Go, allSweeps и другие в TypeScript.

Ошибки

{ "error": { "code": "unknown_token", "message": "token must be a listed ticker, its address or \"native\"" } }

Ветвитесь по code — он стабилен; message — для людей. Все коды — в гайде Ошибки и повторы. Запросы, которые создают задания на sweep и снятия делегации, принимают external_id, чтобы их было безопасно повторять: см. Идемпотентность.

Спецификация OpenAPI

• openapi.yaml — спецификация OpenAPI 3.1 с описаниями на английском, для генераторов кода и инструментов API.
• GET /v1/openapi.yaml у API отдаёт ту же спецификацию — в том виде, в каком её знает работающий сервис.

Ресурсы

АккаунтБаланс газ-кошелька, тариф, настройки, движения и работа по дням.

Горячие кошелькиРегистрация горячих кошельков и развёртывание их делегатов.

SweepСоздание, получение и список заданий.

Снятие делегацииСнятие делегации с депозитных адресов.

ВебхукНастройки вебхука, журнал доставки и тестовые события.

События вебхукаЗаголовки, конверт и данные каждого события.

ОбъектыВсе объекты со всеми полями.

СервисПроверка работоспособности и спецификация.