TG MARKET — Account & API Docs

🔐 Authentication

All API requests require an API key obtained from the bot (menu → 🔑 API KEY). Include it in the Authorization header.

// Every request must include:
Authorization: Bearer sk-xxxxxxxxxxxxxxxx...

💰 GET /api/v2/balance

GET/api/v2/balance

Returns available, locked, and total balance.

# Example request
curl -X GET https://tg-market.store/api/v2/balance \
  -H "Authorization: Bearer sk-xxx"

// 200 OK { "ok": true, "balance_usd": 25.5, "locked_usd": 2.0, "available_usd": 23.5 }

Status	Error	Description
401	missing_api_key	Authorization header missing
401	invalid_api_key	API key is invalid or inactive
429	rate_limit_exceeded	Too many requests (max 10/sec)
404	user_not_found	User record not found

⭐ POST /api/v2/stars

POST/api/v2/stars

Purchase Telegram Stars for a target username. Optionally wait for completion with ?wait=true.

# Fire-and-forget (returns pending order)
curl -X POST https://tg-market.store/api/v2/stars \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"username":"target","amount":100}'

# Wait for completion (up to 90s)
curl -X POST https://tg-market.store/api/v2/stars?wait=true \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"username":"target","amount":100}'

// 200 OK (pending) { "ok": true, "order_id": 42, "username": "target", "amount": 100, "price_usd": 1.20, "status": "pending", "message": "Order queued..." } // 200 OK (completed with ?wait=true) { "ok": true, "order_id": 42, "status": "completed", "provider_order_id": "abc123", "error_message": null }

Status	Error	Description
400	username_required	Missing target username
400	amount must be int...	Invalid star amount
400	insufficient_balance	Not enough funds in wallet
400	reservation_failed	Fund reservation error
500	order_creation_failed	Internal order creation error
408	timeout	Order did not finish within 90s

⭐ POST /api/v2/premium

POST/api/v2/premium

Purchase Telegram Premium subscription (3, 6, or 12 months). Supports ?wait=true.

# Purchase 3-month Premium
curl -X POST https://tg-market.store/api/v2/premium \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"username":"target","duration":3}'

// 200 OK { "ok": true, "order_id": 15, "username": "target", "duration_months": 3, "price_usd": 12.00, "status": "pending" }

Status	Error	Description
400	duration must be 3, 6, or 12	Invalid duration value
400	insufficient_balance	Not enough funds
400	reservation_failed	Fund reservation error
500	order_creation_failed	Internal order creation error

🔍 GET /api/v2/order/{id}

GET/api/v2/order/{id}

Check the status of a stars order by its ID.

curl -X GET https://tg-market.store/api/v2/order/42 \
  -H "Authorization: Bearer sk-xxx"

Status	Error	Description
404	order_not_found	Order does not exist or doesn't belong to you

🔍 GET /api/v2/premium_order/{id}

GET/api/v2/premium_order/{id}

Check the status of a premium order by its ID.

curl -X GET https://tg-market.store/api/v2/premium_order/15 \
  -H "Authorization: Bearer sk-xxx"

Status	Error	Description
404	order_not_found	Order does not exist or doesn't belong to you

📋 Common Error Codes

Code	Meaning	Typical Cause
400	Bad Request	Invalid JSON, missing fields, insufficient balance
401	Unauthorized	Missing or invalid API key
404	Not Found	Order or user not found
408	Timeout	Order did not complete within 90 seconds (wait mode)
429	Too Many Requests	Rate limit exceeded (10 req/s per key)
500	Internal Server Error	Unexpected server failure