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.

    Table of Contents

    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 sandbox testing, use the base URL https://sandbox.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.

    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://sandbox.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://sandbox.fragmentapi.com/api/v1/partner/orders/star" 
-H "API-Key: your_api_key_here" 
-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.

    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://sandbox.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 "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"
}

    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 balance of your TON wallet:

    GET /wallet/balance

    Example:

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

    Response:

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

    This endpoint provides the current balance of your TON wallet.

    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-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.