iStar Developer API Documentation

This documentation describes how to integrate with iStar's API to offer Telegram Stars and Premium Gifts directly from your application.

Authentication
Idempotency
API Endpoints
Webhooks
Error Handling

Authentication

All API requests require an API key that you can obtain from the iStar Developer Dashboard. To authenticate API requests, include your API key in the API-Key header:

API-Key: your_api_key_here

API keys have a configurable expiry and can be revoked at any time from the dashboard.

Note: For v1 testing, use the base URL https://v1.fragmentapi.com/api/v1/partner. For production, use https://v1.fragmentapi.com/api/v1/partner.

Rate Limits: A maximum of 1 request per second is allowed per API key. Exceeding this limit will result in rate-limiting errors.

Idempotency

Always include a unique Idempotency-Key header when creating a Star or Premium order. A UUID is recommended:

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

If a request is retried with the same key and identical order data, the API returns the existing order instead of reserving the wallet balance or sending the blockchain transaction twice. Reusing the key with different data, including a different wallet_type, returns HTTP 409 Conflict.

Keys are scoped to the authenticated developer and may contain up to 128 characters. The optional idempotency_key JSON field is also supported, but the header is recommended.

Payment Currencies

Star and Premium orders accept:

TON for native TON payments.
USDT for official Tether USD on the TON network.

Set wallet_type in the order request to choose the balance to use. If wallet_type is omitted, it defaults to TON for backward compatibility. USDT sent on Ethereum, TRON, or any network other than TON is not supported.

API Endpoints

Star Gifting

Get Star Recipient Information

Before gifting stars, validate the recipient:

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

Parameters:

username: Telegram username of the recipient (without @)
quantity: Number of stars to send (min: 50, max: 1,000,000)

Example:

curl -X GET "https://v1.fragmentapi.com/api/v1/partner/star/recipient/search?username=johndoe&quantity=100"
-H "API-Key: your_api_key_here"

Response:

{
  "success": true,
  "myself": false,
  "recipient": "ABCDEF123456",
  "name": "User's Display Name",
  "photo": "https://path/to/user/photo.jpg"
}

Create Star Gift Order

POST /orders/star

Example:

curl -X POST "https://v1.fragmentapi.com/api/v1/partner/orders/star" 
-H "API-Key: your_api_key_here" 
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000"
-H "Content-Type: application/json" 
-d '{
  "username": "johndoe",
  "recipient_hash": "ABCDEF123456",
  "quantity": 100,
  "wallet_type": "TON"
}'

Response:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "username": "johndoe",
  "quantity": 100,
  "amount": 55.5,
  "created_at": "2025-04-01T12:34:56Z"
}

This endpoint queues the order for processing. A webhook will be sent when the order is completed or fails.

To pay from the developer USDT-on-TON balance, use "wallet_type": "USDT" in the same request.

Premium Gifts

Get Premium Gift Recipient Information

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

Parameters:

username: Telegram username of the recipient (without @)
months: Duration of premium subscription (valid values: 3, 6, 12)

Example:

curl -X GET "https://v1.fragmentapi.com/api/v1/partner/premium/recipient/search?username=johndoe&months=3"
-H "API-Key: your_api_key_here"

Response:

{
  "success": true,
  "myself": false,
  "recipient": "ABCDEF123456",
  "name": "User's Display Name",
  "photo": "https://path/to/user/photo.jpg"
}

Create Premium Gift Order

POST /orders/premium

Example:

curl -X POST "https://v1.fragmentapi.com/api/v1/partner/orders/premium" 
-H "API-Key: your_api_key_here" 
-H "Idempotency-Key: d9428888-122b-11e1-b85c-61cd3cbb3210"
-H "Content-Type: application/json" 
-d '{
  "username": "johndoe",
  "recipient_hash": "ABCDEF123456",
  "months": 3,
  "wallet_type": "TON"
}'

Response:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "username": "johndoe",
  "months": 3,
  "amount": 12.5,
  "created_at": "2025-04-01T12:34:56Z"
}

To pay from the developer USDT-on-TON balance, use "wallet_type": "USDT" in the same request.

Order Status

Webhook delivery is asynchronous. Integrations should also poll the order as a fallback when their webhook endpoint is temporarily unavailable:

GET /orders/{order_id}

curl -X GET "https://v1.fragmentapi.com/api/v1/partner/orders/550e8400-e29b-41d4-a716-446655440000"
-H "API-Key: your_api_key_here"

The response contains the current pending, processing, completed, or failed status, along with the order amount, payload, completion timestamp, and any error message.

Premium Packages

Get current Premium gift package pricing:

GET /premium/packages

Example:

curl -X GET "https://v1.fragmentapi.com/api/v1/partner/premium/packages" 
-H "API-Key: your_api_key_here"

Response:

[
  {
    "months": 3,
    "usd_value": 15.75,
    "ton_value": 8.25
  },
  {
    "months": 6,
    "usd_value": 30.45,
    "ton_value": 16.5
  },
  {
    "months": 12,
    "usd_value": 55.65,
    "ton_value": 32.25
  }
]

Use this endpoint to display current pricing to users before initiating a gift purchase.

Wallet

Get Wallet Balance

Get the current TON balance. Pass wallet_type=USDT to request the USDT-on-TON balance instead:

GET /wallet/balance?wallet_type=TON

Example:

curl -X GET "https://v1.fragmentapi.com/api/v1/partner/wallet/balance?wallet_type=USDT"
-H "API-Key: your_api_key_here"

Response:

{
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "balance": 1250.75,
  "currency": "USDT",
  "updated_at": "2025-04-01T12:34:56Z"
}

Supported values are TON and USDT. If the query parameter is omitted, the endpoint returns the TON balance.

Webhooks

Setting Up Webhooks

Webhooks can be configured in the Developer Dashboard. You can set up to 5 webhook endpoints per developer account.

Each webhook configuration requires:

URL: HTTPS endpoint to receive webhook events
Secret (optional): Used to verify webhook authenticity

Webhook Events

The following events will trigger webhooks:

order.completed: Order has been successfully processed
order.failed: Order has failed after all retry attempts or has expired

Webhook Payload

Example webhook payload:

{
  "event_type": "order.completed",
  "occurred_at": "2025-04-01T12:34:58Z",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "order_type": "star",
    "amount": 55.5,
    "created_at": "2025-04-01T12:34:56Z",
    "updated_at": "2025-04-01T12:34:58Z",
    "payload": {
      "username": "johndoe",
      "recipient": "ABCDEF123456",
      "quantity": 100,
      "completed_at": "2025-04-01T12:34:58Z",
      "tx_hash": "base64_encoded_transaction_hash"
    }
  },
  "tx_hash": "base64_encoded_transaction_hash",
  "completed_at": "2025-04-01T12:34:58Z",
  "quantity": 100
}

For failed orders:

{
  "event_type": "order.failed",
  "occurred_at": "2025-04-01T12:34:58Z",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "order_type": "star",
    "amount": 55.5,
    "created_at": "2025-04-01T12:34:56Z",
    "updated_at": "2025-04-01T12:34:58Z",
    "payload": {
      "username": "johndoe",
      "recipient": "ABCDEF123456",
      "quantity": 100,
      "failed_at": "2025-04-01T12:34:58Z",
      "reason": "Fragment transaction expired"
    }
  },
  "error": "Fragment transaction expired",
  "retry_count": 5,
  "max_retries": 5
}

Webhook Security

To verify webhook authenticity, we include the following headers:

X-iStar-Event: Event type (e.g., order.completed)
X-iStar-Delivery: Unique delivery ID
X-iStar-Attempt: Current delivery attempt number
X-iStar-Signature: HMAC-SHA256 signature (if a secret was configured)

To verify the signature, compute an HMAC-SHA256 hash of the request body using your webhook secret as the key, and compare it to the X-iStar-Signature header value.

Webhook requests time out after 10 seconds. Network errors, 408, 425, 429, and 5xx responses are retried up to three times with exponential backoff. Other 4xx responses are recorded without retry because the receiving endpoint must be corrected.

iStar Developer API Documentation

Table of Contents

Authentication

Idempotency

Payment Currencies

API Endpoints

Star Gifting

Get Star Recipient Information

Create Star Gift Order

Premium Gifts

Get Premium Gift Recipient Information

Create Premium Gift Order

Order Status

Premium Packages

Wallet

Get Wallet Balance

Webhooks

Setting Up Webhooks

Webhook Events

Webhook Payload

Webhook Security