Sh4de Stars — Developer API

⚡ Quick Start

Top up your balance

Open the bot, go to Balance → Deposit via Binance Pay and add funds in USD.

Create an API key

In the bot menu tap 🔑 API → Create New Key. You can have up to 3 keys.

Start sending requests

Add your key to every request via the X-API-Key header.

BASE URL

Base URL https://docs.sh4de.space

AUTHENTICATION

Include your key in every request:

X-API-Key: sh4de_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Never share your API key. Every request deducts from your bot balance immediately.

📡 Endpoints

GET /api/v1/prices Current prices

Returns current prices for stars and premium. Does not require balance.

GET /api/v1/prices
X-API-Key: sh4de_xxxx

Response

{
  "status": "ok",
  "currency": "USD",
  "stars": {
    "price_per_star": 0.013,
    "min_quantity": 50,
    "example_100": 1.3
  },
  "premium": {
    "3_months": 4.99,
    "6_months": 8.99,
    "12_months": 15.99
  }
}

GET /api/v1/balance Your current balance

GET /api/v1/balance
X-API-Key: sh4de_xxxx

{
  "status": "ok",
  "balance_usd": 25.50,
  "total_orders": 12,
  "total_spent_usd": 8.42,
  "key_label": "My Stars Bot"
}

GET /api/v1/user/{username} Verify a Telegram user

Verifies that a Telegram username exists and can receive Stars or Premium.

GET /api/v1/user/durov
X-API-Key: sh4de_xxxx

POST /api/v1/order/stars Send Stars ⭐

Field	Type	Required	Description
username	string	required	Telegram username (with or without @)
quantity	integer	required	Number of stars — minimum 50

POST /api/v1/order/stars
X-API-Key: sh4de_xxxx
Content-Type: application/json

{
  "username": "some_user",
  "quantity": 100
}

{
  "status": "ok",
  "order_id": 47,
  "username": "some_user",
  "quantity": 100,
  "cost_usd": 1.30,
  "new_balance_usd": 24.20,
  "status_order": "pending",
  "note": "Track: GET /api/v1/order/47"
}

✅ On failure, the deducted balance is automatically refunded.

POST /api/v1/order/premium Gift Premium 💎

Field	Type	Required	Description
username	string	required	Telegram username
months	integer	required	Duration — must be `3`, `6`, or `12`

POST /api/v1/order/premium
X-API-Key: sh4de_xxxx
Content-Type: application/json

{
  "username": "some_user",
  "months": 3
}

GET /api/v1/order/{id} Order status

Returns the current status of an order. Automatically refreshes from upstream if still pending.

GET /api/v1/order/47
X-API-Key: sh4de_xxxx

{
  "status": "ok",
  "order_id": 47,
  "type": "stars",
  "username": "some_user",
  "quantity": 100,
  "cost_usd": 1.30,
  "status": "completed",
  "created_at": "2026-03-28 03:00:00",
  "updated_at": "2026-03-28 03:01:05"
}

pending completed failed

⚠️ Error Reference

HTTP	Code	Meaning
401	MISSING_API_KEY	X-API-Key header not sent
401	INVALID_API_KEY	Key not found in system
403	KEY_DISABLED	Key has been disabled
400	INSUFFICIENT_BALANCE	Not enough balance
400	INVALID_MONTHS	months must be 3, 6, or 12
404	USER_NOT_FOUND	Telegram username not found
404	ORDER_NOT_FOUND	Order ID doesn't exist
403	FORBIDDEN	Order belongs to another key
429	RATE_LIMIT_EXCEEDED	30 req/min exceeded
502	CHARGING_ERROR	Upstream charging error
503	SERVICE_UNAVAILABLE	Service temporarily disabled

{
  "status": "error",
  "code": "INSUFFICIENT_BALANCE",
  "message": "Your balance ($1.20) is less than the order cost ($1.30)."
}

💻 Code Examples

Python

import requests

API_KEY = "sh4de_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE    = "https://docs.sh4de.space"
headers = {"X-API-Key": API_KEY}

# Send 100 Stars
res = requests.post(f"{BASE}/api/v1/order/stars",
    headers=headers,
    json={"username": "some_user", "quantity": 100}
)
data = res.json()
print(data["order_id"], data["status"])

# Check order status
r2 = requests.get(f"{BASE}/api/v1/order/{data['order_id']}", headers=headers)
print(r2.json()["status"])   # pending | completed | failed

Node.js

const BASE    = "https://docs.sh4de.space";
const API_KEY = "sh4de_xxxxxxxxxxxxxxxxxxxxxxxxxxxx";

async function sendStars(username, quantity) {
  const res = await fetch(`${BASE}/api/v1/order/stars`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ username, quantity })
  });
  return res.json();
}

sendStars("some_user", 100).then(console.log);

PHP

$key  = "sh4de_xxxxxxxxxxxxxxxxxxxxxxxxxxxx";
$base = "https://docs.sh4de.space";

$ch = curl_init("$base/api/v1/order/stars");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: $key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode(["username" => "some_user", "quantity" => 100]),
]);
$res = json_decode(curl_exec($ch), true);
echo $res['order_id'];