# fragment-api.io — LLM integration guide

> Provider API for Telegram Stars via Fragment.
> Pay with TON or USDT TON from merchant balance.

## Base URL
https://api.fragment-api.io

## Authentication
Header: X-API-Key: <merchant_api_key>
Legacy: Authorization: Bearer <merchant_api_key>

Key format: URL-safe string (secrets.token_urlsafe(32)), no prefix.
Full key shown once at registration or rotation in Telegram bot.
Server stores SHA-256 hash only.

## USDT deposit contract (only accepted)
EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs
Suffix for wallet verification: Id_sDs
Other jettons are rejected.

## Minimum deposit
5 TON or 5 USDT (amounts below minimum are ignored)

## Payment methods
- ton — debit ton_balance
- usdt_ton — debit usdt_balance

## Error codes
400 — invalid parameters (detail string)
401 — missing or invalid API key
402 — insufficient balance
404 — transaction not found

Response format: {"detail": "message"}

## Order statuses
pending → processing → paying → completed | failed
Failed orders are refunded to merchant balance automatically.

## Constraints
- product_type: stars | premium

## Stars
- quantity: 50–1000000 (star count)

## Premium
- quantity: 3, 6, or 12 (months)
- quantity: string, 50–1000000
- idempotency_key: required for all purchases (unique per order)

---

## GET /api/balance

Returns ton_balance, usdt_balance, deposit_address, usdt_jetton_master, usdt_jetton_master_suffix.

Example:
curl "https://api.fragment-api.io/api/balance" -H "X-API-Key: KEY"

---

## GET /api/prices

Query params:
- product_type (required): stars
- quantity (optional string): default 50
- payment_method (optional): ton | usdt_ton

Returns: product_type, item_name, price, gas_fee, total, currency, payment_method

---

## GET /api/prices/list

Returns array of PriceResponse for quantities 50, 100, 500, 1000 × (ton, usdt_ton).

---

## POST /api/search

Body:
{
  "product_type": "stars",
  "query": "username",
  "quantity": "50"
}

200 found: {"ok": true, "found": {"recipient": "...", "name": "...", "myself": false}}
200 not found: {"ok": false, "found": null}

---

## POST /api/purchase

Body:
{
  "product_type": "stars",
  "recipient": "username_without_at",
  "quantity": "50",
  "payment_method": "usdt_ton",
  "idempotency_key": "unique-key"
}

201: transaction_id, status (pending), item_price, payment_method, created_at
402: insufficient balance

---

## GET /api/purchase/transaction/{transaction_id}

Returns Transaction object with status, error_message, ton_tx_id.

---

## GET /api/purchase/by-idempotency-key/{key}

Same Transaction object as above.

---

## GET /api/purchase/history?limit=50&offset=0

Returns {transactions: [...], limit, offset}

---

## POST /merchants/topup

Body: {"currency": "ton"} or {"currency": "usdt"}

201: wallet_address, usdt_jetton_master, usdt_jetton_master_suffix, note, invoice_id

---

## Agent workflow
1. GET /api/balance — check balances and deposit_address
2. POST /api/search — verify recipient
3. GET /api/prices — quote
4. POST /api/purchase — with idempotency_key
5. Poll GET /api/purchase/transaction/{id} until completed

## OpenAPI
https://api.fragment-api.io/openapi.json

## Human documentation
https://doc.fragment-api.io

## Legacy v1 (deprecated)
/v1/balance, /v1/stars/search, /v1/stars/quote, /v1/stars/purchase, /v1/orders/{id}, /v1/withdraw