Stars Bot API v1

Minimal, safe API to work with Telegram Stars using your own TON balance. All write operations require an API key and spend the user’s balance.

0. Authentication (API key)

Every /api/v1/* endpoint requires an API key:

curl -X GET "https://fragment-api.work/api/v1/balance" \
  -H "Authorization: Bearer sk_...your_api_key_here..."

1. Get API balance

GET /api/v1/balance

Returns your current API balance in TON.

Request

curl -X GET "https://fragment-api.work/api/v1/balance" \
  -H "Authorization: Bearer sk_...your_api_key_here..."

Response (200)

{
  "balance_ton": 1.234567,
  "currency": "TON"
}

2. Get deposit address (top up)

GET /api/v1/deposit

Returns a TON wallet and memo to top up your API balance.

Request

curl -X GET "https://fragment-api.work/api/v1/deposit" \
  -H "Authorization: Bearer sk_...your_api_key_here..."

Response (200)

{
  "wallet": "UQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "memo": "AP123456789",
  "message": "Send TON to the wallet with this memo (comment) to top up your API balance."
}

3. Buy stars (spend TON balance)

POST /api/v1/buy

Spend your API balance in TON to buy Telegram Stars. You can send to yourself (default) or to another user by specifying to_username.

Body parameters

amount_stars (required) — number of stars to buy.

to_username (optional) — recipient’s Telegram username (e.g. johndoe). If omitted, stars are sent to you. Fragment uses it to look up the user.

Example: send to yourself

curl -X POST "https://fragment-api.work/api/v1/buy" \
  -H "Authorization: Bearer sk_...your_api_key_here..." \
  -H "Content-Type: application/json" \
  -d '{"amount_stars": 100}'

Example: send to another user

curl -X POST "https://fragment-api.work/api/v1/buy" \
  -H "Authorization: Bearer sk_...your_api_key_here..." \
  -H "Content-Type: application/json" \
  -d '{"amount_stars": 100, "to_username": "johndoe"}'

Response (200, delivered)

{
  "status": "ok",
  "order_id": "api_buy_123456789_100_1700000000",
  "amount_stars": 100,
  "to_username": null,
  "message": "Stars sent to your Telegram account."
}

When sending to another user, the response includes "to_username": "johndoe" and the message may be: "Stars sent to @johndoe."

Response (200, manual delivery)

{
  "status": "ok",
  "order_id": "api_buy_123456789_100_1700000000",
  "amount_stars": 100,
  "to_username": "johndoe",
  "message": "Order created. Stars will be delivered manually."
}