# Fragment Stars API - Full AI Integration Context

Fragment Stars API lets backend applications buy Telegram Stars and Telegram Premium subscriptions through Fragment.com using TON wallets.

Documentation site: https://wemakecode.ru/fragment-api
Production API endpoint: https://fragment-api.ydns.eu:8443
OpenAPI spec: https://wemakecode.ru/fragment-api/openapi.yaml
Python SDK: https://pypi.org/project/fragment-stars-api/
GitHub SDK repo: https://github.com/bbbuilt/fragment-stars-api
Example Telegram shop: https://github.com/bbbuilt/tg_stars_premium_shop

## Authentication And Access

Normal client API calls do not need issued API tokens.

Do not add or ask for:

- X-API-Key for normal client endpoints
- Authorization headers
- JWT
- OAuth
- API-token issuance flow

Admin routes are separate from client routes. Admin routes use X-Admin-Key and are not needed for normal Stars or Premium purchases.

## Production Endpoint

Use this base URL for direct HTTP requests:

```text
https://fragment-api.ydns.eu:8443
```

Use HTTPS only.

## Purchase Modes

### KYC mode

KYC mode is permanently free with 0% API commission.

The client provides their own Fragment session data:

- fragment_cookies
- optionally fragment_local_storage

The purchase is made through the client's Fragment account. The API still needs the wallet seed to sign the TON transaction.

### Non-KYC mode

The client does not provide Fragment cookies. The API uses the service owner's Fragment cookies. Commission is configured by the service.

Clients can verify current rates with:

```bash
curl https://fragment-api.ydns.eu:8443/api/v1/commission/rates
```

or SDK:

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

## Security Rules

- Wallet seed must stay on the backend/server side.
- Fragment cookies and localStorage must stay on the backend/server side.
- Never put seeds, cookies, or localStorage in frontend JavaScript.
- Never commit real seeds, cookies, localStorage, API admin keys, or wallet secrets to git.
- Do not log seeds, cookies, or localStorage.
- Show errors to admins/operators without leaking secrets.
- Use placeholders in examples, tests, docs, and screenshots.

## Python SDK

Install:

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

Create client:

```python
from fragment_api import FragmentAPIClient

client = FragmentAPIClient("https://fragment-api.ydns.eu:8443")
```

Buy Stars:

```python
result = client.buy_stars(
    username="username",
    amount=50,
    seed="BASE64_WALLET_SEED",
    cookies="BASE64_FRAGMENT_COOKIES",
)
```

Buy Premium:

```python
result = client.buy_premium(
    username="username",
    duration=3,
    seed="BASE64_WALLET_SEED",
    cookies="BASE64_FRAGMENT_COOKIES",
)
```

Check rates:

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

Check queue:

```python
status = client.get_queue_status()
```

## Direct REST Examples

Buy Stars:

```bash
curl -X POST https://fragment-api.ydns.eu:8443/api/v1/stars/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@username",
    "amount": 50,
    "seed": "BASE64_WALLET_SEED",
    "fragment_cookies": "BASE64_FRAGMENT_COOKIES"
  }'
```

Buy Premium:

```bash
curl -X POST https://fragment-api.ydns.eu:8443/api/v1/premium/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "@username",
    "duration": 3,
    "seed": "BASE64_WALLET_SEED",
    "fragment_cookies": "BASE64_FRAGMENT_COOKIES"
  }'
```

Check rates:

```bash
curl https://fragment-api.ydns.eu:8443/api/v1/commission/rates
```

Check queue request:

```bash
curl https://fragment-api.ydns.eu:8443/api/v1/queue/{request_id}
```

## Queue Behavior

Stars purchases are queued. POST /api/v1/stars/buy may return HTTP 202 with request_id. Poll:

```text
GET /api/v1/queue/{request_id}
```

Stop polling on completed, failed, or timeout.

Premium usually returns the final result directly, but integrations should still handle API errors carefully.

## Duplicate Purchase Prevention

Never blindly retry purchase requests after any of these events:

- transaction hash returned
- transaction signing started
- transaction was sent
- network error happened after signing/sending
- order state is unknown

Instead, check queue status, wallet transaction history, saved shop order state, or ask an operator. Blind retries can buy Stars or Premium twice.

At the shop/bot level, implement idempotency: one paid customer order must map to one Fragment purchase attempt.

## Common Errors

USER_NOT_FOUND: Fragment/Telegram did not find the username. Ask user to verify the username.

INVALID_SEED: seed is missing, malformed, not base64, or unsupported.

INVALID_COOKIES: Fragment cookies/localStorage are invalid, malformed, or expired.

INSUFFICIENT_BALANCE: wallet lacks TON for purchase plus gas.

RATE_LIMIT_EXCEEDED: slow down requests.

FRAGMENT_ERROR or 5xx: external Fragment/TON provider issue. Do not retry if a transaction may already have been sent.

Failed to get wallet seqno: TON provider/wallet state issue. Do not blindly retry if transaction signing/sending may have started.

page.goto timeout or Execution context was destroyed: browser automation/navigation issue inside the API. Treat as external/temporary unless transaction was already sent.

Could not capture req_id: Fragment page/API did not produce the expected request id. Do not retry automatically if the flow might have progressed to signing/sending.

## AI Agent Implementation Checklist

1. Store FRAGMENT_API_URL=https://fragment-api.ydns.eu:8443 in backend config.
2. Keep wallet seed and Fragment session data backend-only.
3. Prefer the Python SDK for Python bots/backends.
4. Use direct REST for other stacks.
5. Do not add API-key auth to normal client API calls.
6. Add shop-level idempotency and a persisted order state machine.
7. Poll queued Stars purchases until completed, failed, or timeout.
8. Surface API errors clearly to admins/operators.
9. Never leak secrets in logs, commits, screenshots, or frontend bundles.
10. Link users to the cookie guide when enabling KYC mode.