Fragment API
Fragment APIREST v1

From API key to delivered gift.

The shortest reliable path to Telegram Stars and Premium: validate the recipient, reserve a funded balance, create an idempotent order, then confirm delivery.

REST

JSON over HTTPS

TON · USDT

On TON network

Async

Webhook or polling

Before you start

Sign in to the dashboard, create an API key, and fund either your TON or USDT balance. API keys belong in server-side code and must never be exposed in a browser or mobile application.

Base URLs: use https://v1.fragmentapi.com/api/v1/partner in production and https://sandbox.fragmentapi.com/api/v1/partner while testing.

Create your first Stars order

01

Authenticate every request

Pass the key in the API-Key header. A missing, expired, revoked, or inactive key returns 401.

API-Key: your_api_key_here
02

Resolve the recipient

Search before purchase. The response returns the provider recipient hash required by the order endpoint.

GET
/star/recipient/search?username={username}&quantity={quantity}
curl "https://v1.fragmentapi.com/api/v1/partner/star/recipient/search?username=alexdev&quantity=100" \
  -H "API-Key: $FRAGMENT_API_KEY"
03

Create one idempotent order

Use a new UUID as Idempotency-Key for every logical order. Retrying the same payload returns the existing order without reserving the wallet twice.

POST
/orders/star
curl -X POST "https://v1.fragmentapi.com/api/v1/partner/orders/star" \
  -H "API-Key: $FRAGMENT_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alexdev",
    "recipient_hash": "recipient_hash_from_search",
    "quantity": 100,
    "wallet_type": "TON"
  }'
04

Confirm the final state

The create call returns 202 Accepted. Listen for order.completed or order.failed, and keep order polling as your fallback.

GET
/orders/{order_id}

Find the right guide

Pricing

5% service margin, VAT treatment, resale economics, and refund rules.

Read guide

Orders

Stars and Premium parameters, responses, status, and idempotency.

Read guide

Wallets & deposits

Fund TON or official USDT on TON and inspect each balance.

Read guide

Webhooks

Verify HMAC signatures and process delivery retries safely.

Read guide

Production checklist

  • Keep API keys and webhook secrets on your server.
  • Use a unique idempotency key for every customer order.
  • Store the order_id before responding to your customer.
  • Verify webhook signatures against the raw request body.
  • Treat webhooks as notifications and the order endpoint as the source of truth.
  • Never fulfill while an order is pending or processing.
    Quickstart — API Documentation | Fragment API