Qonix FragmentsAPI

REST API for Telegram Stars and Premium gifts. Anonymous, settled on-chain in ~10–20s.

Base: https://api.qonixcore.com/v1Auth: API-Key header1 req/sec/keyHMAC-SHA256 webhooks

Introduction

The Qonix Fragments API lets you buy Telegram Stars and Premium gifts programmatically. Every order is delivered anonymously and settles on-chain in ~10–20 seconds.

Create an account on qonixcore.com
Mint an API key in API Keys
Top up TON via your unique memo address (Topup)
Call POST /orders/star or POST /orders/premium

Every order debits your prepaid TON balance. Failures auto-refund in full.

Authentication

Pass your key in the API-Key header on every request. Treat keys like passwords.

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/wallet/balance"

Rate limits

1 request per second per API key by default. Configurable per key.

Exceeding the limit returns 429 rate_limited.

Pricing & fees

Every order is charged at Fragment's live TON quote + a flat 2% API fee + TON network gas. The fee stays in our operator wallet; the on-chain transfer to Fragment is exactly the quoted amount.

All amount fields in order responses are the total the user paid (quote + 2% + gas). The preview endpoint also returns fragment_quote_ton, fee_ton, fee_percent, and gas_ton.

Failed orders are auto-refunded in full (quote + fee + gas).

Stars · Search recipient

Validate a Telegram username + quantity. Returns the recipient_hash you'll need for the order.

GET/star/recipient/search

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/star/recipient/search?username=alice&quantity=100"

200 OK · response

{
  "recipient_hash": "ABCDEF123456",
  "display_name":   "Alice",
  "photo_url":      "https://..."
}

Stars · Create order

Quantity 50 – 1,000,000. Returns immediately with status:processing; webhook fires when on-chain confirmed.

POST/orders/star

curl -X POST "https://api.qonixcore.com/v1/orders/star" \
  -H "API-Key: qonix_..." \
  -H "Content-Type: application/json" \
  -d '{
  "username": "alice",
  "recipient_hash": "ABCDEF123456",
  "quantity": 100
}'

200 OK · response

{
  "order_id":   "550e8400-e29b-41d4-a716-446655440000",
  "status":     "processing",
  "type":       "star",
  "username":   "alice",
  "quantity":   100,
  "amount":     5.61,
  "created_at": "2026-05-22T01:30:12Z"
}

Premium · Search recipient

Validate a Telegram username + months. months ∈ {3, 6, 12}.

GET/premium/recipient/search

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/premium/recipient/search?username=alice&months=3"

200 OK · response

{
  "recipient_hash": "ABCDEF123456",
  "display_name":   "Alice",
  "photo_url":      "https://..."
}

Premium · Create order

Send a Premium gift (3 / 6 / 12 months) to a Telegram user.

POST/orders/premium

curl -X POST "https://api.qonixcore.com/v1/orders/premium" \
  -H "API-Key: qonix_..." \
  -H "Content-Type: application/json" \
  -d '{
  "username": "alice",
  "recipient_hash": "ABCDEF123456",
  "months": 3
}'

200 OK · response

{
  "order_id":   "...",
  "status":     "processing",
  "type":       "premium",
  "username":   "alice",
  "months":     3,
  "amount":     17.85,
  "created_at": "..."
}

Premium · Packages

Live TON pricing for 3, 6, and 12-month Premium gifts.

GET/premium/packages

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/premium/packages"

200 OK · response

{
  "packages": [
    { "months":  3, "amount_ton": 17.50, "amount_usd": 33.20 },
    { "months":  6, "amount_ton": 30.10, "amount_usd": 57.10 },
    { "months": 12, "amount_ton": 55.00, "amount_usd": 104.30 }
  ],
  "ton_usd_rate": 1.90
}

Wallet balance

Operator wallet balance. Your prepaid TON balance is separate — see /topup in the dashboard.

GET/wallet/balance

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/wallet/balance"

200 OK · response

{
  "address":       "EQA...XYZ",
  "balance_ton":   42.7,
  "reserved_ton":  1.5,
  "available_ton": 41.2,
  "refreshed_at":  "..."
}

Order status

Look up an order by ID. Returns current status and tx_hash if completed.

GET/orders/{order_id}

curl -H "API-Key: qonix_..." \
  "https://api.qonixcore.com/v1/orders/550e8400-e29b-41d4-a716-446655440000"

200 OK · response

{
  "order_id":     "550e8400-...",
  "status":       "completed",
  "type":         "star",
  "username":     "alice",
  "quantity":     100,
  "amount":       5.61,
  "tx_hash":      "abc123def456...",
  "created_at":   "...",
  "completed_at": "..."
}

Webhooks

Configure up to 5 endpoints per account at Webhooks. We POST JSON when an event fires.

Event

order.completed

TON tx confirmed on chain; Fragment delivered the gift.

Event

order.failed

Fragment rejected, price drift, insufficient wallet, etc.

Headers we send

X-Qonix-Event — order.completed | order.failed
X-Qonix-Delivery — unique delivery id
X-Qonix-Timestamp — unix seconds; reject deliveries older than 5min
X-Qonix-Signature — HMAC-SHA256 of {timestamp}.{raw_body}

Verify the signature

# Webhook verification is server-side code, not a curl example.
# Switch to Python / JS / PHP / Go to see how to verify the signature.

Errors

All errors return JSON with error, message, and optional details.

code	HTTP	when
invalid_api_key	401	Missing or bad API-Key header
rate_limited	429	Too many requests/sec for this key
recipient_not_found	404	Telegram username has no Fragment-eligible account
insufficient_user_balance	402	Your TON balance is below the order amount
insufficient_wallet_balance	503	Operator wallet is short on TON (treasury issue)
fragment_blocked	503	Fragment returned an unexpected error / 5xx
fragment_session_expired	503	Operator must re-paste Fragment cookies
circuit_breaker_open	503	Repeated Fragment failures — try again in ~1 min
price_drift_detected	409	Fragment quote moved >2% between accept and broadcast
idempotency_conflict	409	Concurrent request with the same idempotency_key
wallet_not_configured	503	Operator hasn't encrypted a TON mnemonic yet

Ready to start?

Get your API Key