Dashboard

API Key: hp_****
TON Balance
0.000
Total Orders
0
Stars Sold
0
Premium Sold
0

Recent Transactions

IDTypeRecipientQtyPrice (TON)Status
Loading...

All Orders

Order IDService TypeTarget UserAmountCostStatusDate
Loading...

Hyperpin API Reference

Welcome to the Hyperpin API. This API enables you to programmatically buy Telegram Stars, Premium subscriptions, and Gifts. It is designed for seamless integration into your bots and apps. The system automatically calculates and deducts the equivalent cost in TON from your Developer Balance. All responses are returned in JSON format.

Base URL: https://hyperpin.top/api/v1
Content-Type: application/json

Authentication

Security is handled via the X-API-Key header. You must pass this header in every request to authenticate your account. Keep your API key secret and do not share it publicly.

X-API-Key: hp_your_secret_api_key_here

⚡ Rate Limiting

Each API key is limited to 60 requests per minute. If exceeded, the API returns 429 Too Many Requests. The limit resets automatically after 60 seconds.

// 429 Response { "detail": { "error": "Rate limit exceeded. Max 60 req/min.", "code": "rate_limit_exceeded" } }

🔁 Idempotency Key

To prevent duplicate purchases (e.g. from network retries), include a unique X-Idempotency-Key header on buy requests. If you repeat the same key within 24 hours, the original response is returned — no duplicate charge.

// Header X-Idempotency-Key: order-user123-1717200000 // Tip: use a UUID or {user_id}-{timestamp} as the key

Webhooks (Real-Time Updates)

Provide a response_url in buy requests. When the transaction completes, we POST the result to your URL. Optionally pass webhook_secret to receive an HMAC-SHA256 signature in the X-Hyperpin-Signature header for verification.

// Verify webhook in Python import hmac, hashlib, json def verify(body: dict, secret: str, signature: str) -> bool: payload = json.dumps(body, sort_keys=True, separators=(',', ':')) expected = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)
GET /user-info?username=durov
POST /user-info

Verify a user before purchasing. Returns name, photo, and premium status.

// GET (simple) GET /api/v1/user-info?username=durov // POST (body) { "username": "durov" } // Response { "username": "durov", "name": "Pavel Durov", "has_premium": true }
GET /stars/price?username=durov&quantity=100
POST /stars/price

Real-time TON price for Stars from Fragment.

// Response { "username": "durov", "quantity": 100, "price_ton": "0.7706", "fee_ton": "0.015412", "total_ton": "0.786012", "currency": "TON", "commission_rate": "2%" }
POST /stars/buy

Purchase Telegram Stars. Minimum 50. TON deducted instantly; refunded if Fragment fails.

// Request { "username": "durov", "quantity": 100, "response_url": "https://your-site.com/webhook", // optional "webhook_secret": "my-secret" // optional } // Header (optional, prevents duplicate charge) X-Idempotency-Key: order-abc-123 // Response { "success": true, "id": "42", "receiver": "durov", "goods_quantity": 100, "type": "stars", "ton_price": "0.7706", "fee_ton": "0.015412", "total_ton": "0.786012", "status": "completed" }
POST /premium/buy

Gift Premium. months: 3, 6, or 12 only.

{ "username": "durov", "months": 3, "response_url": "https://your-site.com/webhook" }
POST /gift/buy

Send a Telegram Gift by gift_id and stars_cost.

{ "username": "durov", "gift_id": 12345, "stars_cost": 50, "message": "Happy Birthday!" // Optional }
GET /order/{order_id}

Get a single order. Status: pending | completed | failed.

GET /orders

Paginated order history with optional filters.

GET /api/v1/orders?limit=20&offset=0&status=completed&type=stars // Response { "orders": [ { "id": "42", "type": "stars", ... } ], "count": 20, "limit": 20, "offset": 0 }
GET /balance

Your current TON developer balance.

{ "balance": "1.234500", "currency": "TON", "user_id": "123" }
GET /account/deposit

Get the TON wallet address to top up your API balance. Send TON to this address.

{ "address": "UQ...", "currency": "TON", "network": "TON", "your_current_balance": "0.500000" }
POST /account/rotate-key

Generate a new API key. The old key is immediately revoked.

{ "success": true, "api_key": "hp_new_key_here" }
GET /prices

Public endpoint. Real-time TON rates for Stars and Premium from Fragment (no auth required).

{ "star_rate": "0.007706", "stars": [ { "quantity": 50, "price": "0.3853" }, { "quantity": 100, "price": "0.7706" }, ... ], "premium": [ { "months": 3, "price": "8.18" }, ... ] }

📜 Audit Logs

Access your request history for debugging and security auditing.

🔔 Webhook Events

List of all possible events sent to your response_url.

Common Errors

All errors: {"detail": {"error": "...", "code": "..."}}

401 — Invalid X-API-Key
429 — rate_limit_exceeded — 60 req/min exceeded
400 — insufficient_balance — Not enough TON
400 — invalid_quantity — Stars < 50
404 — user_not_found — Username not found
503 — service_unavailable — Fragment/Telegram error

Users
0
Total Sales
0 so'm
Today Orders
0
Pending
0
⏳ Prices loading...

📢 Broadcast

📤 Export Data

💰 TON Wallet Transactions

⏳ Loading...

📋 Admin Activity Log

⏳ Loading...

💰 UZS Narxlar

⚡ API Komissiya foizi

%