Telegram Stars API.
Built for your bot.

# /api/v1/purchases; basic backend step, not a persistent shop or bot.
# Only fulfill confirmed paid orders; --create spends real wallet funds.
# Persist purchase_id with your durable SHOP_ORDER_ID before polling.
import json
import os
import re
import sys

SELECTION = {"product":"stars","amount":50,"payment_method":"gram"}

def required(name):
    value = os.environ.get(name, "").strip()
    if not value or value.startswith("<"):
        raise ValueError(f"Set {name} on your trusted backend")
    return value

def order_payload():
    data = dict(SELECTION)
    data["product"] = os.environ.get("PRODUCT", data["product"])
    data["amount"] = int(os.environ.get("AMOUNT", data["amount"]))
    data["payment_method"] = os.environ.get("PAYMENT_METHOD", data["payment_method"])
    data["username"] = required("TELEGRAM_USERNAME")
    data["idempotency_key"] = required("SHOP_ORDER_ID")
    data["seed"] = required("TON_WALLET_SEED")
    if data["product"] not in ("stars", "premium") or data["payment_method"] not in ("gram", "usdt"):
        raise ValueError("Invalid product or payment method")
    if not (50 <= data["amount"] <= 1000000 if data["product"] == "stars" else data["amount"] in (3, 6, 12)):
        raise ValueError("Invalid amount")
    if not re.fullmatch(r"@[A-Za-z0-9_]{1,32}", data["username"]):
        raise ValueError("Invalid Telegram username")
    if not re.fullmatch(r"[\x20-\x7E]{1,128}", data["idempotency_key"]):
        raise ValueError("SHOP_ORDER_ID must be 1..128 printable ASCII characters")
    return data

def execute(test=False):
    from fragment_api import FragmentAPI
    api = FragmentAPI(base_url=os.environ.get("FRAGMENT_API_URL", "https://api-stars.duckdns.org"))
    if test:
        quote = api.get_price("stars", 50)
        return {"prices": {"gram": quote.prices.gram, "usdt": quote.prices.usdt}, "stale": quote.stale}
    data = order_payload()
    public = {key: data[key] for key in ("product", "username", "amount", "payment_method")}
    check = api.check_availability(**public)
    if not check.available:
        raise ValueError("Recipient unavailable; nothing created")
    return api.create_purchase(**data)

if __name__ == "__main__":
    if sys.argv[1:] == ["--dry-run"]:
        # Offline: imports no SDK, reads no credentials, creates no purchase.
        print(json.dumps({"offline": True, **SELECTION}))
    elif sys.argv[1:] in (["--test"], ["--create"]):
        try:
            test = sys.argv[1] == "--test"
            result = execute(test)
            if test:
                print(json.dumps(result))
            else:
                print(result.purchase_id, flush=True)
                print("Persist this purchase_id with SHOP_ORDER_ID before polling.", file=sys.stderr)
        except Exception:
            # Do not log request bodies, wallet credentials, or raw API errors.
            raise SystemExit("Request failed. Check connectivity/setup. For create: reconcile the same order; do not change its key.")
    else:
        raise SystemExit("Use --test for a live price request or --dry-run offline. --create spends real wallet funds; backend only.")

# Template only. Set actual values on your trusted backend; never in this page.
# Keep real .env files out of version control, logs, and frontend bundles.
FRAGMENT_API_URL=https://api-stars.duckdns.org
PRODUCT=stars
AMOUNT=50
PAYMENT_METHOD=gram
TELEGRAM_USERNAME=<TELEGRAM_USERNAME>
# One durable, unique shop order ID per logical order. Reuse it for retries.
SHOP_ORDER_ID=<EXISTING_SHOP_ORDER_ID>
TON_WALLET_SEED=<24_WORD_MNEMONIC>