# Stard API documentation > Developer documentation for the Stard Market API (Telegram Stars, Premium, gifts, usernames, +888 numbers; prices in toman/TON). Persian (fa) documentation, server-rendered HTML; Markdown twin of every page linked below. Stard API is the official REST/JSON API of Stard Market (stard-market.ir), an Iranian marketplace for Telegram Stars, Telegram Premium, Telegram gifts/NFTs, usernames and anonymous +888 numbers, priced in Iranian toman (IRT) and TON. The same order engine that serves the Telegram bot @Stard_marketbot and the Mini App fulfils API orders. Key facts: - Base URL: `https://stard-market.ir/api/v1` — JSON only, UTF-8. OpenAPI 3 spec: https://stard-market.ir/api/v1/openapi.json - Auth: `Authorization: Bearer sk_test_…` (sandbox, free simulated balance, no real money) or `Bearer sk_live_…` (live, debits the linked Stard account's API wallet in TON or toman). Keys are created in the dashboard: https://stard-market.ir/developers/dashboard - Keys carry scopes: `products:read`, `prices:read`, `orders:read`, `orders:write`, `wallet:read`, `webhooks:read` (default set) and opt-in `wallet:write` (toman↔TON conversion, TON withdrawal to the linked TON Connect wallet only). - Idempotency: send `Idempotency-Key` (≤64 chars) on every POST that creates an order; a retry with the same key returns the original response and never charges twice; reusing a key with a different body → `409 idempotency_key_reused`. - Errors: JSON body `{"error": {"type", "code", "message" (fa), "message_en", "param", "request_id"}}`; branch on `code`; with HTTP status 400/401/402/403/404/409/429/5xx. See /docs/errors. - Rate limits: default 60 requests/minute per key (order creation 20/min); `X-RateLimit-*` headers, `Retry-After` on 429. - Pagination: `limit` (1–100, default 20) + `offset`; responses include `has_more` / `next_offset`. - Webhooks: signed POSTs with headers `Stard-Event`, `Stard-Event-Id`, `Stard-Signature: t=,v1=`; v1 = HMAC-SHA256 of `"."` keyed with the endpoint secret (`whsec_…`). Reject timestamps older than 5 minutes. - Amounts: toman as integers; TON as exact decimal strings with 9 decimals (never floats). - Documentation language: Persian (fa). Every page has a Markdown twin: append `.md` to the URL (root: /docs/index.md). ## Machine-readable - [Full documentation in one Markdown file](https://stard-market.ir/docs/llms-full.txt) - [OpenAPI 3 JSON](https://stard-market.ir/api/v1/openapi.json) - [Docs sitemap](https://stard-market.ir/developers/sitemap.xml) - [Site-wide llms.txt (company facts, products, prices)](https://stard-market.ir/llms.txt) ## Endpoints | Method | Path | Scope | Docs (fa) | |---|---|---|---| | GET | `/api/v1/ping` | — | [بررسی کلید](https://stard-market.ir/docs/reference/ping.md) | | GET | `/api/v1/categories` | `products:read` | [دسته‌های محصول](https://stard-market.ir/docs/reference/categories.md) | | GET | `/api/v1/products` | `products:read` | [فهرست محصولات](https://stard-market.ir/docs/reference/products-list.md) | | GET | `/api/v1/products/{category}` | `products:read` | [محصولات یک دسته](https://stard-market.ir/docs/reference/products-category.md) | | GET | `/api/v1/products/{id}` | `products:read` | [یک محصول](https://stard-market.ir/docs/reference/product-get.md) | | GET | `/api/v1/products/tag/{tag}` | `products:read` | [محصول با تگ](https://stard-market.ir/docs/reference/product-tag.md) | | GET | `/api/v1/products/{id}/price` | `prices:read` | [قیمت لحظه‌ای یک محصول](https://stard-market.ir/docs/reference/product-price.md) | | GET | `/api/v1/prices` | `prices:read` | [قیمت استارز، TON و دلار](https://stard-market.ir/docs/reference/prices.md) | | GET | `/api/v1/stars/price` | `prices:read` | [قیمت خرید استارز](https://stard-market.ir/docs/reference/stars-price.md) | | GET | `/api/v1/premium/prices` | `prices:read` | [قیمت تلگرام پریمیوم](https://stard-market.ir/docs/reference/premium-prices.md) | | GET | `/api/v1/marketplace` | `products:read` | [آمار بازار](https://stard-market.ir/docs/reference/marketplace.md) | | GET | `/api/v1/auctions` | `products:read` | [مزایده‌های فعال](https://stard-market.ir/docs/reference/auctions.md) | | GET | `/api/v1/auctions/{id}` | `products:read` | [یک مزایده](https://stard-market.ir/docs/reference/auction.md) | | GET | `/api/v1/auctions/{id}/bids` | `products:read` | [پیشنهادهای یک مزایده](https://stard-market.ir/docs/reference/auction-bids.md) | | POST | `/api/v1/orders` | `orders:write` | [ثبت سفارش](https://stard-market.ir/docs/reference/orders-create.md) | | GET | `/api/v1/orders` | `orders:read` | [فهرست سفارش‌ها](https://stard-market.ir/docs/reference/orders-list.md) | | GET | `/api/v1/orders/{id}` | `orders:read` | [یک سفارش](https://stard-market.ir/docs/reference/orders-get.md) | | POST | `/api/v1/orders/{id}/cancel` | `orders:write` | [لغو سفارش](https://stard-market.ir/docs/reference/orders-cancel.md) | | GET | `/api/v1/wallet` | `wallet:read` | [موجودی کیف پول](https://stard-market.ir/docs/reference/wallet.md) | | GET | `/api/v1/transactions` | `wallet:read` | [تراکنش‌ها](https://stard-market.ir/docs/reference/transactions.md) | | POST | `/api/v1/orders/quote` | `prices:read` | [پیش‌قیمت سفارش](https://stard-market.ir/docs/reference/orders-quote.md) | | POST | `/api/v1/orders/{id}/refund` | `orders:write` | [بازپرداخت سفارش](https://stard-market.ir/docs/reference/orders-refund.md) | | GET | `/api/v1/orders/{id}/refund` | `orders:read` | [وضعیت بازپرداخت](https://stard-market.ir/docs/reference/orders-refund-status.md) | | GET | `/api/v1/boosts` | `prices:read` | [بوست کانال: مدت‌ها و قیمت](https://stard-market.ir/docs/reference/boosts.md) | | GET | `/api/v1/boosts/price` | `prices:read` | [قیمت دقیق بوست](https://stard-market.ir/docs/reference/boosts-price.md) | | POST | `/api/v1/boosts/orders` | `orders:write` | [ثبت سفارش بوست](https://stard-market.ir/docs/reference/boosts-order.md) | | GET | `/api/v1/boosts/orders/{id}` | `orders:read` | [وضعیت سفارش بوست](https://stard-market.ir/docs/reference/boosts-order-get.md) | | GET | `/api/v1/gifts` | `products:read` | [گیفت‌های استارزی](https://stard-market.ir/docs/reference/gifts.md) | | POST | `/api/v1/gifts/send` | `orders:write` | [ارسال گیفت به یوزرنیم](https://stard-market.ir/docs/reference/gifts-send.md) | | GET | `/api/v1/gifts/orders/{id}` | `orders:read` | [وضعیت ارسال گیفت](https://stard-market.ir/docs/reference/gifts-order-get.md) | | GET | `/api/v1/usernames/check` | `products:read` | [بررسی یوزرنیم](https://stard-market.ir/docs/reference/usernames-check.md) | | GET | `/api/v1/usernames/{username}` | `products:read` | [یک یوزرنیم](https://stard-market.ir/docs/reference/username-get.md) | | GET | `/api/v1/listings` | `products:read` | [آگهی‌های بازار P2P](https://stard-market.ir/docs/reference/listings.md) | | GET | `/api/v1/nfts/{slug}/history` | `products:read` | [سابقه‌ی فروش NFT](https://stard-market.ir/docs/reference/nft-history.md) | | GET | `/api/v1/nfts/collections/{slug}/stats` | `products:read` | [آمار کالکشن NFT](https://stard-market.ir/docs/reference/nft-collection-stats.md) | | GET | `/api/v1/market/stats` | `products:read` | [آمار بازار گیفت‌ها](https://stard-market.ir/docs/reference/market-stats.md) | | GET | `/api/v1/prices/history` | `prices:read` | [تاریخچه‌ی قیمت استارز](https://stard-market.ir/docs/reference/prices-history.md) | | GET | `/api/v1/products/{id}/price-history` | `prices:read` | [تاریخچه‌ی قیمت محصول](https://stard-market.ir/docs/reference/product-price-history.md) | | POST | `/api/v1/price-alerts` | `prices:read` | [ساخت هشدار قیمت](https://stard-market.ir/docs/reference/price-alerts-create.md) | | GET | `/api/v1/price-alerts` | `prices:read` | [فهرست هشدارها](https://stard-market.ir/docs/reference/price-alerts-list.md) | | DELETE | `/api/v1/price-alerts/{id}` | `prices:read` | [حذف هشدار](https://stard-market.ir/docs/reference/price-alerts-delete.md) | | POST | `/api/v1/wallet/topups` | `wallet:read` | [شارژ موجودی TON](https://stard-market.ir/docs/reference/wallet-topup.md) | | GET | `/api/v1/wallet/topups/{id}` | `wallet:read` | [وضعیت شارژ TON](https://stard-market.ir/docs/reference/wallet-topup-get.md) | | GET | `/api/v1/status` | — | [وضعیت سرویس‌ها](https://stard-market.ir/docs/reference/status.md) | | POST | `/api/v1/test/orders/{id}/simulate` | `orders:write` | [شبیه‌سازی نتیجه‌ی سفارش (test)](https://stard-market.ir/docs/reference/test-simulate.md) | | GET | `/api/v1/services` | `prices:read` | [فهرست خدمات کانال](https://stard-market.ir/docs/reference/services.md) | | GET | `/api/v1/services/{service}` | `prices:read` | [یک خدمت](https://stard-market.ir/docs/reference/service-get.md) | | GET | `/api/v1/services/reactions/options` | `prices:read` | [ری‌اکشن‌های قابل سفارش](https://stard-market.ir/docs/reference/services-reactions.md) | | GET | `/api/v1/services/{service}/options` | `prices:read` | [گزینه‌های خدمت](https://stard-market.ir/docs/reference/service-options.md) | | GET | `/api/v1/services/{service}/price` | `prices:read` | [قیمت دقیق خدمت](https://stard-market.ir/docs/reference/service-price.md) | | POST | `/api/v1/services/post-info` | `prices:read` | [اطلاعات و ری‌اکشن‌های پست](https://stard-market.ir/docs/reference/service-post-info.md) | | POST | `/api/v1/services/orders` | `orders:write` | [ثبت سفارش خدمت کانال](https://stard-market.ir/docs/reference/service-order.md) | | GET | `/api/v1/services/orders/{id}` | `orders:read` | [وضعیت سفارش خدمت](https://stard-market.ir/docs/reference/service-order-get.md) | | GET | `/api/v1/star-reactions/quote` | `prices:read` | [قیمت ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-quote.md) | | GET | `/api/v1/star-reactions/check` | `prices:read` | [بررسی پست برای ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-check.md) | | POST | `/api/v1/star-reactions/orders` | `orders:write` | [ثبت سفارش ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-order.md) | | GET | `/api/v1/star-reactions/orders/{id}` | `orders:read` | [وضعیت سفارش ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-order-get.md) | | POST | `/api/v1/services/members/invite` | `orders:write` | [ممبر با ادمین کردن ربات](https://stard-market.ir/docs/reference/members-invite.md) | | GET | `/api/v1/services/members/invite/{token}` | `orders:read` | [وضعیت ممبر با ربات](https://stard-market.ir/docs/reference/members-invite-get.md) | | GET | `/api/v1/services/orders/{id}/members` | `orders:read` | [آمار اعضای سفارش ممبر](https://stard-market.ir/docs/reference/service-order-members.md) | | GET | `/api/v1/ton/rate` | `prices:read` | [نرخ TON](https://stard-market.ir/docs/reference/ton-rate.md) | | GET | `/api/v1/wallet/convert/quote` | `wallet:read` | [پیش‌نمایش تبدیل تومان ↔ TON](https://stard-market.ir/docs/reference/wallet-convert-quote.md) | | POST | `/api/v1/wallet/convert` | `wallet:write` | [تبدیل تومان ↔ TON](https://stard-market.ir/docs/reference/wallet-convert.md) | | GET | `/api/v1/wallet/ton/withdrawals/quote` | `wallet:read` | [پیش‌نمایش برداشت TON](https://stard-market.ir/docs/reference/ton-withdraw-quote.md) | | POST | `/api/v1/wallet/ton/withdrawals` | `wallet:write` | [برداشت TON](https://stard-market.ir/docs/reference/ton-withdraw.md) | | GET | `/api/v1/wallet/ton/withdrawals` | `wallet:read` | [برداشت‌های TON](https://stard-market.ir/docs/reference/ton-withdrawals.md) | | GET | `/api/v1/ton/sell/quote` | `prices:read` | [قیمت فروش TON (کیف به کیف / کیف پول تلگرام)](https://stard-market.ir/docs/reference/ton-sell-quote.md) | | POST | `/api/v1/ton/sell` | `ton:send` | [فروش و ارسال TON](https://stard-market.ir/docs/reference/ton-sell.md) | | GET | `/api/v1/ton/sell` | `wallet:read` | [ارسال‌های TON](https://stard-market.ir/docs/reference/ton-sell-list.md) | | GET | `/api/v1/ton/sell/{sell_id}` | `wallet:read` | [یک ارسال TON](https://stard-market.ir/docs/reference/ton-sell-get.md) | | POST | `/api/v1/auctions/{product_id}/bids` | `orders:write` | [پیشنهاد روی مزایده یا آگهی توافقی](https://stard-market.ir/docs/reference/auction-bid.md) | | POST | `/api/v1/orders/{id}/finalize` | `orders:write` | [خرید P2P: پرداخت و شروع امانت](https://stard-market.ir/docs/reference/order-finalize.md) | | POST | `/api/v1/orders/{id}/receipt` | `orders:write` | [خرید P2P: تایید یا رد دریافت](https://stard-market.ir/docs/reference/order-receipt.md) | ## شروع - [معرفی](https://stard-market.ir/docs/index.md) - [شروع سریع](https://stard-market.ir/docs/getting-started.md) - [احراز هویت](https://stard-market.ir/docs/authentication.md) - [کلیدهای API](https://stard-market.ir/docs/api-keys.md) - [محیط test و live](https://stard-market.ir/docs/sandbox.md) ## مفاهیم - [خطاها](https://stard-market.ir/docs/errors.md) - [محدودیت نرخ](https://stard-market.ir/docs/rate-limits.md) - [Idempotency](https://stard-market.ir/docs/idempotency.md) - [صفحه‌بندی](https://stard-market.ir/docs/pagination.md) - [امنیت](https://stard-market.ir/docs/security.md) ## ابزار - [وب‌هوک‌ها](https://stard-market.ir/docs/webhooks.md) - [SDKها](https://stard-market.ir/docs/sdks.md) - [ربات فروشگاهی آماده](https://stard-market.ir/docs/shop-bot.md) ## راهنما - [محصولات](https://stard-market.ir/docs/products.md) - [استارز تلگرام](https://stard-market.ir/docs/products/stars.md) - [تلگرام پریمیوم](https://stard-market.ir/docs/products/premium.md) - [گیفت‌ها و NFT](https://stard-market.ir/docs/products/gifts.md) - [یوزرنیم و شماره](https://stard-market.ir/docs/products/usernames.md) - [قیمت‌ها](https://stard-market.ir/docs/prices.md) - [سفارش و خرید](https://stard-market.ir/docs/orders.md) - [کیف پول و تراکنش](https://stard-market.ir/docs/wallet.md) ## مرجع API - [بررسی کلید](https://stard-market.ir/docs/reference/ping.md) - [دسته‌های محصول](https://stard-market.ir/docs/reference/categories.md) - [فهرست محصولات](https://stard-market.ir/docs/reference/products-list.md) - [محصولات یک دسته](https://stard-market.ir/docs/reference/products-category.md) - [یک محصول](https://stard-market.ir/docs/reference/product-get.md) - [محصول با تگ](https://stard-market.ir/docs/reference/product-tag.md) - [قیمت لحظه‌ای یک محصول](https://stard-market.ir/docs/reference/product-price.md) - [قیمت استارز، TON و دلار](https://stard-market.ir/docs/reference/prices.md) - [قیمت خرید استارز](https://stard-market.ir/docs/reference/stars-price.md) - [قیمت تلگرام پریمیوم](https://stard-market.ir/docs/reference/premium-prices.md) - [آمار بازار](https://stard-market.ir/docs/reference/marketplace.md) - [مزایده‌های فعال](https://stard-market.ir/docs/reference/auctions.md) - [یک مزایده](https://stard-market.ir/docs/reference/auction.md) - [پیشنهادهای یک مزایده](https://stard-market.ir/docs/reference/auction-bids.md) - [ثبت سفارش](https://stard-market.ir/docs/reference/orders-create.md) - [فهرست سفارش‌ها](https://stard-market.ir/docs/reference/orders-list.md) - [یک سفارش](https://stard-market.ir/docs/reference/orders-get.md) - [لغو سفارش](https://stard-market.ir/docs/reference/orders-cancel.md) - [موجودی کیف پول](https://stard-market.ir/docs/reference/wallet.md) - [تراکنش‌ها](https://stard-market.ir/docs/reference/transactions.md) - [پیش‌قیمت سفارش](https://stard-market.ir/docs/reference/orders-quote.md) - [بازپرداخت سفارش](https://stard-market.ir/docs/reference/orders-refund.md) - [وضعیت بازپرداخت](https://stard-market.ir/docs/reference/orders-refund-status.md) - [بوست کانال: مدت‌ها و قیمت](https://stard-market.ir/docs/reference/boosts.md) - [قیمت دقیق بوست](https://stard-market.ir/docs/reference/boosts-price.md) - [ثبت سفارش بوست](https://stard-market.ir/docs/reference/boosts-order.md) - [وضعیت سفارش بوست](https://stard-market.ir/docs/reference/boosts-order-get.md) - [گیفت‌های استارزی](https://stard-market.ir/docs/reference/gifts.md) - [ارسال گیفت به یوزرنیم](https://stard-market.ir/docs/reference/gifts-send.md) - [وضعیت ارسال گیفت](https://stard-market.ir/docs/reference/gifts-order-get.md) - [بررسی یوزرنیم](https://stard-market.ir/docs/reference/usernames-check.md) - [یک یوزرنیم](https://stard-market.ir/docs/reference/username-get.md) - [آگهی‌های بازار P2P](https://stard-market.ir/docs/reference/listings.md) - [سابقه‌ی فروش NFT](https://stard-market.ir/docs/reference/nft-history.md) - [آمار کالکشن NFT](https://stard-market.ir/docs/reference/nft-collection-stats.md) - [آمار بازار گیفت‌ها](https://stard-market.ir/docs/reference/market-stats.md) - [تاریخچه‌ی قیمت استارز](https://stard-market.ir/docs/reference/prices-history.md) - [تاریخچه‌ی قیمت محصول](https://stard-market.ir/docs/reference/product-price-history.md) - [ساخت هشدار قیمت](https://stard-market.ir/docs/reference/price-alerts-create.md) - [فهرست هشدارها](https://stard-market.ir/docs/reference/price-alerts-list.md) - [حذف هشدار](https://stard-market.ir/docs/reference/price-alerts-delete.md) - [شارژ موجودی TON](https://stard-market.ir/docs/reference/wallet-topup.md) - [وضعیت شارژ TON](https://stard-market.ir/docs/reference/wallet-topup-get.md) - [وضعیت سرویس‌ها](https://stard-market.ir/docs/reference/status.md) - [شبیه‌سازی نتیجه‌ی سفارش (test)](https://stard-market.ir/docs/reference/test-simulate.md) - [فهرست خدمات کانال](https://stard-market.ir/docs/reference/services.md) - [یک خدمت](https://stard-market.ir/docs/reference/service-get.md) - [ری‌اکشن‌های قابل سفارش](https://stard-market.ir/docs/reference/services-reactions.md) - [گزینه‌های خدمت](https://stard-market.ir/docs/reference/service-options.md) - [قیمت دقیق خدمت](https://stard-market.ir/docs/reference/service-price.md) - [اطلاعات و ری‌اکشن‌های پست](https://stard-market.ir/docs/reference/service-post-info.md) - [ثبت سفارش خدمت کانال](https://stard-market.ir/docs/reference/service-order.md) - [وضعیت سفارش خدمت](https://stard-market.ir/docs/reference/service-order-get.md) - [قیمت ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-quote.md) - [بررسی پست برای ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-check.md) - [ثبت سفارش ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-order.md) - [وضعیت سفارش ری‌اکشن استارزی](https://stard-market.ir/docs/reference/star-reactions-order-get.md) - [ممبر با ادمین کردن ربات](https://stard-market.ir/docs/reference/members-invite.md) - [وضعیت ممبر با ربات](https://stard-market.ir/docs/reference/members-invite-get.md) - [آمار اعضای سفارش ممبر](https://stard-market.ir/docs/reference/service-order-members.md) - [نرخ TON](https://stard-market.ir/docs/reference/ton-rate.md) - [پیش‌نمایش تبدیل تومان ↔ TON](https://stard-market.ir/docs/reference/wallet-convert-quote.md) - [تبدیل تومان ↔ TON](https://stard-market.ir/docs/reference/wallet-convert.md) - [پیش‌نمایش برداشت TON](https://stard-market.ir/docs/reference/ton-withdraw-quote.md) - [برداشت TON](https://stard-market.ir/docs/reference/ton-withdraw.md) - [برداشت‌های TON](https://stard-market.ir/docs/reference/ton-withdrawals.md) - [قیمت فروش TON (کیف به کیف / کیف پول تلگرام)](https://stard-market.ir/docs/reference/ton-sell-quote.md) - [فروش و ارسال TON](https://stard-market.ir/docs/reference/ton-sell.md) - [ارسال‌های TON](https://stard-market.ir/docs/reference/ton-sell-list.md) - [یک ارسال TON](https://stard-market.ir/docs/reference/ton-sell-get.md) - [پیشنهاد روی مزایده یا آگهی توافقی](https://stard-market.ir/docs/reference/auction-bid.md) - [خرید P2P: پرداخت و شروع امانت](https://stard-market.ir/docs/reference/order-finalize.md) - [خرید P2P: تایید یا رد دریافت](https://stard-market.ir/docs/reference/order-receipt.md) ## منابع - [پرسش‌های رایج](https://stard-market.ir/docs/faq.md) - [تغییرات](https://stard-market.ir/docs/changelog.md)