Fragment APIREST v1

Create orders that are safe to retry.

Stars and Premium follow the same four-part contract: resolve the recipient, choose a funded wallet, send an idempotency key, and wait for a final order state.

Idempotency is your retry boundary

Send one unique Idempotency-Key header per logical purchase. A UUID is recommended. Repeating an identical request returns the original order; reusing the key with different order data returns 409 Conflict.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

The key is scoped to your developer account and may contain up to 128 characters. The JSON field idempotency_key and legacy X-Idempotency-Key header are accepted, but the standard header is preferred.

Telegram Stars

GET

/star/recipient/search?username={username}&quantity={quantity}

Validate eligibility and obtain recipient_hash.

Parameter	Type	Rules
`username`	string	Telegram username without @
`quantity`	integer	50 to 1,000,000

POST

/orders/star

Queue a Stars gift order.

{
  "username": "alexdev",
  "recipient_hash": "recipient_hash_from_search",
  "quantity": 100,
  "wallet_type": "TON"
}

Body field	Required	Notes
`username`	Yes	Must match the recipient search.
`recipient_hash`	Yes	Use the latest search response.
`quantity`	Yes	50 to 1,000,000.
`wallet_type`	No	`TON` or `USDT`; defaults to TON.

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "username": "alexdev",
  "quantity": 100,
  "amount": 10.5,
  "created_at": "2026-09-21T10:30:00Z"
}

Telegram Premium gifts

GET

/premium/recipient/search?username={username}&months={months}

Validate eligibility and obtain recipient_hash.

POST

/orders/premium

Queue a Premium gift order.

{
  "username": "alexdev",
  "recipient_hash": "recipient_hash_from_search",
  "months": 3,
  "wallet_type": "USDT"
}

Body field	Required	Notes
`username`	Yes	Telegram username without @.
`recipient_hash`	Yes	Use the latest search response.
`months`	Yes	One of 3, 6, or 12.
`wallet_type`	No	`TON` or `USDT`; defaults to TON.

GET

/premium/packages

List active Premium durations and display pricing with the 5% margin included.

Order status is the source of truth

GET

/orders/{order_id}

Status	Meaning	Action
`pending`	Balance reserved; waiting for processing.	Do not fulfill or retry.
`processing`	Provider or chain confirmation is in progress.	Keep waiting or polling.
`completed`	Gift delivery completed.	Fulfill your customer flow.
`failed`	Order reached a terminal failure.	Inspect error and refund details.

The status response includes amount, timestamps, the original order payload, completed_at when available, and error_message on failure.

Error handling

HTTP	Meaning
`400`	Invalid input, recipient data, wallet type, or order ID.
`401`	API key missing, invalid, expired, revoked, or account inactive.
`400`	Insufficient balance or no active wallet for the selected currency.
`404`	Wallet or order not found for this developer.
`409`	Idempotency key reused with a different payload.
`5xx`	Temporary server or provider failure; retry with the same idempotency key.

{
  "error": "Insufficient wallet balance. Required: 10.500000000 TON, Available: 8.250000000 TON"
}