# Fragment API

> Fragment API is a production REST API and developer dashboard for purchasing or gifting Telegram Stars and Telegram Premium from backend applications.

Fragment API supports recipient validation, API-key authentication, separate TON and USDT balances on the TON network, idempotent asynchronous orders, order-status polling, and signed webhooks. API access has no setup fee or monthly subscription. Orders use the live provider amount plus a 5% service margin.

## Canonical resources

- [Website](https://www.fragmentapi.com/): Product overview and account access.
- [Quickstart](https://www.fragmentapi.com/docs): First integration from API key to final order state.
- [Telegram Stars API guide](https://www.fragmentapi.com/telegram-stars-api): Recipient search, quantities, orders, retries, and delivery.
- [Telegram Premium API guide](https://www.fragmentapi.com/telegram-premium-api): Packages, eligibility, gift orders, and delivery.
- [Orders API](https://www.fragmentapi.com/docs/orders): Request fields, responses, idempotency, and order states.
- [Pricing](https://www.fragmentapi.com/docs/pricing): 5% margin, VAT guidance, resale pricing, and failed-order balance returns.
- [Wallets and deposits](https://www.fragmentapi.com/docs/wallets): TON and USDT balances on the TON network.
- [Webhooks](https://www.fragmentapi.com/docs/webhooks): Events, signatures, retries, and safe processing.
- [OpenAPI 3.1 specification](https://www.fragmentapi.com/openapi.json): Machine-readable public API contract.
- [Full AI reference](https://www.fragmentapi.com/llms-full.txt): Expanded integration facts and examples.

## API hosts

- Production: `https://v1.fragmentapi.com/api/v1/partner`
- Sandbox: `https://sandbox.fragmentapi.com/api/v1/partner`
- Authentication header: `API-Key: YOUR_API_KEY`

## Core workflow

1. Create an API key in the Fragment API dashboard and fund a TON or USDT balance.
2. Search the Telegram recipient for the chosen product and quantity or duration.
3. Create an order with the returned recipient hash and a unique `Idempotency-Key`.
4. Store the returned `order_id`.
5. Confirm `completed` or `failed` through signed webhooks and order polling.

## Important distinctions

- Fragment API purchases or gifts Stars and Premium to Telegram recipients.
- Accepting Stars as payment inside a Telegram bot or Mini App is a separate Telegram Bot Payments workflow.
- A `202 Accepted` order is not delivered yet; wait for a final order state.
- API keys belong only in server-side code.

## Languages

- English: https://www.fragmentapi.com/
- Russian: https://www.fragmentapi.com/ru
- Uzbek: https://www.fragmentapi.com/uz