YuDropYuDrop

Partner API

Buy Telegram Stars and Premium for the customers of your shop, bot or site over HTTP. The money is taken from your YuDrop wallet at once; delivery is automatic as usual.

Getting access

  • Partnerships are agreed with the shop: write to the support chat — your discount and daily limit are set.
  • The bot sends you the key (yd_live_…) and the webhook secret. /partner in the bot shows your status.
  • Top up the wallet in the app as usual; every order costs the base price minus your discount.

Authentication

Send Authorization: Bearer <key> with every request. Never share the key — it buys from your wallet. Need a new one? Ask the shop: the old key stops working at once.

https://tgstars.uz/partner/v1

Endpoints

GET/partner/v1/me

You: balance, discount, today's purchases and limit, webhook.

GET/partner/v1/prices

Your prices: the price of one Star, examples, Premium periods.

POST/partner/v1/recipient

Check a recipient: {"product", "username"}.

POST/partner/v1/orders

Order: {"product", "recipient", "quantity" | "months", "ref", "expected_amount"?}.

GET/partner/v1/orders

Your orders: ?limit=1..100&before=<id>.

GET/partner/v1/orders/{id}

An order's status.

GET/partner/v1/orders/ref/{ref}

An order by your ref.

POST/partner/v1/orders/{id}/refund

Refund a late order into the wallet.

POST/partner/v1/webhook

Webhook URL: {"url": "https://…" | null, "rotate_secret"?: true}.

Placing an order

Stars: quantity 50…100000; Premium: months 3, 6, 12. ref is your own order id (1–64 characters): a repeated request with the same ref returns the same order and never buys twice (200, created: false). The same ref with another product, recipient or quantity is refused with 409 ref_conflict. expected_amount is the most you expect to pay: a higher price creates nothing (409 quote_changed). The recipient is checked with Fragment before any money moves.

curl -X POST https://tgstars.uz/partner/v1/orders \
  -H "Authorization: Bearer yd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"product": "stars", "recipient": "@username", "quantity": 100, "ref": "shop-order-1001"}'

HTTP/1.1 201 Created
{"order": {"id": 1234, "ref": "shop-order-1001", "product": "stars", "recipient": "username", "quantity": 100,
  "amount": 22000, "currency": "UZS", "status": "processing", "created_at": "2026-10-28T12:00:00Z",
  "paid_at": "2026-10-28T12:00:00Z", "delivered_at": null}, "created": true}

Statuses

processing

Paid, being delivered (usually within minutes).

delivered

Delivered.

cancelled

Cancelled; with refunded: true the money is back in the wallet. reason: recipient_not_found / already_premium / recipient_restricted (fix the recipient and order again with a new ref), refunded (a late order you refunded) or cancelled.

expired / pending

An order whose payment did not finish (rare: e.g. a request cut off). Send the same ref again and the payment completes.

Errors

Body: {"error": "code", "message": "…"}. 400 bad request · 401 missing or wrong key · 402 not enough money in the wallet (wallet_low) · 403 paused or over the daily limit · 404 not found (recipient_not_found too) · 409 ref_conflict / quote_changed / refund_too_early · 422 already_premium · 429 too many requests (Retry-After) · 503 temporarily unavailable.

Webhooks

Events: order.delivered, order.cancelled, order.expired, order.delayed (paid but late — /refund is possible). Body: JSON {"id", "event", "created_at", "order": {…}}. Signature: X-YuDrop-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>. Until a 2xx answer it is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h; an event may arrive more than once — drop repeats by X-YuDrop-Delivery (id). https on public hosts only; redirects are not followed.

Verifying the signature (Python)

import hashlib, hmac, time

def verified(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    stamp, signature = parts.get("t", ""), parts.get("v1", "")
    expected = hmac.new(secret.encode(), stamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature) and abs(time.time() - int(stamp or 0)) <= tolerance

Limits

Per key: 120 reads and 60 writes a minute (bursts of 120 / 30). Per address: 20 attempts with a wrong key a minute.