Endpoints
GET/api/balance
Returns merchant balance, deposit address, and USDT contract info.Баланс мерчанта, deposit-адрес и данные USDT-контракта.
Parameters
| Name | Type | In | Required | Description |
|---|
| X-API-Key | string | header | Yes | Merchant API key |
200 Success
{
"ton_balance": 1.25,
"usdt_balance": 9.14,
"deposit_address": "UQDVv_pPqr8U...",
"usdt_jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
"usdt_jetton_master_suffix": "Id_sDs",
"mainnet_balance": 1.25,
"testnet_balance": 0.0
}
401 Unauthorized
{ "detail": "Invalid API key" }
Examples
cURL
curl "https://api.fragment-api.io/api/balance" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const balance = await fetch("https://api.fragment-api.io/api/balance", {
headers: { "X-API-Key": process.env.FRAGMENT_API_KEY }
}).then(r => r.json());
Python
import requests
balance = requests.get(
"https://api.fragment-api.io/api/balance",
headers={"X-API-Key": "YOUR_API_KEY"},
).json()
GET/api/prices
Quote Stars price for a given quantity and payment method.Расчёт стоимости Stars для указанного количества и способа оплаты.
Parameters
| Name | Type | In | Required | Description |
|---|
| product_type | string | query | Yes | stars only |
| quantity | string | query | No | 50–1000000. Default: 50 |
| payment_method | string | query | No | ton | usdt_ton. Default: usdt_ton |
| X-API-Key | string | header | Yes | Merchant API key |
200 Success
{
"product_type": "stars",
"item_name": "50 Telegram Stars",
"price": 0.7875,
"gas_fee": 0.07,
"total": 0.8575,
"currency": "USDT",
"payment_method": "usdt_ton"
}
400 Bad Request
{ "detail": "Unsupported product_type: premium" }
Examples
curl "https://api.fragment-api.io/api/prices?product_type=stars&quantity=50&payment_method=usdt_ton" \
-H "X-API-Key: YOUR_API_KEY"
GET/api/prices/list
Price list for common volumes (50, 100, 500, 1000 stars) in TON and USDT TON.Прайс-лист для типовых объёмов (50, 100, 500, 1000 stars) в TON и USDT TON.
Parameters
| Name | Type | In | Required | Description |
|---|
| X-API-Key | string | header | Yes | Merchant API key |
200 Success
[ { "product_type": "stars", "item_name": "50 Telegram Stars", "total": 0.575, "...": "..." } ]
Examples
curl "https://api.fragment-api.io/api/prices/list" -H "X-API-Key: YOUR_API_KEY"
POST/api/search
Verify Telegram Stars recipient exists via Fragment.Проверка существования Telegram-получателя Stars через Fragment.
Parameters (body JSON)
| Name | Type | Required | Description |
|---|
| product_type | string | Yes | stars |
| query | string | Yes | Username (with or without @) |
| quantity | string | No | Optional compat field |
| payment_method | string | No | Optional compat field |
200 — found
{ "ok": true, "found": { "recipient": "durov", "name": "Pavel Durov", "myself": false } }
200 — not found
{ "ok": false, "found": null }
Examples
curl -X POST "https://api.fragment-api.io/api/search" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product_type":"stars","query":"durov","quantity":"50"}'
POST/api/purchase
Create a Stars purchase order. Balance is debited when the worker processes the order.Создание заказа на покупку Telegram Stars. Списание с баланса при обработке worker'ом.
Parameters (body JSON)
| Name | Type | Required | Description |
|---|
| product_type | string | Yes | stars |
| recipient | string | Yes | Telegram username without @ |
| quantity | string | Yes | 50–1000000 (string) |
| payment_method | string | No | ton | usdt_ton. Default: usdt_ton |
| idempotency_key | string | No | Unique order key; retries return the same order |
201 Created
{
"transaction_id": "ord_a1b2c3d4e5f6...",
"status": "pending",
"recipient": "durov",
"item_name": "50 Telegram Stars",
"item_price": 0.8575,
"payment_method": "usdt_ton"
}
402 Payment Required
{ "detail": "Insufficient usdt balance. Need 0.8575, have 0.5" }
Examples
curl -X POST "https://api.fragment-api.io/api/purchase" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"product_type":"stars","recipient":"durov","quantity":"50","payment_method":"usdt_ton","idempotency_key":"order-1001"}'
GET/api/purchase/transaction/{transaction_id}
Get order status by transaction_id from purchase response.Статус заказа по transaction_id из ответа purchase.
Parameters
| Name | Type | In | Required | Description |
|---|
| transaction_id | string | path | Yes | ID like ord_... |
| X-API-Key | string | header | Yes | Merchant API key |
200 Success
{ "transaction_id": "ord_...", "status": "completed", "ton_tx_id": "live:...", "...": "..." }
404 Not Found
{ "detail": "Transaction not found" }
GET/api/purchase/by-idempotency-key/{key}
Find order by your idempotency_key.Найти заказ по вашему idempotency_key.
200 Success
Same Transaction object as /api/purchase/transaction/{id}.Тот же объект Transaction, что и в /api/purchase/transaction/{id}.
404 Not Found
{ "detail": "Transaction not found" }
GET/api/purchase/history
Paginated order history for the merchant.История заказов мерчанта с пагинацией.
Parameters
| Name | Type | In | Required | Description |
|---|
| limit | integer | query | No | 1–100, default 50 |
| offset | integer | query | No | Default 0 |
| X-API-Key | string | header | Yes | Merchant API key |
200 Success
{ "transactions": [ { "...": "..." } ], "limit": 50, "offset": 0 }
POST/merchants/topup
Get deposit address and USDT contract info for top-up.Получить deposit-адрес и данные USDT-контракта для пополнения.
Parameters (body JSON)
| Name | Type | Required | Description |
|---|
| currency | string | No | ton | usdt. Default: ton |
| amount | float | No | Informational only |
201 Created
{
"wallet_address": "UQDVv_pPqr8U...",
"currency": "usdt",
"usdt_jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
"usdt_jetton_master_suffix": "Id_sDs",
"note": "Send TON to this address. For USDT TON use jetton contract …Id_sDs only."
}