# Fragment Stars API — AI integration context

Fragment Stars API lets backend applications buy Telegram Stars and Telegram
Premium through Fragment.com. Use `https://api.fragment-api.space` for public
HTTP requests and `https://fragment-api.space/en/docs/` for documentation.

## Public contract

Normal public client routes do not require an issued API key, JWT, OAuth token,
or Authorization header. The machine-readable contract is available at
https://fragment-api.space/openapi.yaml.

Current rates:

- KYC: 0% API commission.
- no-KYC: 0.25% API commission.

Verify live rates with:

```bash
curl https://api.fragment-api.space/api/v1/commission/rates
```

Stars purchases start at 50. `payment_method` is optional, defaults to `ton`,
and also accepts `usdt_ton`. Check `GET /api/v1/prices` before presenting a
checkout total.

## Secret handling

`seed`, `fragment_cookies`, and `fragment_local_storage` are backend-only
secrets. Never place them in frontend JavaScript, logs, commits, screenshots,
or public documents. Examples must use these placeholders:

- `YOUR_BASE64_ENCODED_SEED`
- `YOUR_BASE64_ENCODED_COOKIES`
- `YOUR_BASE64_ENCODED_LOCAL_STORAGE`

## Twelve-word wallet accounts

Twelve-word BIP39 seeds use V5R1 accounts derived from
`m/44'/607'/{account_index}'`. Purchase requests support four valid forms:

- `seed` only: account index 0 for a 12-word seed.
- `seed` plus `account_index`: select that account directly.
- `seed` plus `wallet_address`: find the matching common account index.
- `seed` plus both selectors: verify that address and index match.

To find the index for a known address, call backend-only
`POST /api/v1/wallet/resolve` with `seed` and `wallet_address`. Use POST so the
seed never appears in a URL or access log. Pass `account_index` explicitly for
indexes above the common lookup range.

## Direct purchase flows

Prefer these routes for new integrations:

- `POST /api/v1/stars/buy`
- `POST /api/v1/premium/buy`

Example shape for Stars:

```bash
curl -X POST https://api.fragment-api.space/api/v1/stars/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@username",
    "amount": 50,
    "seed": "YOUR_BASE64_ENCODED_SEED",
    "payment_method": "ton"
  }'
```

Example shape for Premium:

```bash
curl -X POST https://api.fragment-api.space/api/v1/premium/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@username",
    "duration": 3,
    "seed": "YOUR_BASE64_ENCODED_SEED",
    "payment_method": "ton"
  }'
```

The legacy create, pay, and order-status routes remain compatibility endpoints;
new clients should use the direct buy flows.

## Queue and errors

Stars purchases can return HTTP 202 with a `request_id`. Poll
`GET /api/v1/queue/{request_id}` until the request is completed, failed, or
timed out.

Respect `Retry-After` for `API_BUSY` and submit a new request only after that
interval. Do not create an automatic purchase retry loop. When a transaction
may have been signed or sent and the final state is unknown, reconcile the
queue response and the calling application's saved order state before any new
purchase attempt.

Common public errors include `VALIDATION_ERROR`, `INVALID_SEED`,
`INVALID_FRAGMENT_COOKIES`, `INVALID_FRAGMENT_LOCAL_STORAGE`,
`INSUFFICIENT_BALANCE`, `RATE_LIMIT_EXCEEDED`, `API_BUSY`, and
`SERVICE_UNAVAILABLE`.

## SDK

```bash
pip install fragment-stars-api
```

```python
from fragment_api import FragmentAPIClient

client = FragmentAPIClient()
rates = client.get_rates()
```

Links:

- SDK source: https://github.com/bbbuilt/fragment-stars-api
- Example shop: https://github.com/bbbuilt/tg_stars_premium_shop
- Russian documentation: https://fragment-api.space/ru/docs/