XTR Wallet API

Приём платежей и переводы в XTR — стейблкоине, привязанном к цене Telegram Star ($0.015). Комиссия с оплаты счетов — 3%, переводы и вывод с баланса приложения — 0%.

Авторизация: ✓ ключ применён к примерам ниже

Основное

Базовый URL: https://api.xtrcoin.org
Заголовок: Authorization: Bearer <api_key> — ключ создаётся в @xtrwalletbot → «Для разработчиков».
Суммы — строки в минимальных единицах, 9 знаков: 1 XTR = "1000000000".
Ошибки — HTTP-статус + текст причины в теле.

Эндпоинты

GET/v1/me

Информация о приложении и его баланс.

curl https://api.xtrcoin.org/v1/me \
  -H "Authorization: Bearer xtr_…"

POST/v1/invoices

Создать счёт. Ссылку url покажите покупателю — она откроет оплату в MiniApp с карточкой вашего приложения.

amount — от 1 до 1 000 000 XTR ("1000000000"…"1000000000000000").
payload — до 1024 символов, вернётся в вебхуке и статусе.
expires_in — секунды, 60…86400, по умолчанию 3600.
idempotency_key — опционально, до 128 символов: повторный запрос с тем же ключом вернёт уже созданный счёт, а не создаст новый. Используйте ID заказа.

curl -X POST https://api.xtrcoin.org/v1/invoices \
  -H "Authorization: Bearer xtr_…" \
  -H "Content-Type: application/json" \
  -d '{"amount":"5000000000","payload":"order-42","idempotency_key":"order-42"}'

GET/v1/invoices

Список счетов. Фильтры (query): status (pending|paid|expired), from/to (RFC3339 по дате создания), limit (до 100), offset.

curl "https://api.xtrcoin.org/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer xtr_…"

GET/v1/invoices/{token}

Статус счёта: pending | paid | expired.

curl https://api.xtrcoin.org/v1/invoices/inv… \
  -H "Authorization: Bearer xtr_…"

POST/v1/transfers

Мгновенный перевод с баланса приложения пользователю кошелька по его Telegram ID. Без комиссии.

curl -X POST https://api.xtrcoin.org/v1/transfers \
  -H "Authorization: Bearer xtr_…" \
  -H "Content-Type: application/json" \
  -d '{"tg_id":123456789,"amount":"1000000000"}'

GET/v1/transfers · /v1/transfers/{ref}

Список переводов приложения или конкретный перевод по ref. Фильтры списка: tg_id, from/to, limit, offset.

curl "https://api.xtrcoin.org/v1/transfers?tg_id=123456789" \
  -H "Authorization: Bearer xtr_…"

POST/v1/withdraw

Вывод XTR с баланса приложения на TON-адрес. Комиссия 0%. Минимум — 15 XTR. Заявка проходит проверку, после одобрения токены отправляются в сеть.

curl -X POST https://api.xtrcoin.org/v1/withdraw \
  -H "Authorization: Bearer xtr_…" \
  -H "Content-Type: application/json" \
  -d '{"address":"UQ…","amount":"15000000000"}'

GET/v1/withdrawals · /v1/withdrawals/{id}

Список выводов приложения или конкретный вывод по id. Статусы: pending → approved → sent, либо rejected/failed. Фильтры списка: status, from/to, limit, offset.

curl "https://api.xtrcoin.org/v1/withdrawals?status=sent" \
  -H "Authorization: Bearer xtr_…"

Вебхуки

Если у приложения задан webhook_url, при оплате счёта на него уходит POST:

{
  "event": "invoice_paid",
  "invoice": "inv…",
  "amount": "5000000000",
  "payload": "order-42",
  "paid_at": "2026-07-15T18:02:49Z"
}

Подпись: заголовок X-XTR-Signature = hex(HMAC-SHA256(api_key, тело запроса)). Проверяйте её, прежде чем засчитывать оплату. Ретраи: до 10 попыток с экспоненциальной задержкой; ответ 2xx останавливает повторы. Без вебхука статус можно поллить через GET /v1/invoices/{token}.