# Stard API — full documentation (Markdown) Source: https://stard-market.ir/docs · Generated: 2026-11-18 · Language: Persian (fa) with an English overview. ## Overview (English) 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). ## Endpoint index | 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) | --- ## مستندات API استارد (Stard API) > API رسمی Stard Market برای خرید خودکار استارز تلگرام، پریمیوم، گیفت، یوزرنیم و شماره و دریافت قیمت‌های لحظه‌ای. **پاسخ کوتاه:** Stard API یک REST API رسمی است که با یک کلید `sk_live_` یا `sk_test_` در هدر `Authorization` کار می‌کند و به برنامه‌ی تو اجازه می‌دهد قیمت استارز و محصولات تلگرام را بخواند و سفارش واقعی ثبت کند. ### Stard API چیست؟ Stard API یک REST API با پاسخ JSON است که همان امکانات فروشگاه و ربات Stard را در اختیار برنامه‌ی تو می‌گذارد: دیدن محصولات و قیمت‌ها، ثبت سفارش واقعی با پرداخت خودکار از کیف پول API (TON یا تومان) و پیگیری وضعیت سفارش. هیچ سیستم جداگانه‌ای پشتش نیست؛ سفارش‌های API دقیقاً با همان موتورهای خودکاری انجام می‌شوند که سفارش‌های مینی‌اپ را انجام می‌دهند. - [شروع سریع](https://stard-market.ir/docs/getting-started) — از ساخت کلید تا اولین درخواست در ۵ دقیقه - [مرجع API](https://stard-market.ir/docs/reference/products-list) — همه‌ی endpointها با نمونه در ۶ زبان - [API Explorer](https://stard-market.ir/docs/explorer) — درخواست واقعی از داخل مرورگر - [محیط test](https://stard-market.ir/docs/sandbox) — تست کامل بدون پول واقعی ### آدرس پایه و قالب همه‌ی درخواست‌ها به `https://stard-market.ir/api/v1` فرستاده می‌شوند، با HTTPS و JSON (UTF-8). مبلغ‌ها عدد صحیح تومان‌اند (`currency: "IRT"`) و مقدار TON رشته‌ی دقیق با ۹ رقم اعشار، تا هیچ خطای گرد کردن پیش نیاید. زمان‌ها ISO 8601 به وقت UTC هستند. ```bash curl "https://stard-market.ir/api/v1/ping" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ping", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ping", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ping", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ping", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### چه کارهایی می‌شود کرد؟ - قیمت لحظه‌ای استارز، TON، دلار و تلگرام پریمیوم — [`GET /prices`](https://stard-market.ir/docs/reference/prices)، [`GET /stars/price`](https://stard-market.ir/docs/reference/stars-price) - جستجوی همه‌ی محصولات: گیفت، NFT، یوزرنیم، شماره، پریمیوم — [`GET /products`](https://stard-market.ir/docs/reference/products-list) - خرید خودکار استارز و محصولات با پرداخت از کیف پول — [`POST /orders`](https://stard-market.ir/docs/reference/orders-create) - پیگیری و لغو سفارش — [`GET /orders/{id}`](https://stard-market.ir/docs/reference/orders-get)، [`POST /orders/{id}/cancel`](https://stard-market.ir/docs/reference/orders-cancel) - موجودی کیف پول و تراکنش‌ها — [`GET /wallet`](https://stard-market.ir/docs/reference/wallet) - مزایده‌ها و آمار بازار — [`GET /auctions`](https://stard-market.ir/docs/reference/auctions) --- ## شروع سریع: اولین درخواست به Stard API > در پنج قدم: ورود، ساخت کلید test، اولین درخواست، اولین سفارش آزمایشی و رفتن به live. ### ۱. ورود به داشبورد به [داشبورد توسعه‌دهندگان](https://stard-market.ir/developers/login) برو و با تلگرام (کد ربات @Stard_marketbot) یا گوگل وارد شو. یک پروژه‌ی پیش‌فرض و ۱۰۰ میلیون تومان موجودی آزمایشی برایت ساخته می‌شود. ### ۲. ساخت کلید test در بخش «کلیدهای API» یک کلید با محیط **test** بساز. کلید فقط **همان یک بار** نمایش داده می‌شود؛ آن را در متغیر محیطی نگه دار، نه در کد: **ترمینال** ```bash export STARD_API_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ### ۳. اولین درخواست قیمت ۵۰۰ استارز را بگیر: ```bash curl "https://stard-market.ir/api/v1/stars/price?quantity=500" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/stars/price?quantity=500", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/stars/price?quantity=500", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "stars_price", "quantity": 500, "unit_price": 4382, "amount": 2191000, "currency": "IRT", "updated_at": "2026-10-01T10:31:49Z" } ``` ### ۴. اولین سفارش آزمایشی با کلید test سفارش در sandbox ثبت می‌شود؛ همه‌ی اعتبارسنجی‌ها و قیمت‌ها واقعی‌اند ولی پولی جابه‌جا نمی‌شود: ```bash curl -X POST "https://stard-market.ir/api/v1/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: first-order-1" \ -d '{"type": "stars", "quantity": 500, "recipient": "@durov"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "first-order-1", }, body: JSON.stringify({ "type": "stars", "quantity": 500, "recipient": "@durov" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "first-order-1", }, body: JSON.stringify({ "type": "stars", "quantity": 500, "recipient": "@durov" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "first-order-1", }, json={ "type": "stars", "quantity": 500, "recipient": "@durov" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: first-order-1", ], CURLOPT_POSTFIELDS => json_encode([ "type" => "stars", "quantity" => 500, "recipient" => "@durov" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"type": "stars", "quantity": 500, "recipient": "@durov"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "first-order-1") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "order", "id": "ord_test_TyrINakBwx0N66kV", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "⭐ 500 استارز برای @durov (test)", "product_id": null, "product_tag": null, "type": "stars", "quantity": 500, "recipient": "@durov", "amount": { "amount": 2191000, "currency": "IRT" }, "paid": { "amount": 2191000, "currency": "IRT" }, "failure_reason": null, "metadata": {}, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ``` ### ۵. رفتن به live وقتی یکپارچه‌سازی کامل شد، حساب تلگرام Stard را در داشبورد وصل کن (اگر با گوگل وارد شده‌ای)، از بخش «کیف پول API» داشبورد با یک کلیک از ولت TON خودت (Tonkeeper یا هر ولت) شارژ کن و یک کلید **live** بساز. کد تو تغییری نمی‌کند؛ فقط کلید عوض می‌شود. [تفاوت test و live](https://stard-market.ir/docs/sandbox) --- ## احراز هویت در Stard API > هر درخواست با هدر Authorization: Bearer و کلید API احراز هویت می‌شود؛ کلید هرگز نباید در URL یا کد سمت کاربر بیاید. ### هدر Authorization کلید را فقط در هدر بفرست: **درخواست** ```http GET /api/v1/ping HTTP/1.1 Host: stard-market.ir Authorization: Bearer sk_live_… ``` *⛔* کلید در query string (`?api_key=`) با خطای `key_in_url` رد می‌شود، چون URLها در لاگ سرورها و تاریخچه‌ی مرورگر می‌مانند. ### فقط سمت سرور کلید API دسترسی خرید از کیف پول تو را دارد. آن را هرگز در اپ موبایل، افزونه‌ی مرورگر یا جاوااسکریپت سمت کاربر نگذار. اگر کلاینت لازم دارد، از سرور خودت به‌عنوان واسطه استفاده کن. ### خطاهای احراز هویت | HTTP | code | معنی | |---|---|---| | 401 | `missing_api_key` | هدر Authorization نیامده | | 401 | `invalid_authorization_header` | قالب هدر اشتباه است | | 401 | `invalid_api_key` | کلید وجود ندارد | | 401 | `api_key_revoked` / `api_key_expired` | کلید باطل یا منقضی شده | | 403 | `insufficient_scope` | کلید اجازه‌ی این کار را ندارد | | 403 | `developer_suspended` | حساب توسعه‌دهنده غیرفعال شده | | 429 | `too_many_auth_failures` | تلاش‌های ناموفق زیاد از یک IP؛ ۱۰ دقیقه صبر کن | **نمونه — 401** ```json { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "کلید API نامعتبر است.", "param": null, "request_id": "req_kOJImCbYQBR8TFvCeGON" } } ``` --- ## کلیدهای API: ساخت، چرخش و ابطال > کلیدها برای هر پروژه و محیط جدا ساخته می‌شوند، scope و سقف نرخ و تاریخ انقضا دارند و فقط هش آن‌ها ذخیره می‌شود. ### قالب کلید `sk_live_` یا `sk_test_` و ۴۰ کاراکتر تصادفی (حدود ۲۳۸ بیت). Stard فقط HMAC کلید را نگه می‌دارد؛ حتی پشتیبانی Stard هم نمی‌تواند کلید تو را ببیند. اگر گمش کردی، کلید تازه بساز. ### Scopeها | scope | اجازه | |---|---| | `products:read` | محصولات، دسته‌ها، مزایده‌ها، آمار بازار | | `prices:read` | قیمت استارز، TON، دلار، پریمیوم و محصولات | | `orders:read` | خواندن سفارش‌های همین پروژه | | `orders:write` | ثبت و لغو سفارش (در live با پول واقعی) | | `wallet:read` | موجودی و تراکنش‌ها | | `wallet:write` | تبدیل تومان↔TON و برداشت TON به کیف پول وصل‌شده (پیش‌فرض نیست؛ صریحاً انتخاب کن) | | `webhooks:read` | خواندن رویدادها | اصل کمترین دسترسی: کلیدی که فقط قیمت نشان می‌دهد نباید `orders:write` داشته باشد. ### چرخش (rotate) چرخش یک کلید تازه با همان تنظیمات می‌سازد. کلید قبلی یا فوراً باطل می‌شود یا تا مهلتی که تعیین می‌کنی (حداکثر ۷۲ ساعت) کار می‌کند تا بتوانی بدون قطعی سرویس، کلید را در سرورهایت عوض کنی. ### ابطال ابطال فوری است؛ درخواست بعدی با آن کلید `401 api_key_revoked` می‌گیرد. اگر کلید لو رفت، اول ابطال، بعد بررسی لاگ‌ها. --- ## محیط test و live > کلیدهای sk_test_ با موجودی آزمایشی و بدون پول واقعی کار می‌کنند؛ کلیدهای sk_live_ سفارش واقعی ثبت می‌کنند. ### تفاوت‌ها | | test | live | |---|---|---| | کلید | `sk_test_…` | `sk_live_…` | | داده‌ی محصولات و قیمت | واقعی | واقعی | | سفارش | در sandbox، با شناسه‌ی `ord_test_` | سفارش واقعی Stard | | پرداخت | موجودی آزمایشی (۱۰۰ میلیون، قابل شارژ مجدد از داشبورد) | کیف پول واقعی حساب لینک‌شده | | پیش‌نیاز | هیچ | اتصال حساب تلگرام Stard | *✅* این دو محیط هیچ‌وقت قاطی نمی‌شوند: کلید test هرگز سفارش live را نمی‌بیند و برعکس، و هیچ سفارش test به پول یا سفارش واقعی دست نمی‌زند. ### همان اعتبارسنجی در test همه‌ی قواعد live اجرا می‌شود: قیمت واقعی، کمبود موجودی (`402`)، گیرنده‌ی نامعتبر، محدودیت نرخ و idempotency. پس کدی که در test کار کند، در live هم کار می‌کند. --- ## خطاها > همه‌ی خطاها قالب یکسان JSON دارند با type، code، message، param و request_id؛ روی code تصمیم بگیر، نه message. ### قالب خطا **نمونه — 400** ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "حداقل خرید استارز ۵۰ عدد است.", "param": "quantity", "request_id": "req_XZV2dfm7YHW6ECeAA1bW" } } ``` `code` پایدار است و برای منطق برنامه است؛ `message` فارسی و برای نمایش است و ممکن است تغییر کند. `request_id` را در لاگ خودت نگه دار؛ پشتیبانی با آن درخواست را دقیق پیدا می‌کند. ### کدهای HTTP | HTTP | type | معنی | |---|---|---| | 400 | `invalid_request_error` | پارامتر یا بدنه نامعتبر | | 401 | `authentication_error` | مشکل کلید | | 402 | `payment_error` | موجودی کافی نیست | | 403 | `permission_error` | scope یا وضعیت حساب | | 404 | `invalid_request_error` | پیدا نشد (منابع دیگران هم همیشه 404 می‌دهند) | | 409 | `conflict_error` | تداخل وضعیت یا idempotency | | 429 | `rate_limit_error` | محدودیت نرخ | | 5xx | `api_error` | خطای سرور؛ با همان Idempotency-Key دوباره بفرست | ### کی دوباره تلاش کنم؟ روی `429` بعد از `Retry-After`، روی `5xx` و قطعی شبکه با فاصله‌ی افزایشی (۱، ۲، ۴، ۸ ثانیه). درخواست‌های `POST` را فقط با `Idempotency-Key` تکرار کن. روی `4xx` دیگر تکرار نکن؛ درخواست را اصلاح کن. --- ## محدودیت نرخ (Rate limit) > هر کلید، هر حساب و هر IP سقف درخواست در دقیقه دارد و وضعیت لحظه‌ای در هدرهای X-RateLimit برمی‌گردد. ### سقف‌ها | سطح | پیش‌فرض | |---|---| | هر کلید | ۶۰ در دقیقه (قابل تنظیم تا سقفی که Stard تعیین می‌کند) | | کل حساب توسعه‌دهنده | ۱۲۰۰ در دقیقه | | ثبت سفارش هر کلید | ۲۰ در دقیقه | | تلاش ناموفق احراز هویت هر IP | ۳۰ در ۱۰ دقیقه | ### هدرها **پاسخ** ```http X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Reset: 1790850720 X-Request-Id: req_CrDLZwkMsyARmvYlkkTI ``` `X-RateLimit-Reset` زمان یونیکس (ثانیه) شروع پنجره‌ی بعد است. وقتی سقف پر شود پاسخ `429` با هدر `Retry-After` می‌آید. --- ## Idempotency: تکرار امن درخواست > با هدر Idempotency-Key می‌توانی درخواست ثبت سفارش را بعد از قطعی شبکه بدون خطر خرید دوباره تکرار کنی. ### چطور کار می‌کند برای هر سفارش یک کلید یکتا (مثلاً شماره فاکتور خودت) در هدر `Idempotency-Key` بفرست. اگر همان درخواست با همان کلید دوباره برسد، Stard سفارش تازه نمی‌سازد و پاسخ قبلی را با هدر `Idempotent-Replayed: true` برمی‌گرداند. ```bash curl -X POST "https://stard-market.ir/api/v1/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-INV-1042" \ -d '{"type": "product", "product_id": 4518}' ``` ### قواعد - کلید برای هر کلید API جداست و حداکثر ۶۴ کاراکتر از حروف، عدد و `_-:.`. - همان کلید با بدنه‌ی متفاوت → `409 idempotency_key_reused`. - اگر درخواست اول هنوز در جریان باشد → `409 request_in_progress`؛ کمی بعد دوباره بفرست. - خطای ۵xx ذخیره نمی‌شود، پس تکرار با همان کلید امن است. --- ## صفحه‌بندی > فهرست‌ها شیء list با data، has_more و next_offset برمی‌گردانند؛ با limit و offset صفحه به صفحه جلو برو. ### قالب **پاسخ فهرست** ```json { "object": "list", "data": [ "…" ], "has_more": true, "next_offset": 20 } ``` تا وقتی `has_more` برابر `true` است، درخواست بعد را با `offset=next_offset` بفرست. `limit` حداکثر ۱۰۰ است. --- ## امنیت > نحوه‌ی نگهداری کلیدها، نشست‌ها و داده‌ها در پلتفرم توسعه‌دهندگان Stard و توصیه‌های امنیتی برای یکپارچه‌سازی. ### کلیدها - فقط HMAC-SHA256 کلید ذخیره می‌شود؛ متن کلید فقط یک بار هنگام ساخت نمایش داده می‌شود. - کلید در URL پذیرفته نمی‌شود و هرگز در لاگ‌ها ذخیره نمی‌شود. - ابطال فوری، چرخش با مهلت، تاریخ انقضا و scope محدود. ### داشبورد - ورود با تلگرام یا گوگل (OAuth 2.0 با PKCE و state یک‌بارمصرف)؛ Stard هیچ رمز عبوری نگه نمی‌دارد. - کوکی نشست httpOnly، Secure و SameSite=Lax؛ هر درخواست تغییردهنده توکن CSRF می‌خواهد. - ورود از دستگاه تازه به تلگرامت اطلاع داده می‌شود و همه‌ی نشست‌ها از داشبورد قابل ابطال‌اند. ### داده و حریم خصوصی - لاگ درخواست‌ها فقط مسیر، وضعیت، زمان پاسخ و هش IP را نگه می‌دارد؛ بدنه و کلید هرگز. - هر کلید فقط سفارش‌های پروژه‌ی خودش را می‌بیند؛ منابع دیگران همیشه 404 می‌دهند. - هویت پیشنهاددهنده‌های مزایده برگردانده نمی‌شود. ### گزارش آسیب‌پذیری اگر مشکل امنیتی پیدا کردی، لطفاً عمومی منتشرش نکن و به [پشتیبانی Stard](https://t.me/Stard_market) خبر بده. --- ## وب‌هوک‌ها > وقتی وضعیت سفارش عوض می‌شود، Stard یک درخواست POST امضاشده به سرورت می‌فرستد؛ دیگر لازم نیست مدام وضعیت را بپرسی. **جواب کوتاه:** وب‌هوک Stard برای هر تغییر وضعیت سفارش یک POST با امضای HMAC-SHA256 به سرورت می‌فرستد؛ امضا را با secret بررسی کن و سریع 2xx برگردان. ### ساخت وب‌هوک در [داشبورد ← وب‌هوک‌ها](https://stard-market.ir/developers/dashboard#webhooks) آدرس https سرورت، محیط (test یا live) و رویدادها را انتخاب کن. **secret** (با پیشوند `whsec_`) فقط همان لحظه نمایش داده می‌شود؛ آن را در متغیر محیطی نگه دار. با «ارسال آزمایشی» یک رویداد `webhook.test` می‌گیری و با «لاگ ارسال» نتیجه‌ی هر تحویل را می‌بینی. در محیط test، سفارش‌ها ۱۵ ثانیه بعد خودکار `completed` می‌شوند تا کل چرخه را بدون پول واقعی آزمایش کنی. ### رویدادها | type | کی | |---|---| | `order.created` | سفارش ثبت شد | | `order.pending` | در انتظار انجام | | `order.processing` | انجام سفارش شروع شد | | `order.completed` | سفارش انجام شد | | `order.cancelled` | سفارش لغو/رد شد | | `order.refunded` | مبلغ برگشت داده شد | | `order.failed` | سفارش ناموفق شد | | `price.alert` | قیمت به هدف یک هشدار قیمت رسید | | `webhook.test` | رویداد آزمایشی از داشبورد | ### بدنه‌ی درخواست **POST به آدرس تو** ```json { "id": "evt_8Qe2kV1mZ0xYc3Lb", "object": "event", "type": "order.completed", "environment": "test", "created": "2026-10-02T11:20:05Z", "api_version": "v1", "data": { "object": { "object": "order", "id": "ord_test_4Fh8Kp2Lx9Qa7Rt1", "environment": "test", "status": "completed", "type": "stars", "title": "۵۰۰ استارز", "quantity": 500, "recipient": "@username", "amount": { "amount": 2198000, "currency": "IRT" }, "metadata": { "invoice": "INV-1042" } } } } ``` هدرها: `Stard-Event` (نوع رویداد)، `Stard-Event-Id` (شناسه‌ی یکتا؛ برای جلوگیری از پردازش تکراری نگهش دار) و `Stard-Signature`. ### بررسی امضا هدر `Stard-Signature` این شکل را دارد: `t=1759404005,v1=5f2b…`. مقدار `v1` برابر HMAC-SHA256 رشته‌ی `t + "." + بدنه‌ی خام` با secret توست. حتماً بدنه‌ی **خام** را امضا کن (قبل از parse) و درخواست‌های قدیمی‌تر از ۵ دقیقه را رد کن. SDKها این کار را آماده دارند. ```javascript import express from "express"; import { verifyWebhook } from "./stard.mjs"; const app = express(); // بدنه‌ی خام لازم است؛ JSON parser را برای این مسیر نگذار app.post("/stard/webhook", express.raw({ type: "application/json" }), async (req, res) => { try { const event = await verifyWebhook(req.body, req.get("Stard-Signature"), process.env.STARD_WEBHOOK_SECRET); if (event.type === "order.completed") { // سفارش انجام شد: event.data.object } res.sendStatus(200); // سریع ۲xx برگردان؛ کار سنگین را در صف انجام بده } catch (e) { res.sendStatus(400); } }); ``` ```python from flask import Flask, request, abort from stard import verify_webhook app = Flask(__name__) @app.post("/stard/webhook") def stard_webhook(): try: event = verify_webhook(request.get_data(), request.headers.get("Stard-Signature"), STARD_WEBHOOK_SECRET) except ValueError: abort(400) if event["type"] == "order.completed": order = event["data"]["object"] return "", 200 ``` ```php ## SDKها: JavaScript، Python و PHP > کتابخانه‌های رسمی و تک‌فایلی Stard API بدون وابستگی خارجی؛ با Idempotency-Key خودکار، تلاش دوباره‌ی امن و بررسی امضای وب‌هوک. **جواب کوتاه:** سه SDK رسمی تک‌فایلی برای JavaScript/TypeScript، Python و PHP؛ فایل را دانلود کن، با کلید API بساز و مثلاً با `buyStars` استارز بخر. ### دانلود - [stard.mjs](https://stard-market.ir/developers/sdk/stard.mjs) — Node 18+، Deno، Bun و edge (ESM، بدون وابستگی) - [stard.py](https://stard-market.ir/developers/sdk/stard.py) — Python 3.8+ (فقط کتابخانه‌ی استاندارد) - [Stard.php](https://stard-market.ir/developers/sdk/Stard.php) — PHP 7.4+ با ext-curl ```bash curl -O https://stard-market.ir/developers/sdk/stard.mjs curl -O https://stard-market.ir/developers/sdk/stard.py curl -O https://stard-market.ir/developers/sdk/Stard.php ``` ### استفاده ```javascript import { Stard } from "./stard.mjs"; const stard = new Stard(process.env.STARD_API_KEY); // sk_test_… یا sk_live_… const price = await stard.starsPrice(500); const order = await stard.buyStars({ quantity: 500, recipient: "@username", metadata: { invoice: "INV-1042" } }); console.log(order.id, order.status); ``` ```python from stard import Stard stard = Stard(os.environ["STARD_API_KEY"]) price = stard.stars_price(500) order = stard.buy_stars(quantity=500, recipient="@username", metadata={"invoice": "INV-1042"}) print(order["id"], order["status"]) ``` ```php starsPrice(500); $order = $stard->buyStars(500, '@username', null, ['invoice' => 'INV-1042']); echo $order['id'], ' ', $order['status']; ``` ### چه چیزهایی آماده است - همه‌ی endpointهای v1: قیمت‌ها، استارز، پریمیوم، محصولات، کیف پول، تراکنش‌ها و سفارش (ثبت، پیگیری، لغو). - `Idempotency-Key` خودکار برای هر POST؛ تلاش دوباره روی 429 و 5xx با همان کلید، پس سفارش تکراری ساخته نمی‌شود. - خطاهای ساختاریافته (`code`، `param`، `request_id`). - `verifyWebhook` / `verify_webhook` برای [وب‌هوک‌ها](https://stard-market.ir/docs/webhooks). - `pay_currency` اختیاری: اگر نفرستی، منبع پیش‌فرض [کیف پول API](https://stard-market.ir/docs/wallet) (TON یا تومان) استفاده می‌شود. *⚠️* SDK فقط سمت سرور. کلید API را هرگز در مرورگر، اپ موبایل یا مخزن عمومی نگذار. --- ## ربات فروشگاهی آماده‌ی تلگرام (Stard Shop Bot) > ربات متن‌باز فروش استارز، پریمیوم و گیفت تلگرام؛ فقط توکن ربات و کلید Stard API را بده، درصد سودت را بگذار و فروشگاه خودت را داشته باش. **جواب کوتاه:** Stard Shop Bot یک ربات فروشگاهی آماده و رایگان برای فروش استارز، پریمیوم و گیفت تلگرام است؛ با توکن ربات و کلید Stard API در چند دقیقه راه می‌افتد و سود هر فروش مال خودت است. ### ربات فروشگاهی استارد چیست؟ **Stard Shop Bot** یک ربات تلگرام آماده و متن‌باز با مجوز MIT است که استارز تلگرام، تلگرام پریمیوم و گیفت‌های استارزی را می‌فروشد. قیمت‌ها و سفارش‌ها مستقیم به [Stard API](https://stard-market.ir/docs) وصل‌اند؛ مالک ربات فقط درصد سود خودش را روی قیمت API می‌گذارد و سفارش‌ها خودکار ثبت و تحویل می‌شوند. کد کامل: [github.com/arad-afray/stard-shop-bot](https://github.com/arad-afray/stard-shop-bot). ### امکانات #### برای کاربر - فروشگاه دسته‌بندی‌شده: استارز (آماده یا دلخواه)، پلن‌های پریمیوم، گیفت‌ها - کیف پول داخلی با شارژ کارت‌به‌کارت و رسید - پیش‌فاکتور و دکمه‌ی «برای خودم» - تاریخچه‌ی سفارش با وضعیت لحظه‌ای و اعلان خودکار - پشتیبانی از اعداد فارسی و عربی #### برای مالک - درصد سود کلی و جدا برای هر دسته - آمار فروش، سود خالص و سفارش‌های در جریان - تایید یا رد شارژها با یک دکمه - مدیریت کاربر، موجودی و مسدودسازی - پیام همگانی - نمایش موجودی کیف پول Stard API و محیط test/live - باز و بسته کردن فروشگاه #### قابلیت اطمینان - کسر موجودی اتمیک - Idempotency-Key روی هر سفارش - `quote_id` برای قفل قیمت - برگشت خودکار پول سفارش ناموفق، فقط یک بار - دفتر کل (ledger) برای هر تومان - تلاش دوباره روی 429، 5xx و قطعی شبکه ### راه‌اندازی در ۷ قدم 1. **ساخت ربات**: در @BotFather یک ربات بساز و توکنش را بردار. 2. **ساخت کلید API**: در داشبورد توسعه‌دهندگان استارد یک کلید sk_test_ بساز (برای تست بدون پول واقعی). 3. **دریافت کد**: مخزن stard-shop-bot را از گیت‌هاب clone کن و فایل .env.example را به .env کپی کن. 4. **تنظیم**: در .env مقدار BOT_TOKEN، ADMIN_IDS و STARD_API_KEY را بنویس. 5. **اجرا**: با docker compose up -d --build یا python -m bot اجرا کن. 6. **تنظیمات فروشگاه**: در ربات /start بزن، از پنل مدیریت شماره کارت، نام صاحب کارت و درصد سود را تنظیم کن. 7. **رفتن به live**: حساب تلگرام را در داشبورد وصل کن، کیف پول Stard را شارژ کن و کلید sk_live_ بگذار. ``` git clone https://github.com/arad-afray/stard-shop-bot.git cd stard-shop-bot cp .env.example .env # BOT_TOKEN, ADMIN_IDS, STARD_API_KEY docker compose up -d --build ``` ### متغیرهای محیطی | متغیر | توضیح | پیش‌فرض | |---|---|---| | `BOT_TOKEN` | توکن ربات از BotFather | الزامی | | `ADMIN_IDS` | آیدی عددی مدیرها، با کاما | — | | `STARD_API_KEY` | sk_test_… یا sk_live_… | الزامی | | `STARD_BASE_URL` | آدرس API | https://stard-market.ir/api/v1 | | `STARD_PAY_CURRENCY` | IRT یا TON | پیش‌فرض داشبورد | | `DATABASE_PATH` | مسیر SQLite | data/shop.db | | `DEFAULT_PROFIT_PERCENT` | سود اولیه٪ | 10 | | `POLL_INTERVAL_SECONDS` | فاصله‌ی پیگیری سفارش | 20 | ### جریان سفارش 1. کاربر محصول را انتخاب می‌کند؛ ربات با `POST /orders/quote` قیمت و `quote_id` (قفل ۲ دقیقه‌ای) می‌گیرد. 2. قیمت فروش = قیمت × (۱ + سود٪). 3. با تایید کاربر، موجودی کسر و `POST /orders` با Idempotency-Key ثبت می‌شود. 4. worker هر ۲۰ ثانیه وضعیت را می‌پرسد؛ completed ← «تحویل شد»، failed یا refunded ← برگشت پول. *⚠️* در live، موجودی کیف پول Stard باید از مجموع سفارش‌های در جریان بیشتر باشد؛ وگرنه سفارش با insufficient_funds رد و پول کاربر برگردانده می‌شود. ### پرسش‌های رایج **ربات فروشگاهی استارد چیست؟** یک ربات تلگرام آماده و متن‌باز (MIT) که استارز، تلگرام پریمیوم و گیفت تلگرام را می‌فروشد و قیمت و تحویل را از Stard API می‌گیرد. مالک فقط توکن ربات و کلید API را می‌دهد و درصد سود خودش را تعیین می‌کند. **برای راه‌اندازی برنامه‌نویسی لازم است؟** نه. کافی است توکن ربات، آیدی عددی مدیر و کلید API را در فایل .env بنویسی و با Docker اجرا کنی. **سود من چطور حساب می‌شود؟** قیمت فروش = قیمت Stard × (۱ + درصد سود). درصد سود را از پنل مدیریت ربات، کلی یا جدا برای هر دسته، تعیین می‌کنی. **اگر سفارش انجام نشود پول کاربر چه می‌شود؟** سفارش ناموفق، لغوشده یا برگشتی خودکار و فقط یک بار به کیف پول کاربر برمی‌گردد و کاربر پیام می‌گیرد. **آیا ممکن است یک سفارش دو بار خریده شود؟** نه. هر سفارش Idempotency-Key دارد و کسر موجودی اتمیک است؛ قطعی شبکه هم باعث خرید تکراری نمی‌شود. **می‌توانم بدون پول واقعی امتحان کنم؟** بله. با کلید sk_test_ همه‌چیز در محیط test اجرا می‌شود و نتیجه‌ی سفارش را هم می‌شود شبیه‌سازی کرد. **کاربران چطور پرداخت می‌کنند؟** کیف پول داخلی ربات را با کارت‌به‌کارت و ارسال عکس رسید شارژ می‌کنند و مدیر با یک دکمه تایید می‌کند. --- ## محصولات در Stard API > همه‌ی محصولات فروشگاه — گیفت، NFT، یوزرنیم، شماره، پریمیوم و استارز — با یک endpoint جستجو و فیلتر می‌شوند. ### شیء محصول **product** ```json { "object": "product", "id": 4518, "tag": "3Q219N", "name": "پریمیوم ۳ ماهه", "description": "اشتراک تلگرام پریمیوم", "category": "premium", "pricing_type": "fixed", "price": { "amount": 3788624, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": "https://fragment.com/premium", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": "2026-10-01T10:13:50Z", "created_at": "2026-07-25T21:54:14Z" } ``` ### فیلدهای مهم - `price.amount`: مبلغی که هنگام خرید کسر می‌شود (تومان). - `purchasable_via_api`: آیا با `POST /orders` قابل خرید است. آگهی‌های کاربر به کاربر (P2P)، مزایده و توافقی به تایید طرفین در تلگرام نیاز دارند و از API خریده نمی‌شوند. - `marketplace`: `stard` (فروش مستقیم) یا `p2p`. ### endpointها - [`GET /products`](https://stard-market.ir/docs/reference/products-list) - [`GET /products/{category}`](https://stard-market.ir/docs/reference/products-category) - [`GET /products/{id}`](https://stard-market.ir/docs/reference/product-get) - [`GET /products/tag/{tag}`](https://stard-market.ir/docs/reference/product-tag) - [`GET /categories`](https://stard-market.ir/docs/reference/categories) --- ## خرید استارز تلگرام با API > قیمت لحظه‌ای استارز را بگیر و با یک درخواست، استارز را مستقیم به یوزرنیم تلگرام گیرنده بفرست؛ ارسال خودکار است. **پاسخ کوتاه:** بله. با `POST /api/v1/orders` و بدنه‌ی `{"type":"stars","quantity":500,"recipient":"@username"}` استارز تلگرام خریده و خودکار به گیرنده فرستاده می‌شود؛ مبلغ از کیف پول Stard کسر می‌شود. ### قیمت ```bash curl "https://stard-market.ir/api/v1/stars/price?quantity=500" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/stars/price?quantity=500", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/stars/price?quantity=500", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ** ```json { "object": "stars_price", "quantity": 500, "unit_price": 4382, "amount": 2191000, "currency": "IRT", "updated_at": "2026-10-01T10:31:49Z" } ``` ### خرید حداقل ۵۰ استارز. گیرنده فقط با یوزرنیم تلگرام (نه آیدی عددی). ```bash curl -X POST "https://stard-market.ir/api/v1/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: stars-7781" \ -d '{"type": "stars", "quantity": 500, "recipient": "@username"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "stars-7781", }, body: JSON.stringify({ "type": "stars", "quantity": 500, "recipient": "@username" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "stars-7781", }, body: JSON.stringify({ "type": "stars", "quantity": 500, "recipient": "@username" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "stars-7781", }, json={ "type": "stars", "quantity": 500, "recipient": "@username" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: stars-7781", ], CURLOPT_POSTFIELDS => json_encode([ "type" => "stars", "quantity" => 500, "recipient" => "@username" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"type": "stars", "quantity": 500, "recipient": "@username"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "stars-7781") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### تحویل استارز با موتور خودکار Stard به‌صورت آنی (معمولاً کمتر از یک دقیقه) به حساب گیرنده می‌رسد. وضعیت را با [`GET /orders/{id}`](https://stard-market.ir/docs/reference/orders-get) دنبال کن؛ وقتی `status` برابر `completed` شد، تحویل انجام شده است. ### پرسش‌های رایج **حداقل خرید استارز از API چقدر است؟** ۵۰ استارز. **می‌شود به آیدی عددی استارز فرستاد؟** نه؛ تلگرام استارز را فقط به یوزرنیم می‌فرستد. --- ## خرید تلگرام پریمیوم با API > پلن‌های ۳، ۶ و ۱۲ ماهه‌ی تلگرام پریمیوم را با قیمت لحظه‌ای بگیر و برای هر یوزرنیم فعال کن. ### پلن‌ها ```bash curl "https://stard-market.ir/api/v1/premium/prices" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/premium/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/premium/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/premium/prices", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/premium/prices", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ** ```json { "object": "list", "data": [ { "object": "premium_plan", "product_id": 4518, "tag": "3Q219N", "name": "پریمیوم ۳ ماهه", "price": { "amount": 3788624, "currency": "IRT" }, "available": true, "updated_at": "2026-10-01T10:13:50.573556" }, { "object": "premium_plan", "product_id": 4519, "tag": "XOQORP", "name": "پریمیوم ۶ ماهه", "price": { "amount": 5051499, "currency": "IRT" }, "available": true, "updated_at": "2026-10-01T10:13:50.573556" } ], "has_more": false, "next_offset": null } ``` ### خرید `product_id` پلن را با یوزرنیم گیرنده بفرست: ```bash curl -X POST "https://stard-market.ir/api/v1/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: premium-311" \ -d '{"type": "product", "product_id": 4518, "recipient": "@username"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "premium-311", }, body: JSON.stringify({ "type": "product", "product_id": 4518, "recipient": "@username" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "premium-311", }, body: JSON.stringify({ "type": "product", "product_id": 4518, "recipient": "@username" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "premium-311", }, json={ "type": "product", "product_id": 4518, "recipient": "@username" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: premium-311", ], CURLOPT_POSTFIELDS => json_encode([ "type" => "product", "product_id" => 4518, "recipient" => "@username" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"type": "product", "product_id": 4518, "recipient": "@username"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "premium-311") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` --- ## گیفت‌ها و NFTهای تلگرام در API > گیفت‌های کالکشنی، NFTها و گیفت‌های استارزی با ویژگی‌ها و کف قیمت؛ جستجو با نام کالکشن یا لینک فرگمنت. ### فهرست ```bash curl "https://stard-market.ir/api/v1/products?category=gifts&sort=price_asc&limit=20" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products?category=gifts&sort=price_asc&limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products?category=gifts&sort=price_asc&limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products?category=gifts&sort=price_asc&limit=20", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products?category=gifts&sort=price_asc&limit=20", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` برای گیفت‌ها فیلد `attributes` شامل کالکشن، مدل، بک‌دراپ و نماد است. جستجو با لینک `fragment.com/gift/…` هم کار می‌کند. ### خرید گیفت استارزی گیفت‌های استارزی (`star_gift`) به یوزرنیم گیرنده فرستاده می‌شوند و می‌توانند پیام داشته باشند (`gift_message`). --- ## یوزرنیم‌ها و شماره‌های مجازی تلگرام > یوزرنیم‌ها و شماره‌های +888 فروشگاه و بازار کاربران؛ فیلتر بر اساس قیمت و نوع فروش. ### فهرست ```bash curl "https://stard-market.ir/api/v1/products/usernames?sort=price_asc&limit=20" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/usernames?sort=price_asc&limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/usernames?sort=price_asc&limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/usernames?sort=price_asc&limit=20", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/usernames?sort=price_asc&limit=20", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` بیشتر یوزرنیم‌ها آگهی کاربران (P2P) هستند و از طریق مینی‌اپ با واسطه‌گری امن Stard خریده می‌شوند؛ در پاسخ API فیلد `purchasable_via_api` این را مشخص می‌کند. --- ## قیمت‌های لحظه‌ای > قیمت استارز، TON، دلار و پریمیوم به تومان، از همان منبعی که ربات و فروشگاه با آن کار می‌کنند. ### همه‌ی نرخ‌ها ```bash curl "https://stard-market.ir/api/v1/prices" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/prices", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/prices", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ** ```json { "object": "prices", "currency": "IRT", "star": { "amount": 4382, "unit": "1 star" }, "ton": { "amount": 385770, "usd": 1.4976 }, "usd": { "amount": 256300 }, "ton_per_50_stars": 0.5005, "updated_at": "2026-10-01T10:31:48Z" } ``` ### به‌روزرسانی نرخ‌ها حداکثر هر دو دقیقه از منبع به‌روز می‌شوند. برای نمایش در اپ، کش ۳۰ تا ۶۰ ثانیه‌ای کافی است؛ مبلغ نهایی هر سفارش همیشه همان لحظه‌ی ثبت محاسبه می‌شود. --- ## سفارش و خرید از طریق API > چرخه‌ی کامل سفارش: ثبت با idempotency، پرداخت از کیف پول، انجام خودکار، پیگیری وضعیت و لغو. ### چرخه‌ی وضعیت | status | معنی | |---|---| | `pending` | ثبت و پرداخت شده، در صف انجام | | `processing` | در حال انجام | | `completed` | تحویل شد | | `cancelled` | لغو یا رد شد؛ مبلغ برگشت | | `refunded` | مبلغ برگشت داده شد | | `failed` | ناموفق | `raw_status` وضعیت داخلی دقیق Stard را هم برای عیب‌یابی می‌دهد. ### شیء سفارش **order** ```json { "object": "order", "id": "ord_test_gGToQWxqOw89ssiL", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "پریمیوم ۳ ماهه (test)", "product_id": 4518, "product_tag": null, "type": "product", "quantity": 1, "recipient": null, "amount": { "amount": 3788624, "currency": "IRT" }, "paid": { "amount": 3788624, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ``` ### پول و دقت - مبلغ همان لحظه‌ی ثبت از سرور محاسبه می‌شود؛ کلاینت هیچ مبلغی نمی‌فرستد. - کسر موجودی اتمیک است؛ دو سفارش هم‌زمان نمی‌توانند بیش از موجودی خرج کنند. - سفارش لغو یا ردشده دقیقاً با همان واحد (تومان یا TON) برمی‌گردد. ### فروش از طریق API ثبت آگهی فروش (یوزرنیم، گیفت و…) فعلاً فقط از مینی‌اپ و ربات Stard ممکن است، چون مالکیت آیتم باید در تلگرام تایید شود. --- ## کیف پول و تراکنش‌ها > موجودی تومانی و TON و دفتر کل تراکنش‌های حساب لینک‌شده؛ در test، موجودی آزمایشی. ### موجودی ```bash curl "https://stard-market.ir/api/v1/wallet" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ (test)** ```json { "object": "wallet", "environment": "test", "balances": [ { "currency": "IRT", "amount": 100000000 } ], "note": "موجودی آزمایشی؛ پول واقعی نیست." } ``` ### تراکنش‌ها ```bash curl "https://stard-market.ir/api/v1/transactions?limit=20" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/transactions?limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/transactions?limit=20", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/transactions?limit=20", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/transactions?limit=20", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` *⚠️* برداشت و انتقال پول از طریق API عمداً وجود ندارد. ### شارژ کیف پول API با TON در داشبورد، بخش **کیف پول API**: مبلغ TON را وارد کن و «ساخت لینک پرداخت» را بزن؛ ولتت (Tonkeeper یا هر ولت TON) با آدرس و memo آماده باز می‌شود. بعد از تأیید شبکه، موجودی TON شارژ می‌شود و هر سفارش API خودکار و فوری از همین موجودی کم می‌شود. منبع پیش‌فرض (TON یا تومان) را هم همان‌جا انتخاب می‌کنی. *🔐* استارد هیچ‌وقت کلید خصوصی یا ۲۴ کلمه‌ی ولت تو را نمی‌خواهد و نگه نمی‌دارد. اگر جایی به اسم استارد این را خواستند، کلاهبرداری است. --- ## بررسی کلید `GET /api/v1/ping` > ساده‌ترین درخواست: کلید را بررسی می‌کند و محیط (live/test)، شناسه‌ی حساب و scopeهای کلید را برمی‌گرداند. برای تست اتصال و health-check یکپارچه‌سازی مناسب است. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/ping" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ping", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ping", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ping", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ping", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "ping", "ok": true, "environment": "test", "developer": "dev_8Kq2Lm4Np6Rs8Tu0Vw2X", "key": { "id": "key_5Gh8Jk1Lm4Np7Qr0St3V", "display": "sk_test_VDhoHnI5…Jxjs", "scopes": [ "orders:read", "orders:write", "prices:read", "products:read", "wallet:read", "webhooks:read" ] }, "server_time": "2026-10-01T10:31:42Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_yYgWsdRadtPqc3YwtyCC x-ratelimit-limit: 60 x-ratelimit-remaining: 59 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## دسته‌های محصول `GET /api/v1/categories` > همه‌ی دسته‌های فروشگاه Stard با تعداد محصولات موجود هر دسته. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/categories" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/categories", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/categories", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/categories", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/categories", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "has_more": false, "next_offset": null, "data": [ { "object": "category", "slug": "gift", "label": "گیفت", "icon": "🎁", "available_products": 4555 }, { "object": "category", "slug": "nft", "label": "NFT", "icon": "💎", "available_products": 0 } ] } ``` **هدرهای پاسخ** ```http x-request-id: req_UX2LNHAEjfTew3qRkZZX x-ratelimit-limit: 60 x-ratelimit-remaining: 58 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## فهرست محصولات `GET /api/v1/products` > جستجو و فیلتر روی همه‌ی محصولات قابل نمایش فروشگاه (همان قانونی که مینی‌اپ استفاده می‌کند). قیمت هر محصول همان مبلغی است که هنگام خرید کسر می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `category` | query | `string` | اختیاری | یکی از `gift`، `nft`، `username`، `number`، `premium`، `stars`، `star_gift`، `other` (جمع‌ها مثل `usernames` هم پذیرفته می‌شوند) | | `search` | query | `string` | اختیاری | جستجو در نام، توضیح یا تگ (حداکثر ۶۴ کاراکتر) | | `pricing_type` | query | `string` | اختیاری | `fixed`، `auction` یا `negotiable` | | `min_price` | query | `integer` | اختیاری | حداقل قیمت (تومان) | | `max_price` | query | `integer` | اختیاری | حداکثر قیمت (تومان) | | `purchasable` | query | `boolean` | اختیاری | فقط محصولاتی که از API قابل خریدند (قیمت ثابت، فروش مستقیم Stard) | | `sort` | query | `string` | اختیاری | `price_asc` (پیش‌فرض)، `price_desc`، `newest`، `oldest` | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products?category=usernames&limit=2" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products?category=usernames&limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products?category=usernames&limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products?category=usernames&limit=2", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products?category=usernames&limit=2", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "product", "id": 22982, "tag": "UNERZA", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "fixed", "price": { "amount": 400000, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-09-11T16:13:53Z" }, { "object": "product", "id": 24214, "tag": "39R5SC", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "auction", "price": { "amount": 750000, "currency": "IRT" }, "starting_price": { "amount": 750000, "currency": "IRT" }, "auction_end_at": "2026-09-16T09:04:19Z", "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-09-15T09:05:35Z" } ], "has_more": true, "next_offset": 2 } ``` **هدرهای پاسخ** ```http x-request-id: req_CrDLZwkMsyARmvYlkkTI x-ratelimit-limit: 60 x-ratelimit-remaining: 57 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## محصولات یک دسته `GET /api/v1/products/{category}` > میان‌بُر برای `/products?category=…`. مقدارهای مجاز: `stars`، `gifts`، `nfts`، `usernames`، `numbers`، `premium`، `star-gifts`، `other`. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `category` | path | `string` | الزامی | نام دسته | | `search` | query | `string` | اختیاری | جستجو | | `sort` | query | `string` | اختیاری | ترتیب | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products/numbers?limit=2" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/numbers?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/numbers?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/numbers?limit=2", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/numbers?limit=2", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "product", "id": 29684, "tag": "8GIXL8", "name": "+888 0000 0000", "description": "شماره‌ی نمونه", "category": "number", "pricing_type": "fixed", "price": { "amount": 121058966, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": "https://fragment.com/number/88804290821", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": "2026-10-01T10:13:09Z", "created_at": "2026-09-30T11:00:07Z" }, { "object": "product", "id": 28390, "tag": "C347DB", "name": "+888 0000 0000", "description": "شماره‌ی نمونه", "category": "number", "pricing_type": "fixed", "price": { "amount": 165659637, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": "https://fragment.com/number/88808679431", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": "2026-10-01T10:13:09Z", "created_at": "2026-09-27T02:22:22Z" } ], "has_more": true, "next_offset": 2 } ``` **هدرهای پاسخ** ```http x-request-id: req_BTMufSqbxAaJyeSmFIOe x-ratelimit-limit: 60 x-ratelimit-remaining: 56 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک محصول `GET /api/v1/products/{id}` > جزئیات کامل یک محصول با شناسه‌ی عددی. فیلد `purchasable_via_api` می‌گوید آیا می‌شود آن را با `POST /orders` خرید؛ اگر نه، `not_purchasable_reason` دلیلش را می‌دهد. > برای گیفت‌های NFT/کالکشنی فیلد `animation` لینک انیمیشن Lottie (JSON، از دامنه‌ی stard-market.ir) را می‌دهد: `{"type":"lottie","url":"https://stard-market.ir/api/miniapp/nft-lottie/plushpepe-1.json","static_url":"https://stard-market.ir/img/n/plushpepe-1.large.webp","thumb_url":"…medium.webp","fragment_url":"https://fragment.com/gift/plushpepe-1"}` و فیلد `nft` ویژگی‌ها را: `slug، collection، number، model، backdrop، symbol` با `*_rarity_percent`، `issued` و `supply`. برای محصولات غیر NFT هر دو `null` است. با lottie-web یا rlottie پخش کنید؛ اگر نشد `static_url` را نشان دهید. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `integer` | الزامی | شناسه‌ی محصول | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products/4518" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/4518", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/4518", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/4518", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/4518", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "product", "id": 4518, "tag": "3Q219N", "name": "پریمیوم ۳ ماهه", "description": "اشتراک تلگرام پریمیوم", "category": "premium", "pricing_type": "fixed", "price": { "amount": 3788624, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": "https://fragment.com/premium", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": "2026-10-01T10:13:50Z", "created_at": "2026-07-25T21:54:14Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_qLVVsy694Fa2wN8KYdZS x-ratelimit-limit: 60 x-ratelimit-remaining: 55 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## محصول با تگ `GET /api/v1/products/tag/{tag}` > هر محصول یک تگ ۶ کاراکتری یکتا دارد (همان که در لینک مینی‌اپ می‌بینی). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `tag` | path | `string` | الزامی | تگ محصول | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products/tag/3Q219N" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/tag/3Q219N", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/tag/3Q219N", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/tag/3Q219N", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/tag/3Q219N", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "product", "id": 4518, "tag": "3Q219N", "name": "پریمیوم ۳ ماهه", "description": "اشتراک تلگرام پریمیوم", "category": "premium", "pricing_type": "fixed", "price": { "amount": 3788624, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "stars_price": null, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": "https://fragment.com/premium", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": "2026-10-01T10:13:50Z", "created_at": "2026-07-25T21:54:14Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_9V3HBcO5OQz9SmUPKVsd x-ratelimit-limit: 60 x-ratelimit-remaining: 54 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت لحظه‌ای یک محصول `GET /api/v1/products/{id}/price` > فقط قیمت و موجودی؛ سبک‌تر از گرفتن کل محصول، برای به‌روزرسانی مکرر قیمت. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `integer` | الزامی | شناسه‌ی محصول | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products/4518/price" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/4518/price", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/4518/price", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/4518/price", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/4518/price", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "price", "product_id": 4518, "amount": 3788624, "currency": "IRT", "available": true, "last_checked_at": "2026-10-01T10:13:50Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_RKM07J2CvuWWJcgOrpdT x-ratelimit-limit: 60 x-ratelimit-remaining: 53 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت استارز، TON و دلار `GET /api/v1/prices` > قیمت لحظه‌ای هر استارز تلگرام، هر TON و هر دلار به تومان؛ همان عددهایی که ربات و مینی‌اپ با آن حساب می‌کنند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/prices" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/prices", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/prices", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "prices", "currency": "IRT", "star": { "amount": 4382, "unit": "1 star" }, "ton": { "amount": 385770, "usd": 1.4976 }, "usd": { "amount": 256300 }, "ton_per_50_stars": 0.5005, "updated_at": "2026-10-01T10:31:48Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_AmLOq7oEgkmmRP8GuGjG x-ratelimit-limit: 60 x-ratelimit-remaining: 52 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت خرید استارز `GET /api/v1/stars/price` > مبلغ دقیق خرید تعداد مشخصی استارز تلگرام. این همان مبلغی است که `POST /orders` با `type=stars` کسر می‌کند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `quantity` | query | `integer` | الزامی | تعداد استارز، ۵۰ تا ۱٬۰۰۰٬۰۰۰ | ### نمونه ```bash curl "https://stard-market.ir/api/v1/stars/price?quantity=500" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/stars/price?quantity=500", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/stars/price?quantity=500", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "stars_price", "quantity": 500, "unit_price": 4382, "amount": 2191000, "currency": "IRT", "updated_at": "2026-10-01T10:31:49Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_idI5wf2XWeB2zE1pe6Ex x-ratelimit-limit: 60 x-ratelimit-remaining: 51 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت تلگرام پریمیوم `GET /api/v1/premium/prices` > پلن‌های ۳، ۶ و ۱۲ ماهه‌ی تلگرام پریمیوم با قیمت لحظه‌ای. برای خرید، `product_id` هر پلن را به `POST /orders` بده. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/premium/prices" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/premium/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/premium/prices", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/premium/prices", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/premium/prices", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "premium_plan", "product_id": 4518, "tag": "3Q219N", "name": "پریمیوم ۳ ماهه", "price": { "amount": 3788624, "currency": "IRT" }, "available": true, "updated_at": "2026-10-01T10:13:50.573556" }, { "object": "premium_plan", "product_id": 4519, "tag": "XOQORP", "name": "پریمیوم ۶ ماهه", "price": { "amount": 5051499, "currency": "IRT" }, "available": true, "updated_at": "2026-10-01T10:13:50.573556" } ], "has_more": false, "next_offset": null } ``` **هدرهای پاسخ** ```http x-request-id: req_W2MMGC6ZvP0A7HY8l2ck x-ratelimit-limit: 60 x-ratelimit-remaining: 50 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## آمار بازار `GET /api/v1/marketplace` > تعداد آیتم‌های موجود، کف قیمت، تعداد مزایده‌ها و آگهی‌های کاربران به تفکیک دسته. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/marketplace" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/marketplace", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/marketplace", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/marketplace", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/marketplace", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "marketplace", "currency": "IRT", "categories": [ { "category": "gift", "available": 4555, "floor_price": 1726086, "auctions": 0, "p2p_listings": 0 }, { "category": "number", "available": 175, "floor_price": 121058966, "auctions": 0, "p2p_listings": 0 } ], "updated_at": "2026-10-01T10:31:49Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_1AH8666Ot6nNS3FYGEZJ x-ratelimit-limit: 60 x-ratelimit-remaining: 49 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## مزایده‌های فعال `GET /api/v1/auctions` > مزایده‌هایی که هنوز تمام نشده‌اند، به ترتیب نزدیک‌ترین زمان پایان، همراه تعداد پیشنهادها و بالاترین پیشنهاد. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/auctions?limit=1" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/auctions?limit=1", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/auctions?limit=1", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/auctions?limit=1", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/auctions?limit=1", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "auction", "id": 23115, "tag": "5NJIL7", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "auction", "price": { "amount": 8500000, "currency": "IRT" }, "starting_price": { "amount": 8500000, "currency": "IRT" }, "auction_end_at": "2026-09-09T03:34:21Z", "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": "https://t.me/S_I_O24", "badge": null, "attributes": null, "community": null, "last_checked_at": null, "created_at": "2026-09-11T18:11:26Z", "bids_count": 0, "highest_bid": null } ], "has_more": true, "next_offset": 1 } ``` **هدرهای پاسخ** ```http x-request-id: req_D0ULDFoPAimc9UX9axr4 x-ratelimit-limit: 60 x-ratelimit-remaining: 48 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک مزایده `GET /api/v1/auctions/{id}` > جزئیات یک مزایده‌ی باز: قیمت پایه، زمان پایان، تعداد پیشنهادها و بالاترین پیشنهاد فعلی به تومان. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `integer` | الزامی | شناسه‌ی محصول مزایده | ### نمونه ```bash curl "https://stard-market.ir/api/v1/auctions/23115" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/auctions/23115", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/auctions/23115", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/auctions/23115", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/auctions/23115", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "auction", "id": 23115, "tag": "5NJIL7", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "auction", "price": { "amount": 8500000, "currency": "IRT" }, "starting_price": { "amount": 8500000, "currency": "IRT" }, "auction_end_at": "2026-09-09T03:34:21Z", "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": "https://t.me/S_I_O24", "badge": null, "attributes": null, "community": null, "last_checked_at": null, "created_at": "2026-09-11T18:11:26Z", "bids_count": 0, "highest_bid": null } ``` **هدرهای پاسخ** ```http x-request-id: req_gxIAl4ZUfJk9yxolFPUx x-ratelimit-limit: 60 x-ratelimit-remaining: 47 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پیشنهادهای یک مزایده `GET /api/v1/auctions/{id}/bids` > پیشنهادها از بیشترین به کمترین. هویت پیشنهاددهنده‌ها برای حفظ حریم خصوصی برگردانده نمی‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `integer` | الزامی | شناسه‌ی محصول مزایده | ### نمونه ```bash curl "https://stard-market.ir/api/v1/auctions/23115/bids" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/auctions/23115/bids", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/auctions/23115/bids", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/auctions/23115/bids", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/auctions/23115/bids", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [], "has_more": false, "next_offset": null } ``` **هدرهای پاسخ** ```http x-request-id: req_7QtF8Xw866pjW3ZyJXty x-ratelimit-limit: 60 x-ratelimit-remaining: 46 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ثبت سفارش `POST /api/v1/orders` > سفارش واقعی روی همان سیستم سفارش Stard. در محیط **live** مبلغ خودکار از کیف پول API (موجودی TON یا تومانی حساب Stard لینک‌شده؛ منبع پیش‌فرض در داشبورد) کسر می‌شود و سفارش مثل خرید از مینی‌اپ انجام می‌شود. در محیط **test** با موجودی آزمایشی شبیه‌سازی می‌شود و هیچ پول یا سفارش واقعی ساخته نمی‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | تا ۶۴ کاراکتر؛ تکرار درخواست با همین کلید همان پاسخ قبلی را برمی‌گرداند و دوباره کسر نمی‌کند. **همیشه بفرست.** | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `type` | `string` | اختیاری | `product` (پیش‌فرض) یا `stars` | | `product_id` | `integer` | اختیاری | برای `type=product` لازم است | | `quantity` | `integer` | اختیاری | برای محصول همیشه ۱؛ برای استارز تعداد (حداقل ۵۰) | | `recipient` | `string` | اختیاری | یوزرنیم تلگرام گیرنده (مثل `@username`)؛ برای استارز و گیفت استارزی لازم است | | `gift_message` | `string` | اختیاری | پیام روی گیفت استارزی (حداکثر ۲۰۰ کاراکتر) | | `pay_currency` | `string` | اختیاری | `TON` یا `IRT`؛ اگر نفرستی، منبع پیش‌فرض کیف پول API در داشبورد (برای حساب تازه TON) | | `metadata` | `object` | اختیاری | تا ۲۰ کلید دلخواه (رشته/عدد/بولین) که همراه سفارش برمی‌گردد؛ مثلاً شماره فاکتور خودت | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-INV-1042" \ -d '{"type": "product", "product_id": 4518, "metadata": {"invoice": "INV-1042"}}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "order-INV-1042", }, body: JSON.stringify({ "type": "product", "product_id": 4518, "metadata": { "invoice": "INV-1042" } }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "order-INV-1042", }, body: JSON.stringify({ "type": "product", "product_id": 4518, "metadata": { "invoice": "INV-1042" } }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "order-INV-1042", }, json={ "type": "product", "product_id": 4518, "metadata": { "invoice": "INV-1042" } }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: order-INV-1042", ], CURLOPT_POSTFIELDS => json_encode([ "type" => "product", "product_id" => 4518, "metadata" => [ "invoice" => "INV-1042" ] ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"type": "product", "product_id": 4518, "metadata": {"invoice": "INV-1042"}}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "order-INV-1042") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "order", "id": "ord_test_gGToQWxqOw89ssiL", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "پریمیوم ۳ ماهه (test)", "product_id": 4518, "product_tag": null, "type": "product", "quantity": 1, "recipient": null, "amount": { "amount": 3788624, "currency": "IRT" }, "paid": { "amount": 3788624, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_Ne8SLkkri4MPzWnBQnQs x-ratelimit-limit: 60 x-ratelimit-remaining: 44 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid / recipient_invalid / p2p_not_supported / not_fixed_price` | بدنه نامعتبر است یا محصول از API قابل خرید نیست | | `402` | `insufficient_funds` | موجودی کیف پول (یا موجودی آزمایشی) کافی نیست | | `403` | `account_not_linked / insufficient_scope` | برای live باید حساب تلگرام Stard وصل باشد؛ یا کلید scope لازم را ندارد | | `404` | `product_not_found` | محصول وجود ندارد یا غیرفعال است | | `409` | `product_unavailable / idempotency_key_reused / request_in_progress` | محصول همین الان ناموجود شد، یا کلید idempotency با بدنه‌ی دیگری استفاده شده | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد)؛ ثبت سفارش جداگانه حداکثر ۲۰ در دقیقه برای هر کلید. وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## فهرست سفارش‌ها `GET /api/v1/orders` > سفارش‌هایی که از طریق API و در همین پروژه ثبت شده‌اند (کلیدهای پروژه‌های دیگر و سفارش‌های مینی‌اپ دیده نمی‌شوند). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `status` | query | `string` | اختیاری | `pending`، `processing`، `completed`، `cancelled`، `refunded`، `failed` | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/orders?limit=2" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/orders?limit=2", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/orders?limit=2", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "order", "id": "ord_test_TyrINakBwx0N66kV", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "⭐ 500 استارز برای @durov (test)", "product_id": null, "product_tag": null, "type": "stars", "quantity": 500, "recipient": "@durov", "amount": { "amount": 2191000, "currency": "IRT" }, "paid": { "amount": 2191000, "currency": "IRT" }, "failure_reason": null, "metadata": {}, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" }, { "object": "order", "id": "ord_test_gGToQWxqOw89ssiL", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "پریمیوم ۳ ماهه (test)", "product_id": 4518, "product_tag": null, "type": "product", "quantity": 1, "recipient": null, "amount": { "amount": 3788624, "currency": "IRT" }, "paid": { "amount": 3788624, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ], "has_more": false, "next_offset": null } ``` **هدرهای پاسخ** ```http x-request-id: req_RU9oUhGcunV1Q8i3frYJ x-ratelimit-limit: 60 x-ratelimit-remaining: 42 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک سفارش `GET /api/v1/orders/{id}` > وضعیت لحظه‌ای یک سفارش. `id` همان کد پیگیری است (در test با `ord_test_` شروع می‌شود). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش | ### نمونه ```bash curl "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_gGToQWxqOw89ssiL", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "پریمیوم ۳ ماهه (test)", "product_id": 4518, "product_tag": null, "type": "product", "quantity": 1, "recipient": null, "amount": { "amount": 3788624, "currency": "IRT" }, "paid": { "amount": 3788624, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_7lv7TszXd4Zidg8EB0EL x-ratelimit-limit: 60 x-ratelimit-remaining: 41 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## لغو سفارش `POST /api/v1/orders/{id}/cancel` > فقط سفارشی که هنوز انجامش شروع نشده (`pending`) لغو می‌شود و مبلغ کامل به همان کیف پول برمی‌گردد. اگر ربات خرید را شروع کرده باشد، لغو پذیرفته نمی‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/cancel" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/cancel", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/cancel", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_gGToQWxqOw89ssiL", "order_id": null, "environment": "test", "status": "cancelled", "raw_status": "cancelled", "title": "پریمیوم ۳ ماهه (test)", "product_id": 4518, "product_tag": null, "type": "product", "quantity": 1, "recipient": null, "amount": { "amount": 3788624, "currency": "IRT" }, "paid": { "amount": 3788624, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-01T10:31:49Z", "updated_at": "2026-10-01T10:31:49Z" } ``` **هدرهای پاسخ** ```http x-request-id: req_mu2QDMdXrXixTsWPwpRr x-ratelimit-limit: 60 x-ratelimit-remaining: 39 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `409` | `order_not_cancellable` | انجام سفارش شروع شده یا تمام شده است | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## موجودی کیف پول `GET /api/v1/wallet` > در live موجودی تومانی و TON حساب Stard لینک‌شده؛ در test موجودی آزمایشی. مقدار TON رشته‌ی دقیق با ۹ رقم اعشار است (هرگز float). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/wallet" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "wallet", "environment": "test", "balances": [ { "currency": "IRT", "amount": 100000000 } ], "note": "موجودی آزمایشی؛ پول واقعی نیست." } ``` **هدرهای پاسخ** ```http x-request-id: req_SKfBrfznPc6SZbXpF5yg x-ratelimit-limit: 60 x-ratelimit-remaining: 45 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## تراکنش‌ها `GET /api/v1/transactions` > دفتر کل کیف پول از جدید به قدیم: خرید، برگشت وجه، واریز، برداشت و… . مبلغ منفی یعنی کسر. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/transactions?limit=2" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/transactions?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/transactions?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/transactions?limit=2", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/transactions?limit=2", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "transaction", "id": "txn_test_2", "type": "purchase", "currency": "IRT", "amount": -2191000, "status": "pending", "reference": "ord_test_TyrINakBwx0N66kV", "created_at": "2026-10-01T10:31:49Z" }, { "object": "transaction", "id": "txn_test_1", "type": "purchase", "currency": "IRT", "amount": -3788624, "status": "pending", "reference": "ord_test_gGToQWxqOw89ssiL", "created_at": "2026-10-01T10:31:49Z" } ], "has_more": false, "next_offset": null } ``` **هدرهای پاسخ** ```http x-request-id: req_YtDUlxSc9Z2dFnEgj4rz x-ratelimit-limit: 60 x-ratelimit-remaining: 40 x-ratelimit-reset: 1790850720 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پیش‌قیمت سفارش `POST /api/v1/orders/quote` > قبل از ثبت سفارش، مبلغ نهایی را به تومان (و معادل TON) بگیر و به مشتری نشان بده. پاسخ یک `id` امضاشده دارد که تا `expires_at` (۲ دقیقه) معتبر است؛ آن را به‌صورت `quote_id` به `POST /orders`، `/boosts/orders` یا `/gifts/send` بده تا اگر قیمت در این فاصله بالا رفت، سفارش بدون کسر پول با `409 price_changed` رد شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `type` | `string` | الزامی | `stars`، `product` یا `boost` | | `quantity` | `integer` | اختیاری | تعداد (استارز حداقل ۵۰؛ بوست ۱ تا سقف) | | `product_id` | `integer` | اختیاری | برای type=product | | `duration` | `integer` | اختیاری | برای type=boost: مدت به روز (از GET /boosts) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders/quote" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type": "stars", "quantity": 500}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/quote", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "type": "stars", "quantity": 500 }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/quote", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "type": "stars", "quantity": 500 }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders/quote", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "type": "stars", "quantity": 500 }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "type" => "stars", "quantity" => 500 ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"type": "stars", "quantity": 500}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/quote", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "quote", "id": "qt_1790963122_2249000_122dd345912201ab58da15f0ac16f63a", "type": "stars", "quantity": 500, "product_id": null, "duration": null, "amount": 2249000, "unit_price": 4498, "currency": "IRT", "ton_amount": "5.6342", "product_available": true, "not_available_reason": null, "expires_at": "2026-10-02T17:45:22Z", "note": "quote_id را به POST /orders یا /boosts/orders بده؛ اگر قیمت تا آن لحظه بالا رفته باشد سفارش با 409 price_changed رد می‌شود و پولی کسر نمی‌شود." } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_ZykdDzNsBRzXELW04rdp x-ratelimit-limit: 1000 x-ratelimit-remaining: 999 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | نوع/تعداد نامعتبر | | `404` | `product_not_found` | محصول پیدا نشد | | `409` | `boost_unavailable` | این مدت/تعداد بوست فعلاً موجود نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## بازپرداخت سفارش `POST /api/v1/orders/{id}/refund` > بازپرداخت خودکار سفارشی که هنوز انجامش شروع نشده؛ کل مبلغ به همان کیف پول برمی‌گردد. سفارش انجام‌شده خودکار قابل بازپرداخت نیست (برای آن با پشتیبانی تماس بگیر). برای بوست، اگر سفارش به پنل ارسال شده باشد بازپرداخت پذیرفته نمی‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_9pq3kfjbTmRLfMDR", "order_id": null, "environment": "test", "status": "cancelled", "raw_status": "cancelled", "title": "⭐ 500 استارز برای @username (test)", "product_id": null, "product_tag": null, "type": "stars", "quantity": 500, "recipient": "@username", "amount": { "amount": 2249000, "currency": "IRT" }, "paid": { "amount": 2249000, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-1042" }, "created_at": "2026-10-02T17:43:22Z", "updated_at": "2026-10-02T17:43:22Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_dAlugYNqQS5ouO3hP82I x-ratelimit-limit: 1000 x-ratelimit-remaining: 996 ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** وقتی سفارشی را ثبت کرده‌ای ولی هنوز انجامش شروع نشده و می‌خواهی پول برگردد؛ مثلاً یوزرنیم گیرنده اشتباه وارد شده یا مشتری فروشگاهت پشیمان شده است. 1. وضعیت سفارش را با [`GET /orders/{id}`](https://stard-market.ir/docs/reference/orders-get) بگیر؛ فقط سفارشی که انجامش شروع نشده خودکار برمی‌گردد. 2. `POST /orders/{id}/refund` را بزن. پاسخ همان شیء سفارش با وضعیت تازه است و کل مبلغ به همان کیف پولی که از آن کسر شده بود برمی‌گردد. 3. نتیجه را با [`GET /orders/{id}/refund`](https://stard-market.ir/docs/reference/orders-refund-status) یا وب‌هوک `order.*` تأیید کن. - سفارش انجام‌شده (استارز تحویل‌شده، گیفت ارسال‌شده) خودکار برنمی‌گردد و خطای `409 order_not_refundable` می‌دهد؛ برای آن با پشتیبانی تماس بگیر. - سفارش بوستی که به پنل تحویل ارسال شده هم خودکار برنمی‌گردد؛ بخش تحویل‌نشده‌ی بوست را خود سیستم خودکار برمی‌گرداند. - در محیط test هیچ پول واقعی جابه‌جا نمی‌شود؛ رفتار پاسخ همان live است. ### خطاها | HTTP | code | کی | |---|---|---| | `409` | `order_not_refundable` | انجام سفارش شروع شده یا تمام شده | | `404` | `order_not_found` | سفارش پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت بازپرداخت `GET /api/v1/orders/{id}/refund` > آیا مبلغ این سفارش برگشت داده شده و چقدر. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "refund", "order_id": "ord_test_9pq3kfjbTmRLfMDR", "refunded": true, "amount": { "amount": 2249000, "currency": "IRT" } } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_o7BQtSz6FuklFTgGJiQP x-ratelimit-limit: 1000 x-ratelimit-remaining: 995 ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** برای نمایش «پول برگشت» در پنل مشتری یا تطبیق حساب: پاسخ می‌گوید مبلغ این سفارش برگشت داده شده یا نه (`refunded`) و چقدر (`amount` به تومان، `currency: "IRT"`). - این اندپوینت فقط می‌خواند و چیزی را تغییر نمی‌دهد؛ scope آن `orders:read` است و می‌شود با کلید فقط‌خواندنی صدایش زد. - برگشت‌هایی که خود سیستم انجام می‌دهد (سفارش ناموفق، بخش تحویل‌نشده‌ی بوست) هم اینجا دیده می‌شوند، نه فقط بازپرداخت دستی با [`POST /refund`](https://stard-market.ir/docs/reference/orders-refund). - به‌جای poll کردن مداوم، وب‌هوک `order.*` را فعال کن و فقط وقتی تغییری آمد این را بخوان ([وب‌هوک‌ها](https://stard-market.ir/docs/webhooks)). ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `order_not_found` | سفارش پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## بوست کانال: مدت‌ها و قیمت `GET /api/v1/boosts` > مدت‌های قابل فروش بوست کانال/گروه تلگرام، قیمت هر بوست و سقف تعداد در هر سفارش. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/boosts" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/boosts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/boosts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/boosts", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/boosts", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "boost_catalog", "enabled": true, "currency": "IRT", "max_quantity": 1000, "durations": [ { "duration": 7, "label": "۷ روزه", "price_per_boost": 13200, "available": true }, { "duration": 14, "label": "۱۴ روزه", "price_per_boost": null, "available": false }, { "duration": 30, "label": "۱ ماهه", "price_per_boost": 32100, "available": true }, { "duration": 60, "label": "۲ ماهه", "price_per_boost": 79500, "available": true } ], "raw": null } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_0gcZ6fXsruRRhsu6DSbU x-ratelimit-limit: 1000 x-ratelimit-remaining: 994 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت دقیق بوست `GET /api/v1/boosts/price` > مبلغ دقیق سفارش بوست برای تعداد و مدت مشخص؛ همان مبلغی که `POST /boosts/orders` کسر می‌کند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `quantity` | query | `integer` | الزامی | تعداد بوست | | `duration` | query | `integer` | الزامی | مدت به روز | ### نمونه ```bash curl "https://stard-market.ir/api/v1/boosts/price?quantity=10&duration=30" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/boosts/price?quantity=10&duration=30", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/boosts/price?quantity=10&duration=30", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/boosts/price?quantity=10&duration=30", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/boosts/price?quantity=10&duration=30", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "boost_price", "quantity": 10, "duration": 7, "duration_label": "۷ روزه", "amount": 132000, "price_per_boost": 13200, "currency": "IRT", "delivery": "automatic" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_TiBaArqv4tAc2rkxhI9h x-ratelimit-limit: 1000 x-ratelimit-remaining: 993 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `409` | `boost_unavailable` | این مدت/تعداد فعلاً موجود نیست | | `503` | `boost_disabled` | فروش بوست موقتاً غیرفعال است | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ثبت سفارش بوست `POST /api/v1/boosts/orders` > بوست کانال یا گروه عمومی تلگرام را بخر. تحویل خودکار است و پیشرفتش در `boost.delivered` و `boost.remaining` سفارش برمی‌گردد؛ اگر بخشی تحویل نشود، مبلغش خودکار برمی‌گردد. مثل همه‌ی سفارش‌ها از `Idempotency-Key` و `quote_id` پشتیبانی می‌کند و تغییر وضعیتش با وب‌هوک `order.*` خبر داده می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا برای جلوگیری از سفارش تکراری | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `recipient` | `string` | الزامی | `@channel` یا `t.me/channel` (کانال/گروه عمومی) | | `quantity` | `integer` | الزامی | تعداد بوست | | `duration` | `integer` | الزامی | مدت به روز | | `pay_currency` | `string` | اختیاری | `TON` یا `IRT`؛ پیش‌فرض منبع داشبورد | | `quote_id` | `string` | اختیاری | از POST /orders/quote | | `metadata` | `object` | اختیاری | داده‌ی دلخواه تو (حداکثر ۲۰۰۰ کاراکتر) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/boosts/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: boost-2001" \ -d '{"recipient": "@your_channel", "quantity": 10, "duration": 30, "metadata": {"invoice": "INV-2001"}}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/boosts/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "boost-2001", }, body: JSON.stringify({ "recipient": "@your_channel", "quantity": 10, "duration": 30, "metadata": { "invoice": "INV-2001" } }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/boosts/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "boost-2001", }, body: JSON.stringify({ "recipient": "@your_channel", "quantity": 10, "duration": 30, "metadata": { "invoice": "INV-2001" } }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/boosts/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "boost-2001", }, json={ "recipient": "@your_channel", "quantity": 10, "duration": 30, "metadata": { "invoice": "INV-2001" } }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: boost-2001", ], CURLOPT_POSTFIELDS => json_encode([ "recipient" => "@your_channel", "quantity" => 10, "duration" => 30, "metadata" => [ "invoice" => "INV-2001" ] ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"recipient": "@your_channel", "quantity": 10, "duration": 30, "metadata": {"invoice": "INV-2001"}}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/boosts/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "boost-2001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "order", "id": "ord_test_filwZurNgDCrQ9fD", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "🚀 10 بوست 7 روزه برای @your_channel (test)", "product_id": null, "product_tag": null, "type": "boost", "quantity": 10, "recipient": "@your_channel", "amount": { "amount": 132000, "currency": "IRT" }, "paid": { "amount": 132000, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-2001" }, "created_at": "2026-10-02T17:43:23Z", "updated_at": "2026-10-02T17:43:23Z", "duration": 7 } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_14gx0dkOlUtkDjGi3ilp x-ratelimit-limit: 1000 x-ratelimit-remaining: 992 ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** برای فروش خودکار بوست کانال یا گروه عمومی تلگرام در فروشگاه یا ربات خودت. ترتیب پیشنهادی: 1. مدت‌ها و سقف هر سفارش را از [`GET /boosts`](https://stard-market.ir/docs/reference/boosts) بخوان. 2. مبلغ دقیق را با [`GET /boosts/price`](https://stard-market.ir/docs/reference/boosts-price) بگیر (یا برای قفل قیمت از [پیش‌قیمت](https://stard-market.ir/docs/reference/orders-quote) و `quote_id` استفاده کن). 3. سفارش را با `Idempotency-Key` ثبت کن تا تکرار درخواست به خاطر قطعی شبکه، دو بار پول کم نکند. 4. پیشرفت را در `boost.delivered` و `boost.remaining` با [`GET /boosts/orders/{id}`](https://stard-market.ir/docs/reference/boosts-order-get) یا وب‌هوک ببین. - کانال یا گروه باید عمومی باشد (یوزرنیم داشته باشد)؛ گیرنده را به شکل `@channel` بفرست. - اگر بخشی از بوست‌ها تحویل نشود، مبلغ همان بخش خودکار به کیف پول برمی‌گردد؛ لازم نیست بازپرداخت دستی بزنی. - بوست ممبر یا بازدید اضافه نمی‌کند؛ سطح کانال را بالا می‌برد ([بوست تلگرام چیست](https://stard-market.ir/boost)). ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `recipient_invalid` | کانال/گروه عمومی پیدا نشد یا اکانت شخصی است | | `402` | `insufficient_funds` | موجودی کیف پول API (یا موجودی آزمایشی) کافی نیست | | `400` | `quote_invalid / quote_mismatch` | quote_id نامعتبر یا مال سفارش دیگری است | | `409` | `quote_expired` | مهلت پیش‌قیمت (۲ دقیقه) تمام شده | | `409` | `price_changed` | قیمت از مبلغ پیش‌قیمت بالاتر رفته؛ پولی کسر نشده | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت سفارش بوست `GET /api/v1/boosts/orders/{id}` > وضعیت سفارش بوست به‌همراه پیشرفت تحویل. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/boosts/orders/ord_test_gGToQWxqOw89ssiL" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/boosts/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/boosts/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/boosts/orders/ord_test_gGToQWxqOw89ssiL", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/boosts/orders/ord_test_gGToQWxqOw89ssiL", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_filwZurNgDCrQ9fD", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "🚀 10 بوست 7 روزه برای @your_channel (test)", "product_id": null, "product_tag": null, "type": "boost", "quantity": 10, "recipient": "@your_channel", "amount": { "amount": 132000, "currency": "IRT" }, "paid": { "amount": 132000, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-2001" }, "created_at": "2026-10-02T17:43:23Z", "updated_at": "2026-10-02T17:43:23Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_66D4PvmtsgQ61vPdzgKs x-ratelimit-limit: 1000 x-ratelimit-remaining: 991 ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** برای نشان دادن پیشرفت تحویل بوست به مشتری. فیلدهای مهم پاسخ: `status` (وضعیت کلی سفارش)، `quantity` و `duration` (تعداد و مدت سفارش)، و پیشرفت تحویل در `boost.delivered` / `boost.remaining`. - تا وقتی `status` نهایی نشده (`completed`، `failed`، `refunded` یا `cancelled`)، هر چند دقیقه یک بار بخوان یا منتظر وب‌هوک `order.*` بمان. - اگر بخشی تحویل نشد، مبلغ آن بخش خودکار برمی‌گردد و در [وضعیت بازپرداخت](https://stard-market.ir/docs/reference/orders-refund-status) دیده می‌شود. - همین سفارش در [`GET /orders`](https://stard-market.ir/docs/reference/orders-list) هم با `type: "boost"` می‌آید. ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `order_not_found` | سفارش بوست پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## گیفت‌های استارزی `GET /api/v1/gifts` > گیفت‌های استارزی تلگرام (قلب، خرس، کادو، گل و…) که می‌شود به هر یوزرنیم فرستاد، با قیمت تومانی و قیمت استارزی. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/gifts" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/gifts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/gifts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/gifts", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/gifts", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "product", "id": 12577, "tag": "7ZI3FR", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 112275, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 25, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T20:06:40Z" }, { "object": "product", "id": 12578, "tag": "0QNT85", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 224550, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 50, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T20:07:19Z" }, { "object": "product", "id": 12582, "tag": "QI3ZAL", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 224550, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 50, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:09:45Z" }, { "object": "product", "id": 12583, "tag": "LVMGBH", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 224550, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 50, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:10:30Z" }, { "object": "product", "id": 12584, "tag": "E0J9LV", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 449100, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 100, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:11:13Z" }, { "object": "product", "id": 12585, "tag": "V1T27L", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 449100, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 100, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:11:57Z" }, { "object": "product", "id": 12586, "tag": "S98KHZ", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 449100, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 100, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:12:41Z" }, { "object": "product", "id": 12587, "tag": "KAWJM1", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 67365, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 15, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-05T21:18:48Z" }, { "object": "product", "id": 14510, "tag": "HG32HO", "name": "محصول نمونه", "description": "توضیح نمونه", "category": "star_gift", "pricing_type": "fixed", "price": { "amount": 67365, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": 15, "available": true, "purchasable_via_api": true, "not_purchasable_reason": null, "marketplace": "stard", "image_url": "https://stard-market.ir/img/sample.webp", "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-08-15T17:22:21Z" } ], "has_more": false, "next_offset": null, "total": 9 } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_xEpDmeW2Hn9NLgUmt1Q7 x-ratelimit-limit: 1000 x-ratelimit-remaining: 990 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ارسال گیفت به یوزرنیم `POST /api/v1/gifts/send` > یک گیفت استارزی را مستقیم به یوزرنیم تلگرام بفرست، با پیام اختیاری روی گیفت. تفاوتش با `POST /orders`: فقط گیفت می‌پذیرد، گیرنده اجباری است و پیام گیفت فیلد مستقیم دارد. سفارش ساخته‌شده همان سفارش استاندارد است. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `product_id` | `integer` | الزامی | از GET /gifts | | `recipient` | `string` | الزامی | @username گیرنده | | `message` | `string` | اختیاری | پیام روی گیفت، حداکثر ۲۰۰ کاراکتر | | `message_entities` | `array` | اختیاری | entities تلگرام برای پیام (bold، custom_emoji و…) | | `hide_sender` | `boolean` | اختیاری | فرستنده‌ی مخفی (+۲٬۰۰۰ تومان) | | `scheduled_at` | `string` | اختیاری | زمان ارسال برنامه‌ریزی‌شده (ISO 8601) | | `pay_currency` | `string` | اختیاری | TON یا IRT | | `quote_id` | `string` | اختیاری | از POST /orders/quote با type=product | | `metadata` | `object` | اختیاری | داده‌ی دلخواه | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/gifts/send" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"product_id": 12, "recipient": "@username", "message": "تولدت مبارک 🎉"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/gifts/send", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "product_id": 12, "recipient": "@username", "message": "تولدت مبارک 🎉" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/gifts/send", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "product_id": 12, "recipient": "@username", "message": "تولدت مبارک 🎉" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/gifts/send", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "product_id": 12, "recipient": "@username", "message": "تولدت مبارک 🎉" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "product_id" => 12, "recipient" => "@username", "message" => "تولدت مبارک 🎉" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"product_id": 12, "recipient": "@username", "message": "تولدت مبارک 🎉"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/gifts/send", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "order", "id": "ord_test_znAt8QplAwwQImWM", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "کادو (test)", "product_id": 12577, "product_tag": null, "type": "gift", "quantity": 1, "recipient": "@username", "amount": { "amount": 112275, "currency": "IRT" }, "paid": { "amount": 112275, "currency": "IRT" }, "failure_reason": null, "metadata": {}, "created_at": "2026-10-02T17:43:23Z", "updated_at": "2026-10-02T17:43:23Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_XhAAu3bzRaDHeDIToYdd x-ratelimit-limit: 1000 x-ratelimit-remaining: 989 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `not_a_gift` | این product_id گیفت استارزی نیست | | `400` | `recipient_invalid` | یوزرنیم گیرنده نامعتبر | | `402` | `insufficient_funds` | موجودی کیف پول API (یا موجودی آزمایشی) کافی نیست | | `400` | `quote_invalid / quote_mismatch` | quote_id نامعتبر یا مال سفارش دیگری است | | `409` | `quote_expired` | مهلت پیش‌قیمت (۲ دقیقه) تمام شده | | `409` | `price_changed` | قیمت از مبلغ پیش‌قیمت بالاتر رفته؛ پولی کسر نشده | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت ارسال گیفت `GET /api/v1/gifts/orders/{id}` > وضعیت سفارش ارسال گیفت. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/gifts/orders/ord_test_gGToQWxqOw89ssiL" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/gifts/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/gifts/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/gifts/orders/ord_test_gGToQWxqOw89ssiL", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/gifts/orders/ord_test_gGToQWxqOw89ssiL", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_znAt8QplAwwQImWM", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "کادو (test)", "product_id": 12577, "product_tag": null, "type": "gift", "quantity": 1, "recipient": "@username", "amount": { "amount": 112275, "currency": "IRT" }, "paid": { "amount": 112275, "currency": "IRT" }, "failure_reason": null, "metadata": {}, "created_at": "2026-10-02T17:43:23Z", "updated_at": "2026-10-02T17:43:23Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_8o0TBZ88THVz8uSSkOpZ x-ratelimit-limit: 1000 x-ratelimit-remaining: 988 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `order_not_found` | سفارش پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## بررسی یوزرنیم `GET /api/v1/usernames/check` > آیا این یوزرنیم در فروشگاه Stard برای فروش هست و قیمتش چقدر است. وضعیت مالکیت یا حراج خارج از Stard را از `fragment_url` ببین. برای ابزارهای مانیتورینگ یوزرنیم. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `username` | query | `string` | الزامی | یوزرنیم با یا بدون @ | ### نمونه ```bash curl "https://stard-market.ir/api/v1/usernames/check?username=example" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/usernames/check?username=example", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/usernames/check?username=example", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/usernames/check?username=example", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/usernames/check?username=example", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "username", "username": "example", "listed_on_stard": false, "available_to_buy": false, "price": null, "product_id": null, "fragment_url": "https://fragment.com/username/example", "note": "در فروشگاه Stard نیست؛ وضعیت مالکیت/حراج را در Fragment ببین." } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_0pt9R1qkU4RWLcuyDhSh x-ratelimit-limit: 1000 x-ratelimit-remaining: 986 ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** برای ابزار جست‌وجو یا مانیتورینگ یوزرنیم: می‌گوید یوزرنیم در فروشگاه Stard فروشی هست یا نه (`listed_on_stard`، `available_to_buy`)، قیمتش (`price` به تومان) و شناسه‌ی محصول برای خرید با [`POST /orders`](https://stard-market.ir/docs/reference/orders-create). - اگر یوزرنیم در Stard نیست، `fragment_url` صفحه‌ی همان یوزرنیم در فرگمنت است؛ مالکیت، مزایده و فروش خارج از Stard را آنجا ببین. - ورودی با یا بدون `@` پذیرفته می‌شود؛ یوزرنیم معتبر ۴ تا ۳۲ کاراکتر است و با حرف شروع می‌شود، وگرنه `400 parameter_invalid`. - برای فهرست کامل یوزرنیم‌های فروشی از [`GET /products/usernames`](https://stard-market.ir/docs/reference/products-category) استفاده کن و برای راهنمای عمومی [خرید یوزرنیم تلگرام](https://stard-market.ir/username) را ببین. ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | یوزرنیم نامعتبر (۴ تا ۳۲ کاراکتر، شروع با حرف) | | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک یوزرنیم `GET /api/v1/usernames/{username}` > همان بررسی، با یوزرنیم در مسیر. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `username` | path | `string` | الزامی | یوزرنیم | ### نمونه ```bash curl "https://stard-market.ir/api/v1/usernames/tiniest" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/usernames/tiniest", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/usernames/tiniest", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/usernames/tiniest", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/usernames/tiniest", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "username", "username": "tiniest", "listed_on_stard": true, "available_to_buy": false, "type": "collectible", "price": { "amount": 434647658, "currency": "IRT" }, "product_id": 7719, "marketplace": "stard", "fragment_url": "https://fragment.com/username/tiniest" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_J8168erzB5bAAboxbK0B x-ratelimit-limit: 1000 x-ratelimit-remaining: 987 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | یوزرنیم نامعتبر | | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## آگهی‌های بازار P2P `GET /api/v1/listings` > آگهی‌های فعال کاربران (یوزرنیم، شماره، گیفت و…) — فقط خواندنی. ثبت آگهی فروش از API ممکن نیست، چون مالکیت آیتم باید داخل تلگرام تأیید شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `category` | query | `string` | اختیاری | slug دسته | | `limit` | query | `integer` | اختیاری | تعداد نتیجه در هر صفحه، ۱ تا ۱۰۰ (پیش‌فرض ۲۰) | | `offset` | query | `integer` | اختیاری | چند ردیف رد شود (پیش‌فرض ۰)؛ برای صفحه‌ی بعد از `next_offset` استفاده کن | ### نمونه ```bash curl "https://stard-market.ir/api/v1/listings?limit=2" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/listings?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/listings?limit=2", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/listings?limit=2", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/listings?limit=2", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "product", "id": 30244, "tag": "Y3CAMI", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "auction", "price": { "amount": 4000000, "currency": "IRT" }, "starting_price": { "amount": 4000000, "currency": "IRT" }, "auction_end_at": "2026-10-04T07:23:41Z", "auction_ended": false, "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": null, "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-10-02T08:13:03Z" }, { "object": "product", "id": 30243, "tag": "F1UOH5", "name": "@stard_sample", "description": "یوزرنیم نمونه", "category": "username", "pricing_type": "fixed", "price": { "amount": 1000000, "currency": "IRT" }, "starting_price": null, "auction_end_at": null, "auction_ended": false, "stars_price": null, "available": true, "purchasable_via_api": false, "not_purchasable_reason": "p2p_not_supported", "marketplace": "p2p", "image_url": null, "link": "https://t.me/ShellCrab", "badge": null, "attributes": null, "animation": null, "nft": null, "community": null, "last_checked_at": null, "created_at": "2026-10-02T08:12:59Z" } ], "has_more": true, "next_offset": 2, "total": 22 } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_ogiv4hTa9qbdKzeamFtt x-ratelimit-limit: 1000 x-ratelimit-remaining: 985 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## سابقه‌ی فروش NFT `GET /api/v1/nfts/{slug}/history` > سابقه‌ی فروش یک گیفت NFT (مثل `plushpepe-1234`): آخرین فروش، بالاترین و پایین‌ترین قیمت و فهرست فروش‌ها با مدل، پس‌زمینه و نماد، به TON و تومان. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `slug` | path | `string` | الزامی | کالکشن-شماره، مثل plushpepe-1234 | ### نمونه ```bash curl "https://stard-market.ir/api/v1/nfts/plushpepe-1234/history" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/nfts/plushpepe-1234/history", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/nfts/plushpepe-1234/history", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/nfts/plushpepe-1234/history", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/nfts/plushpepe-1234/history", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "nft_history", "gift": "finepen-24624", "sales_count": 4, "last_sale": { "gift": "finepen-24624", "collection": "finepen", "number": 24624, "model": "Signature Scribe", "backdrop": "Moonstone", "symbol": "White Deer", "price_ton": 10.0, "price_irt": 3991680, "sold_at": "2026-09-21T21:07:46Z", "source": "purchase" }, "highest_ton": 10.0, "lowest_ton": 8.0, "sales": [ { "gift": "finepen-24624", "collection": "finepen", "number": 24624, "model": "Signature Scribe", "backdrop": "Moonstone", "symbol": "White Deer", "price_ton": 10.0, "price_irt": 3991680, "sold_at": "2026-09-21T21:07:46Z", "source": "purchase" }, { "gift": "finepen-24624", "collection": "finepen", "number": 24624, "model": "Signature Scribe", "backdrop": "Moonstone", "symbol": "White Deer", "price_ton": 8.85, "price_irt": 3532636, "sold_at": "2026-09-13T10:07:55Z", "source": "history" }, { "gift": "finepen-24624", "collection": "finepen", "number": 24624, "model": "Signature Scribe", "backdrop": "Moonstone", "symbol": "White Deer", "price_ton": 10.0, "price_irt": 3991680, "sold_at": "2026-09-07T20:46:40Z", "source": "history" } ], "note": "سابقه‌ی فروش‌های ثبت‌شده در بازار؛ مالک فعلی و انتقال‌های بدون فروش در این داده نیست." } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_m4DH4WctKq0TySlwuMV7 x-ratelimit-limit: 1000 x-ratelimit-remaining: 984 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | slug نامعتبر | | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## آمار کالکشن NFT `GET /api/v1/nfts/collections/{slug}/stats` > حجم معاملات ۲۴ ساعت/۷ روز/۳۰ روز، تعداد فروش، میانگین، بالاترین و پایین‌ترین فروش، تغییر قیمت ۲۴ ساعته و ۷ روزه و کف قیمت در Stard. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `slug` | path | `string` | الزامی | slug کالکشن، مثل plushpepe | ### نمونه ```bash curl "https://stard-market.ir/api/v1/nfts/collections/plushpepe/stats" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/nfts/collections/plushpepe/stats", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/nfts/collections/plushpepe/stats", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/nfts/collections/plushpepe/stats", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/nfts/collections/plushpepe/stats", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "collection": "finepen", "volume_24h_ton": 27.99, "volume_7d_ton": 27.99, "volume_30d_ton": 85.84, "sales_24h": 3, "sales_7d": 3, "sales_30d": 10, "average_price_7d_ton": 9.33, "highest_sale_30d_ton": 10.0, "lowest_sale_30d_ton": 2.0, "price_change_24h_percent": null, "price_change_7d_percent": 20.39, "active_listings_on_stard": 15, "floor_price_on_stard": { "amount": 4023613, "currency": "IRT" }, "ton_rate_irt": 399168, "object": "collection_stats" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_qVYBIZExg4YE4R4Wh31s x-ratelimit-limit: 1000 x-ratelimit-remaining: 983 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | slug نامعتبر | | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## آمار بازار گیفت‌ها `GET /api/v1/market/stats` > آمار ۲۴ ساعت بازار گیفت‌ها و NFTهای تلگرام: تعداد و حجم فروش، میانگین، بالاترین و پایین‌ترین فروش، آگهی‌های فعال و پرمعامله‌ترین کالکشن‌ها. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `limit` | query | `integer` | اختیاری | تعداد کالکشن‌های برتر (پیش‌فرض ۲۰) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/market/stats?limit=5" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/market/stats?limit=5", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/market/stats?limit=5", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/market/stats?limit=5", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/market/stats?limit=5", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "market_stats", "window": "24h", "sales_count": 148, "volume_ton": 1228.5464, "volume_irt": 490396391, "average_price_ton": 8.301, "highest_sale_ton": 247.0, "lowest_sale_ton": 3.0, "active_listings_on_stard": 5156, "ton_rate_irt": 399168, "top_collections": [ { "collection": "scaredcat", "sales": 1, "volume_ton": 247.0 }, { "collection": "chillflame", "sales": 30, "volume_ton": 124.2433 }, { "collection": "lootbag", "sales": 1, "volume_ton": 120.0 }, { "collection": "minioscar", "sales": 1, "volume_ton": 70.0 }, { "collection": "vicecream", "sales": 14, "volume_ton": 59.21 } ], "updated_at": "2026-10-02T17:43:24Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_eAG7Px1rSxyTsBqoYGLR x-ratelimit-limit: 1000 x-ratelimit-remaining: 982 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `products:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## تاریخچه‌ی قیمت استارز `GET /api/v1/prices/history` > قیمت هر استارز به تومان در طول زمان؛ برای نمودار، تحلیل بازار و ربات‌های هشدار. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `interval` | query | `string` | اختیاری | `1h`، `6h` یا `1d` (پیش‌فرض 1h) | | `from` | query | `string` | اختیاری | شروع ISO-8601 (پیش‌فرض ۷ روز قبل) | | `to` | query | `string` | اختیاری | پایان ISO-8601 | ### نمونه ```bash curl "https://stard-market.ir/api/v1/prices/history?interval=1d" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/prices/history?interval=1d", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/prices/history?interval=1d", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/prices/history?interval=1d", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/prices/history?interval=1d", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "price_history", "asset": "stars", "unit": "1 star", "currency": "IRT", "interval": "1d", "from": "2026-09-25T17:43:24Z", "to": "2026-10-02T17:43:24Z", "data": [ { "timestamp": "2026-09-29T00:00:00Z", "price": 4399, "usd": 0.017339 }, { "timestamp": "2026-09-30T00:00:00Z", "price": 4385, "usd": 0.017216 }, { "timestamp": "2026-10-01T00:00:00Z", "price": 4373, "usd": 0.016919 }, { "timestamp": "2026-10-02T00:00:00Z", "price": 4496, "usd": 0.017395 } ] } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_Ra6aZKHa9yQK09crMpat x-ratelimit-limit: 1000 x-ratelimit-remaining: 981 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | interval یا تاریخ نامعتبر | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## تاریخچه‌ی قیمت محصول `GET /api/v1/products/{id}/price-history` > تاریخچه‌ی قیمت یک محصول با قیمت پایانی، کمترین و بیشترین در هر بازه (حداکثر ۳۶۶ روز). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `integer` | الزامی | شناسه‌ی محصول | | `interval` | query | `string` | اختیاری | 1h، 6h یا 1d (پیش‌فرض 1d) | | `from` | query | `string` | اختیاری | شروع ISO-8601 (پیش‌فرض ۳۰ روز قبل) | | `to` | query | `string` | اختیاری | پایان | ### نمونه ```bash curl "https://stard-market.ir/api/v1/products/4518/price-history?interval=1d" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/products/4518/price-history?interval=1d", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/products/4518/price-history?interval=1d", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/products/4518/price-history?interval=1d", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/products/4518/price-history?interval=1d", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "price_history", "product_id": 30364, "currency": "IRT", "interval": "1d", "from": "2026-09-02T17:43:25Z", "to": "2026-10-02T17:43:25Z", "data": [ { "timestamp": "2026-10-02T00:00:00Z", "price": 52306975, "low": 52306975, "high": 52701274 } ] } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_9omXno0Nx2IV4offX754 x-ratelimit-limit: 1000 x-ratelimit-remaining: 980 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `product_not_found` | محصول پیدا نشد | | `400` | `parameter_invalid` | interval یا بازه نامعتبر | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ساخت هشدار قیمت `POST /api/v1/price-alerts` > وقتی قیمت استارز، TON یا یک محصول از حد تعیین‌شده پایین‌تر یا بالاتر رفت، یک بار رویداد وب‌هوک `price.alert` برایت فرستاده می‌شود (بررسی هر دقیقه). حداکثر ۵۰ هشدار فعال. برای دریافت، یک [وب‌هوک](https://stard-market.ir/docs/webhooks) هم‌محیط بساز. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `asset` | `string` | الزامی | `stars`، `ton` یا `product` | | `product_id` | `integer` | اختیاری | برای asset=product | | `condition` | `string` | الزامی | `below` یا `above` | | `price` | `integer` | الزامی | قیمت هدف به تومان | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/price-alerts" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"asset": "stars", "condition": "below", "price": 4000}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/price-alerts", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "asset": "stars", "condition": "below", "price": 4000 }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/price-alerts", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "asset": "stars", "condition": "below", "price": 4000 }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/price-alerts", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "asset": "stars", "condition": "below", "price": 4000 }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "asset" => "stars", "condition" => "below", "price" => 4000 ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"asset": "stars", "condition": "below", "price": 4000}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/price-alerts", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "price_alert", "id": "pa_9SzgiaSZTsX3dqeX10BI", "environment": "test", "asset": "stars", "product_id": null, "condition": "below", "price": { "amount": 4000, "currency": "IRT" }, "status": "active", "last_value": null, "triggered_at": null, "created_at": "2026-10-02T17:43:25Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_58yHzL3zlPLzO9HFld2x x-ratelimit-limit: 1000 x-ratelimit-remaining: 979 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `product_not_found` | asset=product بدون product_id معتبر | | `400` | `limit_reached` | بیش از ۵۰ هشدار فعال | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## فهرست هشدارها `GET /api/v1/price-alerts` > هشدارهای همین محیط، با وضعیت `active`، `triggered` یا `cancelled` و آخرین قیمت دیده‌شده. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/price-alerts" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/price-alerts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/price-alerts", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/price-alerts", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/price-alerts", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "price_alert", "id": "pa_9SzgiaSZTsX3dqeX10BI", "environment": "test", "asset": "stars", "product_id": null, "condition": "below", "price": { "amount": 4000, "currency": "IRT" }, "status": "active", "last_value": null, "triggered_at": null, "created_at": "2026-10-02T17:43:25Z" } ], "has_more": false, "next_offset": null, "total": 1 } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_UYDrAyIBjU17RVAMfvsK x-ratelimit-limit: 1000 x-ratelimit-remaining: 978 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## حذف هشدار `DELETE /api/v1/price-alerts/{id}` > هشدار را غیرفعال می‌کند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | شناسه‌ی هشدار (pa_…) | ### نمونه ```bash curl -X DELETE "https://stard-market.ir/api/v1/price-alerts/pa_8Kq2Lm4Np6Rs8Tu0" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/price-alerts/pa_8Kq2Lm4Np6Rs8Tu0", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/price-alerts/pa_8Kq2Lm4Np6Rs8Tu0", { method: "DELETE", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.delete( "https://stard-market.ir/api/v1/price-alerts/pa_8Kq2Lm4Np6Rs8Tu0", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "DELETE", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("DELETE", "https://stard-market.ir/api/v1/price-alerts/pa_8Kq2Lm4Np6Rs8Tu0", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "price_alert", "id": "pa_9SzgiaSZTsX3dqeX10BI", "deleted": true } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_PdW6fv9s6J82jOIseEbg x-ratelimit-limit: 1000 x-ratelimit-remaining: 977 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `not_found` | هشدار پیدا نشد | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## شارژ موجودی TON `POST /api/v1/wallet/topups` > یک درخواست شارژ با آدرس و memo یکتا می‌سازد؛ لینک‌های `ton://` و Tonkeeper را به کاربر یا خودت بده تا از ولت خودش TON بفرستد. بعد از تأیید شبکه موجودی TON حساب شارژ می‌شود. فقط با کلید live؛ هیچ کلید خصوصی یا عبارت بازیابی گرفته نمی‌شود. برداشت پول از API عمداً وجود ندارد. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `amount_ton` | `number` | اختیاری | مبلغ پیشنهادی در لینک پرداخت (حداقل ۰٫۱) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/wallet/topups" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount_ton": 10}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/topups", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "amount_ton": 10 }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/topups", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "amount_ton": 10 }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/wallet/topups", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "amount_ton": 10 }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "amount_ton" => 10 ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"amount_ton": 10}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/wallet/topups", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "topup", "id": "XK7P2M9Q", "status": "pending", "currency": "TON", "wallet_address": "UQ…(آدرس واریز Stard)", "memo": "XK7P2M9Q", "min_amount": "0.1", "expires_at": "2026-10-02T12:30:00Z", "links": { "ton": "ton://transfer/UQ…?text=XK7P2M9Q&amount=10000000000", "tonkeeper": "https://app.tonkeeper.com/transfer/UQ…?text=XK7P2M9Q&amount=10000000000" } } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `live_only` | با کلید test | | `503` | `topup_unavailable` | واریز TON موقتاً غیرفعال است | | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت شارژ TON `GET /api/v1/wallet/topups/{id}` > وضعیت درخواست شارژ: `pending`، `succeeded` یا `expired`. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | memo درخواست شارژ | ### نمونه ```bash curl "https://stard-market.ir/api/v1/wallet/topups/XK7P2M9Q" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/topups/XK7P2M9Q", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/topups/XK7P2M9Q", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet/topups/XK7P2M9Q", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet/topups/XK7P2M9Q", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `not_found` | شارژ پیدا نشد | | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت سرویس‌ها `GET /api/v1/status` > وضعیت لحظه‌ای API، دیتابیس، ربات، تحویل خودکار استارز، واریز TON و وب‌هوک‌ها (`operational`، `degraded`، `outage`). نسخه‌ی عمومی: [صفحه‌ی وضعیت](https://stard-market.ir/status). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/status" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/status", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/status", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/status", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/status", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "status", "status": "operational", "services": { "api": "operational", "database": "operational", "cache": "operational", "bot": "operational", "stars": "operational", "ton": "operational", "notifications": "operational", "webhooks": "operational" }, "updated_at": "2026-10-02T17:43:25Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_RBBY18LYQAG0mmWDQEaH x-ratelimit-limit: 1000 x-ratelimit-remaining: 974 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## شبیه‌سازی نتیجه‌ی سفارش (test) `POST /api/v1/test/orders/{id}/simulate` > فقط با کلید `sk_test_`: نتیجه‌ی یک سفارش آزمایشی را تعیین کن تا کد و وب‌هوک‌هایت را برای همه‌ی حالت‌ها تست کنی. `failed` و `refunded` موجودی آزمایشی را برمی‌گردانند. بدون شبیه‌سازی، سفارش test بعد از ۱۵ ثانیه خودکار `completed` می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `outcome` | `string` | الزامی | `processing`، `completed`، `failed` یا `refunded` | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/test/orders/ord_test_gGToQWxqOw89ssiL/simulate" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"outcome": "failed"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/test/orders/ord_test_gGToQWxqOw89ssiL/simulate", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "outcome": "failed" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/test/orders/ord_test_gGToQWxqOw89ssiL/simulate", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "outcome": "failed" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/test/orders/ord_test_gGToQWxqOw89ssiL/simulate", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "outcome": "failed" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "outcome" => "failed" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"outcome": "failed"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/test/orders/ord_test_gGToQWxqOw89ssiL/simulate", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_etbvDNYC7E4k8vEP", "order_id": null, "environment": "test", "status": "failed", "raw_status": "failed", "title": "⭐ 50 استارز برای @username (test)", "product_id": null, "product_tag": null, "type": "stars", "quantity": 50, "recipient": "@username", "amount": { "amount": 224900, "currency": "IRT" }, "paid": { "amount": 224900, "currency": "IRT" }, "failure_reason": "simulated", "metadata": {}, "created_at": "2026-10-02T17:43:25Z", "updated_at": "2026-10-02T17:43:25Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_FkPUX928OypWAvZNCRFd x-ratelimit-limit: 1000 x-ratelimit-remaining: 975 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `test_only` | با کلید live | | `409` | `order_final` | سفارش در وضعیت نهایی است | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## فهرست خدمات کانال `GET /api/v1/services` > همه‌ی خدمات رشد کانال و گروه تلگرام که از API قابل سفارش‌اند، با نوع ورودی (`post`، `channel` یا `bot`)، واحد، حداقل/حداکثر تعداد، چند قیمت نمونه و قابلیت‌های هر خدمت در `features`: `reaction_picker`، `custom_comments`، `guarantee_options`، `post_count_options` و `drip_feed`.`reactions` ری‌اکشن پست (با انتخاب دقیق ایموجی) · `views` بازدید پست · `premium_views` بازدید پریمیوم`auto_views` بازدید خودکار پست‌های بعدی · `last_views` بازدید چند پست آخر`members` ممبر · `premium_members` ممبر پریمیوم (هر دو با سطح ضمانت)`bot_start` استارت ربات · `story_views` بازدید استوری · `poll_votes` رأی نظرسنجی`share` فوروارد · `future_share` فوروارد خودکار پست‌های بعدی`comments` کامنت · `custom_comments` کامنت با متن دلخواه · `future_comments` کامنت خودکار پست‌های بعدی ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "enabled": true, "data": [ { "object": "service", "id": "views", "name": "بازدید پست", "emoji": "👁", "input": "post", "input_example": "https://t.me/channel/123", "unit": "بازدید", "min_quantity": 1, "max_quantity": 100000000, "from_price": 9000, "currency": "IRT", "price_samples": [ { "quantity": 100, "amount": 9000, "unit_price": 90 }, { "quantity": 500, "amount": 11000, "unit_price": 22 }, { "quantity": 1000, "amount": 22000, "unit_price": 22 }, { "quantity": 5000, "amount": 110000, "unit_price": 22 } ], "guarantee_days": null, "features": { "reaction_picker": false, "custom_comments": false, "guarantee_options": false, "post_count_options": false, "drip_feed": true, "auto_refund_undelivered": true } }, { "object": "service", "id": "auto_views", "name": "بازدید خودکار پست‌های بعدی", "emoji": "🔮", "input": "channel", "input_example": "@channel", "unit": "بازدید هر پست", "min_quantity": 1, "max_quantity": 10000000, "from_price": 20000, "currency": "IRT", "price_samples": [ { "quantity": 100, "amount": 20000, "unit_price": 200 }, { "quantity": 500, "amount": 20000, "unit_price": 40 }, { "quantity": 1000, "amount": 40000, "unit_price": 40 }, { "quantity": 5000, "amount": 199000, "unit_price": 40 } ], "guarantee_days": null, "features": { "reaction_picker": false, "custom_comments": false, "guarantee_options": false, "post_count_options": true, "drip_feed": false, "auto_refund_undelivered": true } }, { "object": "service", "id": "last_views", "name": "بازدید پست‌های آخر", "emoji": "🗂", "input": "channel", "input_example": "@channel", "unit": "بازدید هر پست", "min_quantity": 1, "max_quantity": 100000000, "from_price": 20000, "currency": "IRT", "price_samples": [ { "quantity": 100, "amount": 20000, "unit_price": 200 }, { "quantity": 500, "amount": 20000, "unit_price": 40 }, { "quantity": 1000, "amount": 30000, "unit_price": 30 }, { "quantity": 5000, "amount": 149000, "unit_price": 30 } ], "guarantee_days": null, "features": { "reaction_picker": false, "custom_comments": false, "guarantee_options": false, "post_count_options": true, "drip_feed": false, "auto_refund_undelivered": true } } ], "total": 15 } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_7KzsoYUYlMTq8KL25ErV x-ratelimit-limit: 1000 x-ratelimit-remaining: 999 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک خدمت `GET /api/v1/services/{service}` > جزئیات یک خدمت با همان قالب فهرست. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `service` | path | `string` | الزامی | شناسه‌ی خدمت از `GET /services` (مثل `reactions`، `members`، `views`) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/members" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/members", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/members", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/members", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/members", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "service", "id": "members", "name": "ممبر کانال و گروه", "emoji": "👥", "input": "channel", "input_example": "@channel", "unit": "ممبر", "min_quantity": 1, "max_quantity": 1000000, "from_price": 15000, "currency": "IRT", "price_samples": [ { "quantity": 100, "amount": 15000, "unit_price": 150 }, { "quantity": 500, "amount": 35000, "unit_price": 70 }, { "quantity": 1000, "amount": 69000, "unit_price": 69 }, { "quantity": 5000, "amount": 341000, "unit_price": 68 } ], "guarantee_days": 30, "features": { "reaction_picker": false, "custom_comments": false, "guarantee_options": true, "post_count_options": false, "drip_feed": true, "auto_refund_undelivered": true } } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_vtHbIS2rHn4EWW5h0DlZ x-ratelimit-limit: 1000 x-ratelimit-remaining: 998 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `service_not_found` | این خدمت وجود ندارد یا غیرفعال است | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ری‌اکشن‌های قابل سفارش `GET /api/v1/services/reactions/options` > همه‌ی ری‌اکشن‌هایی که می‌شود دقیقاً همان‌ها را روی پست فرستاد: تکی (`kind=single`، مثل 👍 یا ❤️) و ترکیبی (`kind=mix`) با مبلغ همان تعداد. `id` هر ردیف را به‌صورت `reaction` به قیمت و سفارش بده. `auto_amount` قیمت حالت خودکار (ارزان‌ترین سرویس سالم) است. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `quantity` | query | `integer` | اختیاری | تعداد برای محاسبه‌ی قیمت (پیش‌فرض ۱۰۰) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/reactions/options?quantity=100" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/reactions/options?quantity=100", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/reactions/options?quantity=100", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/reactions/options?quantity=100", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/reactions/options?quantity=100", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "quantity": 100, "currency": "IRT", "auto_amount": 12000, "data": [ { "id": "e:👍", "kind": "single", "emojis": [ "👍" ], "amount": 12000, "unit_price": 120 }, { "id": "e:👎", "kind": "single", "emojis": [ "👎" ], "amount": 12000, "unit_price": 120 }, { "id": "e:❤", "kind": "single", "emojis": [ "❤" ], "amount": 12000, "unit_price": 120 }, { "id": "e:👌", "kind": "single", "emojis": [ "👌" ], "amount": 12000, "unit_price": 120 }, { "id": "e:😍", "kind": "single", "emojis": [ "😍" ], "amount": 12000, "unit_price": 120 }, { "id": "e:🐳", "kind": "single", "emojis": [ "🐳" ], "amount": 12000, "unit_price": 120 } ] } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_W06elD3aXD88Ik2bdjim x-ratelimit-limit: 1000 x-ratelimit-remaining: 997 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## گزینه‌های خدمت `GET /api/v1/services/{service}/options` > برای ممبر و ممبر پریمیوم **سطح ضمانت** (`kind=guarantee`: ۷، ۳۰، ۹۰ روزه یا مادام‌العمر) و برای خدمات چندپستی **تعداد پست** (`kind=post_count`: مثلاً ۱۰ پست آخر یا ۵۰ پست بعدی) با مبلغ همان تعداد. `id` را به‌صورت `option` بفرست. در خدمات چندپستی تعداد سفارش «به ازای هر پست» است. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `service` | path | `string` | الزامی | شناسه‌ی خدمت از `GET /services` (مثل `reactions`، `members`، `views`) | | `quantity` | query | `integer` | الزامی | تعداد | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/members/options?quantity=1000" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/members/options?quantity=1000", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/members/options?quantity=1000", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/members/options?quantity=1000", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/members/options?quantity=1000", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "service": "members", "quantity": 1000, "kind": "guarantee", "currency": "IRT", "data": [ { "id": "g30", "label": "ضمانت ۳۰ روزه+", "amount": 69000, "guarantee_days": 30 }, { "id": "g90", "label": "ضمانت ۹۰ روزه+", "amount": 133000, "guarantee_days": 90 } ] } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_yduU4E0N6ZEh1glzgD8l x-ratelimit-limit: 1000 x-ratelimit-remaining: 996 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `service_not_found` | خدمت پیدا نشد | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت دقیق خدمت `GET /api/v1/services/{service}/price` > همان مبلغی که `POST /services/orders` با همین پارامترها کسر می‌کند. با `drip_runs` قیمت ارسال تدریجی را می‌گیری (سرویس باید هر مرحله را بپذیرد). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `service` | path | `string` | الزامی | شناسه‌ی خدمت از `GET /services` (مثل `reactions`، `members`، `views`) | | `quantity` | query | `integer` | الزامی | تعداد کل | | `reaction` | query | `string` | اختیاری | فقط reactions: از `GET /services/reactions/options` | | `option` | query | `string` | اختیاری | سطح ضمانت یا تعداد پست از `/options` | | `drip_runs` | query | `integer` | اختیاری | ارسال تدریجی: تعداد مرحله (۲ تا ۲۰) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/reactions/price?quantity=500&reaction=e%3A%F0%9F%91%8D" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/reactions/price?quantity=500&reaction=e%3A%F0%9F%91%8D", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/reactions/price?quantity=500&reaction=e%3A%F0%9F%91%8D", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/reactions/price?quantity=500&reaction=e%3A%F0%9F%91%8D", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/reactions/price?quantity=500&reaction=e%3A%F0%9F%91%8D", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "service_price", "service": "reactions", "quantity": 500, "amount": 16000, "unit_price": 32, "currency": "IRT", "reaction": "e:👍", "option": null, "drip_runs": null, "guarantee_days": null } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_3zcsZkV0XzcX9jDEw4bV x-ratelimit-limit: 1000 x-ratelimit-remaining: 994 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `409` | `unavailable` | برای این تعداد/گزینه سرویسی موجود نیست | | `400` | `drip_unsupported` | ارسال تدریجی برای این خدمت فعال نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## اطلاعات و ری‌اکشن‌های پست `POST /api/v1/services/post-info` > عنوان کانال، متن، بازدید و **ری‌اکشن‌های فعلی پست** (ایموجی، استارزی و سفارشی) به‌همراه ری‌اکشن‌های مجاز کانال (`allowed`؛ `null` یعنی محدودیتی نیست). اگر `status=pending` بود، ۱ تا ۳ ثانیه بعد همان درخواست را تکرار کن. نتیجه ۱۰ دقیقه کش می‌شود؛ `fresh=true` کش را دور می‌زند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `link` | `string` | الزامی | لینک پست: https://t.me/channel/123 | | `fresh` | `boolean` | اختیاری | نادیده گرفتن کش | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/services/post-info" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"link": "https://t.me/your_channel/42"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/post-info", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "link": "https://t.me/your_channel/42" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/post-info", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "link": "https://t.me/your_channel/42" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/services/post-info", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "link": "https://t.me/your_channel/42" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "link" => "https://t.me/your_channel/42" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"link": "https://t.me/your_channel/42"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/services/post-info", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "post_info", "link": "https://t.me/your_channel/42", "allowed": [ "❤", "👍", "🔥", "🎉", "custom" ], "status": "done", "title": "Your Channel", "text": "متن پست…", "views": 12840, "reactions": [ { "emoji": "👍", "count": 412 }, { "emoji": "❤", "count": 190 }, { "paid": true, "count": 25 }, { "custom_id": "5413794461152978282", "count": 12 } ], "paid_enabled": true } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `invalid_request` | لینک پست معتبر نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ثبت سفارش خدمت کانال `POST /api/v1/services/orders` > سفارش هر خدمت کانال را ثبت کن. تحویل خودکار است و پیشرفتش در `progress` برمی‌گردد؛ هر مقداری که تحویل نشود خودکار به کیف پول برمی‌گردد. قابلیت‌ها: `reaction` برای ری‌اکشن دقیق، `option` برای ضمانت یا تعداد پست، `comments` برای کامنت دلخواه (تعداد = تعداد کامنت‌ها)، و `drip_runs` + `drip_interval` برای **ارسال تدریجی** (مثلاً ۵۰۰۰ بازدید در ۵ مرحله با فاصله‌ی ۶۰ دقیقه). از `Idempotency-Key` پشتیبانی می‌کند و تغییر وضعیت با وب‌هوک `order.*` خبر داده می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا برای جلوگیری از سفارش تکراری | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `service` | `string` | الزامی | شناسه‌ی خدمت | | `target` | `string` | الزامی | لینک پست، @کانال یا @ربات | | `quantity` | `integer` | اختیاری | تعداد (برای custom_comments لازم نیست) | | `reaction` | `string` | اختیاری | فقط reactions | | `option` | `string` | اختیاری | ضمانت یا تعداد پست | | `comments` | `array` | اختیاری | فقط custom_comments: فهرست متن کامنت‌ها | | `drip_runs` | `integer` | اختیاری | ارسال تدریجی: ۲ تا ۲۰ مرحله | | `drip_interval` | `integer` | اختیاری | فاصله‌ی مرحله‌ها به دقیقه (۱۰ تا ۱۴۴۰) | | `max_price` | `integer` | اختیاری | سقف مبلغ؛ بیشتر شد → 409 price_changed | | `pay_currency` | `string` | اختیاری | TON یا IRT | | `metadata` | `object` | اختیاری | داده‌ی دلخواه | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/services/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: svc-3001" \ -d '{"service": "reactions", "target": "https://t.me/your_channel/42", "quantity": 500, "reaction": "e:👍", "metadata": {"invoice": "INV-3001"}}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "svc-3001", }, body: JSON.stringify({ "service": "reactions", "target": "https://t.me/your_channel/42", "quantity": 500, "reaction": "e:👍", "metadata": { "invoice": "INV-3001" } }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "svc-3001", }, body: JSON.stringify({ "service": "reactions", "target": "https://t.me/your_channel/42", "quantity": 500, "reaction": "e:👍", "metadata": { "invoice": "INV-3001" } }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/services/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "svc-3001", }, json={ "service": "reactions", "target": "https://t.me/your_channel/42", "quantity": 500, "reaction": "e:👍", "metadata": { "invoice": "INV-3001" } }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: svc-3001", ], CURLOPT_POSTFIELDS => json_encode([ "service" => "reactions", "target" => "https://t.me/your_channel/42", "quantity" => 500, "reaction" => "e:👍", "metadata" => [ "invoice" => "INV-3001" ] ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"service": "reactions", "target": "https://t.me/your_channel/42", "quantity": 500, "reaction": "e:👍", "metadata": {"invoice": "INV-3001"}}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/services/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "svc-3001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "order", "id": "ord_test_0yLba24ESVLgQzyS", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "ری‌اکشن پست × 500 (test)", "product_id": null, "product_tag": null, "type": "service", "quantity": 500, "recipient": "https://t.me/your_channel/42", "amount": { "amount": 16000, "currency": "IRT" }, "paid": { "amount": 16000, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-3001" }, "created_at": "2026-10-11T11:15:48Z", "updated_at": "2026-10-11T11:15:48Z", "service": "reactions" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_8g0bKYfaoVVkr04WKVOg x-ratelimit-limit: 1000 x-ratelimit-remaining: 991 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `service_not_found` | خدمت پیدا نشد | | `400` | `invalid_request` | ورودی برای این خدمت معتبر نیست | | `400` | `drip_unsupported` | ارسال تدریجی برای این خدمت فعال نیست | | `409` | `price_changed` | مبلغ از max_price بیشتر شد؛ پولی کسر نشده | | `409` | `unavailable` | برای این تعداد/گزینه سرویسی موجود نیست | | `402` | `insufficient_funds` | موجودی کیف پول API (یا موجودی آزمایشی) کافی نیست | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت سفارش خدمت `GET /api/v1/services/orders/{id}` > وضعیت سفارش به‌همراه `progress`: تعداد تحویل‌شده و باقی‌مانده، و برای ارسال تدریجی `drip.completed_runs`، `drip.per_run` و `drip.next_run_at`. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "order", "id": "ord_test_0yLba24ESVLgQzyS", "order_id": null, "environment": "test", "status": "pending", "raw_status": "pending", "title": "ری‌اکشن پست × 500 (test)", "product_id": null, "product_tag": null, "type": "service", "quantity": 500, "recipient": "https://t.me/your_channel/42", "amount": { "amount": 16000, "currency": "IRT" }, "paid": { "amount": 16000, "currency": "IRT" }, "failure_reason": null, "metadata": { "invoice": "INV-3001" }, "created_at": "2026-10-11T11:15:48Z", "updated_at": "2026-10-11T11:15:48Z" } ``` **هدرهای پاسخ** ```http content-type: application/json x-request-id: req_x5DhBp8D4RzXSVYar8R3 x-ratelimit-limit: 1000 x-ratelimit-remaining: 988 ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `order_not_found` | سفارش پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت ری‌اکشن استارزی `GET /api/v1/star-reactions/quote` > قیمت ری‌اکشن پولی (⭐) روی پست کانال. `posts` یعنی همین پست و پست‌های بعدی کانال (هر پست همان تعداد استارز)؛ `anonymous=true` ری‌اکشن را بدون نام می‌فرستد (به‌ازای هر استارز هزینه‌ی اضافه). `amount` همان مبلغی است که هنگام سفارش کسر می‌شود (با سود API تنظیم‌شده). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `stars` | query | `integer` | الزامی | استارز برای هر پست | | `posts` | query | `integer` | اختیاری | تعداد پست (۱ تا ۵۰) | | `anonymous` | query | `boolean` | اختیاری | ناشناس | ### نمونه ```bash curl "https://stard-market.ir/api/v1/star-reactions/quote?stars=50&posts=3" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/star-reactions/quote?stars=50&posts=3", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/star-reactions/quote?stars=50&posts=3", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/star-reactions/quote?stars=50&posts=3", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/star-reactions/quote?stars=50&posts=3", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `503` | `price_unavailable` | قیمت لحظه‌ای استارز در دسترس نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## بررسی پست برای ری‌اکشن استارزی `GET /api/v1/star-reactions/check` > قبل از سفارش بپرس پست پیدا می‌شود و ری‌اکشن استارزی در کانال فعال است (`can_order`). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `url` | query | `string` | الزامی | لینک پست | ### نمونه ```bash curl "https://stard-market.ir/api/v1/star-reactions/check?url=https%3A%2F%2Ft.me%2Fyour_channel%2F42" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/star-reactions/check?url=https%3A%2F%2Ft.me%2Fyour_channel%2F42", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/star-reactions/check?url=https%3A%2F%2Ft.me%2Fyour_channel%2F42", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/star-reactions/check?url=https%3A%2F%2Ft.me%2Fyour_channel%2F42", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/star-reactions/check?url=https%3A%2F%2Ft.me%2Fyour_channel%2F42", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ثبت سفارش ری‌اکشن استارزی `POST /api/v1/star-reactions/orders` > ری‌اکشن استارزی روی یک یا چند پست متوالی، با امکان ناشناس و زمان‌بندی. از `Idempotency-Key` پشتیبانی می‌کند و تغییر وضعیت با وب‌هوک `order.*` خبر داده می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا برای جلوگیری از سفارش تکراری | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `post_url` | `string` | الزامی | لینک پست | | `stars` | `integer` | الزامی | استارز برای هر پست | | `posts` | `integer` | اختیاری | تعداد پست (۱ تا ۵۰) | | `anonymous` | `boolean` | اختیاری | ناشناس | | `scheduled_at` | `string` | اختیاری | زمان ارسال (ISO 8601) | | `max_price` | `integer` | اختیاری | سقف مبلغ؛ بیشتر شد → 409 price_changed | | `pay_currency` | `string` | اختیاری | TON یا IRT | | `metadata` | `object` | اختیاری | داده‌ی دلخواه | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/star-reactions/orders" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: rx-1001" \ -d '{"post_url": "https://t.me/your_channel/42", "stars": 50, "posts": 3, "anonymous": true}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/star-reactions/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "rx-1001", }, body: JSON.stringify({ "post_url": "https://t.me/your_channel/42", "stars": 50, "posts": 3, "anonymous": true }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/star-reactions/orders", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "rx-1001", }, body: JSON.stringify({ "post_url": "https://t.me/your_channel/42", "stars": 50, "posts": 3, "anonymous": true }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/star-reactions/orders", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "rx-1001", }, json={ "post_url": "https://t.me/your_channel/42", "stars": 50, "posts": 3, "anonymous": True }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: rx-1001", ], CURLOPT_POSTFIELDS => json_encode([ "post_url" => "https://t.me/your_channel/42", "stars" => 50, "posts" => 3, "anonymous" => true ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"post_url": "https://t.me/your_channel/42", "stars": 50, "posts": 3, "anonymous": true}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/star-reactions/orders", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "rx-1001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `post_url_invalid` | لینک پست نامعتبر است | | `400` | `quantity_out_of_range` | تعداد استارز خارج از بازه | | `403` | `service_disabled` | ری‌اکشن استارزی موقتاً غیرفعال است | | `409` | `price_changed` | مبلغ از max_price بیشتر شد؛ پولی کسر نشده | | `402` | `insufficient_funds` | موجودی کیف پول API (یا موجودی آزمایشی) کافی نیست | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت سفارش ری‌اکشن استارزی `GET /api/v1/star-reactions/orders/{id}` > وضعیت سفارش ری‌اکشن استارزی. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/star-reactions/orders/ord_test_gGToQWxqOw89ssiL" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/star-reactions/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/star-reactions/orders/ord_test_gGToQWxqOw89ssiL", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/star-reactions/orders/ord_test_gGToQWxqOw89ssiL", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/star-reactions/orders/ord_test_gGToQWxqOw89ssiL", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `order_not_found` | سفارش پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ممبر با ادمین کردن ربات `POST /api/v1/services/members/invite` > به‌جای فرستادن لینک، ربات Stard را در کانال/گروه ادمین کن (با مجوز «دعوت کاربران»): پاسخ `add_bot_url` و `token` می‌دهد. بعد از ادمین شدن، ربات یک لینک دعوت اختصاصی می‌سازد و سفارش ممبر خودکار با همان لینک ثبت می‌شود (هزینه همان لحظه کسر می‌شود). ورود و خروج اعضا از همین لینک شمرده می‌شود. سفارش به حساب API تو لینک می‌شود و وب‌هوک `order.created` می‌آید. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `service` | `string` | اختیاری | `members` (پیش‌فرض) یا `premium_members` | | `kind` | `string` | الزامی | `channel` یا `group` | | `quantity` | `integer` | الزامی | تعداد ممبر | | `option` | `string` | اختیاری | سطح ضمانت | | `drip_runs` | `integer` | اختیاری | ارسال تدریجی | | `drip_interval` | `integer` | اختیاری | فاصله به دقیقه | | `max_price` | `integer` | اختیاری | سقف مبلغ | | `pay_currency` | `string` | اختیاری | TON یا IRT | | `metadata` | `object` | اختیاری | داده‌ی دلخواه | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/services/members/invite" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: mem-1001" \ -d '{"kind": "channel", "quantity": 1000, "option": "g30"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/members/invite", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "mem-1001", }, body: JSON.stringify({ "kind": "channel", "quantity": 1000, "option": "g30" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/members/invite", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "mem-1001", }, body: JSON.stringify({ "kind": "channel", "quantity": 1000, "option": "g30" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/services/members/invite", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "mem-1001", }, json={ "kind": "channel", "quantity": 1000, "option": "g30" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: mem-1001", ], CURLOPT_POSTFIELDS => json_encode([ "kind" => "channel", "quantity" => 1000, "option" => "g30" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"kind": "channel", "quantity": 1000, "option": "g30"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/services/members/invite", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "mem-1001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "member_invite", "environment": "test", "token": "mbr_test_k3Jd9QaZx1Lm", "status": "pending", "add_bot_url": "https://t.me/Stard_marketbot?startchannel=mem_test&admin=invite_users", "kind": "channel", "quantity": 1000, "amount": null, "expires_in": 3600, "order": null, "note": "در محیط test ربات ادمین نمی‌شود؛ برای آزمون سفارش ممبر از POST /services/orders استفاده کن." } ``` **هدرهای پاسخ** ```http content-type: application/json ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** وقتی صاحب کانال یا گروه نمی‌خواهد لینک دعوت بسازد و بفرستد. روند کامل: 1. این اندپوینت را صدا بزن؛ پاسخ `add_bot_url` (لینک ادمین کردن ربات Stard با مجوز «دعوت کاربران») و `token` می‌دهد. 2. `add_bot_url` را به صاحب کانال بده؛ با باز کردنش ربات را در کانال یا گروه ادمین می‌کند. درخواست تا `expires_in` ثانیه معتبر است. 3. بعد از ادمین شدن، ربات لینک دعوت اختصاصی می‌سازد و سفارش ممبر با همان لینک خودکار ثبت و هزینه کسر می‌شود. 4. وضعیت را با [`GET /services/members/invite/{token}`](https://stard-market.ir/docs/reference/members-invite-get) بگیر: `pending` → `done` همراه شیء `order`. - ورود و خروج اعضا فقط از همین لینک اختصاصی شمرده می‌شود ([آمار اعضا](https://stard-market.ir/docs/reference/service-order-members)). - در محیط test ربات ادمین نمی‌شود و پاسخ فقط شکل خروجی را نشان می‌دهد؛ برای آزمون کامل سفارش ممبر از [`POST /services/orders`](https://stard-market.ir/docs/reference/service-order) استفاده کن. - با `max_price` سقف مبلغ بگذار تا اگر قیمت بین نمایش و ثبت بالا رفت، سفارشی با مبلغ بیشتر ثبت نشود. ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `invalid_request` | سطح ضمانت/تنظیم تدریجی نامعتبر | | `409` | `unavailable` | برای این تعداد سرویسی موجود نیست | | `402` | `insufficient_funds` | موجودی کیف پول API (یا موجودی آزمایشی) کافی نیست | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## وضعیت ممبر با ربات `GET /api/v1/services/members/invite/{token}` > `pending` تا وقتی ربات ادمین نشده؛ بعد `done` با `order` (همراه `order.members`: joined/left/net) یا `failed` با `error`. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `token` | path | `string` | الزامی | توکن از پاسخ invite | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/members/invite/AbC123" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/members/invite/AbC123", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/members/invite/AbC123", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/members/invite/AbC123", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/members/invite/AbC123", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "member_invite", "environment": "test", "token": "AbC123", "status": "pending", "order": null } ``` **هدرهای پاسخ** ```http content-type: application/json ``` ### کاربرد و نکته‌ها **کی به کار می‌آید؟** بعد از [`POST /services/members/invite`](https://stard-market.ir/docs/reference/members-invite)، برای اینکه بفهمی صاحب کانال ربات را ادمین کرده یا نه و سفارش ممبر ثبت شده است. `pending` یعنی هنوز ادمین نشده؛ `done` همراه شیء `order` و آمار `order.members` (عضوشده، خارج‌شده، خالص)؛ `failed` همراه `error`. - فقط درخواست‌هایی که با کلید همان حساب API ساخته شده‌اند قابل خواندن‌اند؛ بقیه `404 not_found` می‌دهند. - `chat_title` نام کانال یا گروهی است که ربات در آن ادمین شد؛ برای تأیید اینکه ربات در کانال درست ادمین شده آن را نشان بده. ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `not_found` | درخواست پیدا نشد | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## آمار اعضای سفارش ممبر `GET /api/v1/services/orders/{id}/members` > تعداد عضوشده، خارج‌شده و خالص از لینک دعوت اختصاصیِ سفارش ممبر (فقط سفارش‌های «ممبر با ربات»). ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش (ord_… یا کد live) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL/members" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL/members", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL/members", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL/members", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/services/orders/ord_test_gGToQWxqOw89ssiL/members", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `not_a_member_invite_order` | این سفارش با لینک دعوت ربات ثبت نشده | | `403` | `insufficient_scope` | کلید scope `orders:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## نرخ TON `GET /api/v1/ton/rate` > نرخ لحظه‌ای TON به تومان (همان نرخ پرداخت با کیف پول TON) و دلار. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/ton/rate" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ton/rate", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ton/rate", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ton/rate", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ton/rate", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `503` | `price_unavailable` | نرخ در دسترس نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پیش‌نمایش تبدیل تومان ↔ TON `GET /api/v1/wallet/convert/quote` > نرخ لحظه‌ای، کارمزد، حداقل مبلغ، موجودی دو کیف پول و مبلغ دقیق دریافتی برای `amount`. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `direction` | query | `string` | الزامی | `toman_to_ton` یا `ton_to_toman` | | `amount` | query | `string` | اختیاری | تومان صحیح یا TON اعشاری | ### نمونه ```bash curl "https://stard-market.ir/api/v1/wallet/convert/quote?direction=toman_to_ton&amount=500000" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/convert/quote?direction=toman_to_ton&amount=500000", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/convert/quote?direction=toman_to_ton&amount=500000", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet/convert/quote?direction=toman_to_ton&amount=500000", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet/convert/quote?direction=toman_to_ton&amount=500000", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## تبدیل تومان ↔ TON `POST /api/v1/wallet/convert` > کسر از یک کیف پول و واریز به دیگری در یک تراکنش. scope ِ `wallet:write` پیش‌فرض نیست و باید هنگام ساخت کلید انتخاب شود. `min_receive` محافظ لغزش نرخ است. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | الزامی | الزامی؛ تکرار همان کلید همان نتیجه را برمی‌گرداند | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `direction` | `string` | الزامی | toman_to_ton \| ton_to_toman | | `amount` | `string` | الزامی | مبلغ | | `min_receive` | `string` | اختیاری | حداقل مبلغ دریافتی | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/wallet/convert" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: cv-1001" \ -d '{"direction": "toman_to_ton", "amount": "500000"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/convert", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "cv-1001", }, body: JSON.stringify({ "direction": "toman_to_ton", "amount": "500000" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/convert", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "cv-1001", }, body: JSON.stringify({ "direction": "toman_to_ton", "amount": "500000" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/wallet/convert", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "cv-1001", }, json={ "direction": "toman_to_ton", "amount": "500000" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: cv-1001", ], CURLOPT_POSTFIELDS => json_encode([ "direction" => "toman_to_ton", "amount" => "500000" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"direction": "toman_to_ton", "amount": "500000"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/wallet/convert", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "cv-1001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `live_only` | فقط با کلید live | | `400` | `parameter_missing` | Idempotency-Key لازم است | | `402` | `insufficient_funds` | موجودی کافی نیست | | `409` | `unavailable` | نرخ بدتر از min_receive شد | | `403` | `insufficient_scope` | کلید scope `wallet:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پیش‌نمایش برداشت TON `GET /api/v1/wallet/ton/withdrawals/quote` > مبلغ دقیقی که به کیف پول TON می‌رسد، با کارمزد شبکه و (برای source=toman) نرخ تبدیل. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `source` | query | `string` | الزامی | ton یا toman | | `amount` | query | `string` | الزامی | مبلغ | ### نمونه ```bash curl "https://stard-market.ir/api/v1/wallet/ton/withdrawals/quote?source=ton&amount=2.5" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals/quote?source=ton&amount=2.5", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals/quote?source=ton&amount=2.5", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet/ton/withdrawals/quote?source=ton&amount=2.5", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet/ton/withdrawals/quote?source=ton&amount=2.5", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## برداشت TON `POST /api/v1/wallet/ton/withdrawals` > برداشت TON فقط به کیف پولی که مالک حساب با TON Connect در مینی‌اپ وصل کرده (آدرس دلخواه پذیرفته نمی‌شود تا کلید لو‌رفته نتواند پول را جای دیگری بفرستد). برداشت‌های غیرعادی به صف بررسی می‌روند. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `source` | `string` | الزامی | ton یا toman | | `amount` | `string` | الزامی | مبلغ | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/wallet/ton/withdrawals" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"source": "ton", "amount": "2.5"}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "source": "ton", "amount": "2.5" }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "source": "ton", "amount": "2.5" }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/wallet/ton/withdrawals", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "source": "ton", "amount": "2.5" }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "source" => "ton", "amount" => "2.5" ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"source": "ton", "amount": "2.5"}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/wallet/ton/withdrawals", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `ton_wallet_not_linked` | کیف پول TON وصل نیست | | `400` | `live_only` | فقط با کلید live | | `403` | `insufficient_scope` | کلید scope `wallet:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## برداشت‌های TON `GET /api/v1/wallet/ton/withdrawals` > آخرین برداشت‌ها با وضعیت و لینک تراکنش. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/wallet/ton/withdrawals" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/wallet/ton/withdrawals", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/wallet/ton/withdrawals", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/wallet/ton/withdrawals", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## قیمت فروش TON (کیف به کیف / کیف پول تلگرام) `GET /api/v1/ton/sell/quote` > مبلغی که از کیف پول حساب کسر می‌شود تا گیرنده **دقیقاً** `amount_ton` بگیرد. قیمت هر تون = نرخ لحظه‌ای TON + کارمزد هر تون استارد؛ کارمزد شبکه را استارد می‌پردازد. برای هر دو مقصد (آدرس و یوزرنیم) یکی است. سقف هر ارسال و سقف ۲۴ ساعته هم در پاسخ می‌آید. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `amount_ton` | query | `string` | الزامی | مقداری که گیرنده می‌گیرد؛ حداقل `0.1` | | `source` | query | `string` | اختیاری | `toman` (پیش‌فرض، از کیف تومانی) یا `ton` (از موجودی TON) | ### نمونه ```bash curl "https://stard-market.ir/api/v1/ton/sell/quote?amount_ton=1.5&source=toman" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ton/sell/quote?amount_ton=1.5&source=toman", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ton/sell/quote?amount_ton=1.5&source=toman", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ton/sell/quote?amount_ton=1.5&source=toman", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ton/sell/quote?amount_ton=1.5&source=toman", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "ton_sell_quote", "receive_ton": "1.5", "source": "toman", "pay": { "amount": 645000, "currency": "IRT" }, "ton_rate_toman": 400000, "price_per_ton_toman": 430000, "network_fee": "paid by Stard", "min_ton": "0.1", "environment": "live", "limits": { "max_per_request_ton": "20", "max_per_24h_ton": "50" } } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_invalid` | مقدار کمتر از 0.1 یا نامعتبر | | `503` | `unavailable` | نرخ لحظه‌ای TON در دسترس نیست | | `403` | `insufficient_scope` | کلید scope `prices:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## فروش و ارسال TON `POST /api/v1/ton/sell` > کسر از کیف پول حساب و ارسال TON. `destination=address`: به **هر آدرس TON**، کاملاً خودکار از کیف پول استارد (معمولاً زیر یک دقیقه)؛ موارد غیرعادی `status=review` می‌گیرند و بعد از بررسی ارسال یا کامل برگشت داده می‌شوند.`destination=telegram_username`: به **کیف پول تلگرامِ** یک یوزرنیم؛ پشتیبانی ارسال می‌کند (`pending` → `done`؛ رد = برگشت کامل).امنیت: scope ِ `ton:send` پیش‌فرض **نیست** و باید هنگام ساخت کلید انتخاب شود؛ سقف هر ارسال و سقف ۲۴ ساعته‌ی هر حساب اعمال می‌شود؛ `Idempotency-Key` الزامی است و تکرار آن دوباره پول نمی‌فرستد؛ `max_pay` جلوی کسر بیشتر از انتظار را می‌گیرد. با کلید test فقط شبیه‌سازی می‌شود. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `Idempotency-Key` | header | `string` | الزامی | الزامی؛ تکرار همان کلید همان نتیجه را برمی‌گرداند | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `destination` | `string` | الزامی | `address` یا `telegram_username` | | `amount_ton` | `string` | الزامی | مقداری که گیرنده دقیقاً می‌گیرد (حداقل 0.1) | | `source` | `string` | اختیاری | `toman` (پیش‌فرض) یا `ton` | | `address` | `string` | اختیاری | برای destination=address: آدرس TON (UQ… / EQ… / raw) | | `username` | `string` | اختیاری | برای destination=telegram_username: یوزرنیم گیرنده (با یا بدون @) | | `max_pay` | `integer` | اختیاری | محافظ لغزش نرخ: حداکثر تومان قابل کسر (فقط source=toman) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/ton/sell" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ts-1001" \ -d '{"destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton": "2", "source": "toman", "max_pay": 900000}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ton/sell", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "ts-1001", }, body: JSON.stringify({ "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton": "2", "source": "toman", "max_pay": 900000 }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ton/sell", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "ts-1001", }, body: JSON.stringify({ "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton": "2", "source": "toman", "max_pay": 900000 }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/ton/sell", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", "Idempotency-Key": "ts-1001", }, json={ "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton": "2", "source": "toman", "max_pay": 900000 }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", "Idempotency-Key: ts-1001", ], CURLOPT_POSTFIELDS => json_encode([ "destination" => "address", "address" => "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton" => "2", "source" => "toman", "max_pay" => 900000 ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "amount_ton": "2", "source": "toman", "max_pay": 900000}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/ton/sell", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "ts-1001") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 201** ```json { "object": "ton_sell", "id": 24, "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "receive_ton": "2", "status": "queued", "status_fa": "در صف ارسال", "tracking_code": "9U7KXQ2M", "review_reason": null, "pay": { "amount": 860000, "currency": "IRT" }, "ton_rate_toman": 400000, "price_per_ton_toman": 430000 } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `parameter_missing` | Idempotency-Key یا address/username لازم است | | `400` | `parameter_invalid` | آدرس TON یا مقدار نامعتبر | | `400` | `amount_too_large` | بیشتر از سقف هر ارسال | | `400` | `send_failed` | موجودی کافی نیست یا ارسال ممکن نیست | | `403` | `insufficient_scope` | کلید scope ِ ton:send ندارد | | `409` | `price_changed` | قیمت از max_pay بیشتر شد؛ چیزی کسر نشد | | `429` | `daily_limit` | سقف ۲۴ ساعته پر شده | | `403` | `insufficient_scope` | کلید scope `ton:send` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## ارسال‌های TON `GET /api/v1/ton/sell` > آخرین ارسال‌ها (آدرس و یوزرنیم) با وضعیت، کد پیگیری، `tx_hash` و لینک tonviewer. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | ### نمونه ```bash curl "https://stard-market.ir/api/v1/ton/sell" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ton/sell", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ton/sell", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ton/sell", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ton/sell", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "list", "data": [ { "object": "ton_sell", "id": 24, "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "username": null, "source": "toman", "receive_ton": "2", "status": "done", "status_fa": "ارسال شد", "tracking_code": "9U7KXQ2M", "tx_hash": "b1f0…e9", "explorer_url": "https://tonviewer.com/transaction/b1f0…e9", "created_at": "2026-11-18T09:12:44" } ], "has_more": false } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## یک ارسال TON `GET /api/v1/ton/sell/{sell_id}` > وضعیت یک ارسال با شناسه‌ای که `POST /ton/sell` برگردانده. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `sell_id` | path | `integer` | الزامی | شناسه‌ی ارسال | ### نمونه ```bash curl "https://stard-market.ir/api/v1/ton/sell/{sell_id}" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/ton/sell/{sell_id}", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/ton/sell/{sell_id}", { method: "GET", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.get( "https://stard-market.ir/api/v1/ton/sell/{sell_id}", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/ton/sell/{sell_id}", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` **پاسخ — 200** ```json { "object": "ton_sell", "id": 24, "destination": "address", "address": "UQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "username": null, "source": "toman", "receive_ton": "2", "status": "done", "status_fa": "ارسال شد", "tracking_code": "9U7KXQ2M", "tx_hash": "b1f0…e9", "explorer_url": "https://tonviewer.com/transaction/b1f0…e9", "created_at": "2026-11-18T09:12:44" } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `not_found` | ارسال پیدا نشد | | `403` | `insufficient_scope` | کلید scope `wallet:read` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پیشنهاد روی مزایده یا آگهی توافقی `POST /api/v1/auctions/{product_id}/bids` > پیشنهاد قیمت روی آگهی P2P (مزایده یا توافقی). اگر فروشنده بپذیرد یا مزایده را ببری، خرید با امانت ادامه می‌یابد. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `product_id` | path | `integer` | الزامی | شناسه‌ی محصول از GET /auctions | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `amount` | `integer` | الزامی | مبلغ پیشنهاد (تومان) | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/auctions/23115/bids" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount": 1500000}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/auctions/23115/bids", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "amount": 1500000 }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/auctions/23115/bids", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "amount": 1500000 }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/auctions/23115/bids", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "amount": 1500000 }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "amount" => 1500000 ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"amount": 1500000}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/auctions/23115/bids", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `404` | `auction_not_found` | مزایده/آگهی پیدا نشد | | `400` | `invalid_request` | پیشنهاد کمتر از حداقل | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## خرید P2P: پرداخت و شروع امانت `POST /api/v1/orders/{id}/finalize` > خرید آگهی P2P با `POST /orders` شروع می‌شود (`raw_status=pending_availability`). وقتی فروشنده موجود بودن را تایید کرد (`ready_to_finalize`، وب‌هوک `order.*`) این endpoint مبلغ را کسر و در امانت نگه می‌دارد. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/finalize" \ -H "Authorization: Bearer $STARD_API_KEY" ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/finalize", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/finalize", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, }, }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/finalize", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), ], CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" ) func main() { req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/finalize", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `invalid_request` | سفارش در مرحله‌ی نهایی‌سازی نیست | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## خرید P2P: تایید یا رد دریافت `POST /api/v1/orders/{id}/receipt` > `received=true` پول را به فروشنده آزاد می‌کند؛ `false` سفارش را برای بررسی پشتیبانی نگه می‌دارد. ### درخواست | نام | محل | نوع | | توضیح | |---|---|---|---|---| | `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` | | `id` | path | `string` | الزامی | کد پیگیری سفارش | #### بدنه (JSON) | فیلد | نوع | | توضیح | |---|---|---|---| | `received` | `boolean` | الزامی | دریافت کردم / نکردم | ### نمونه ```bash curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/receipt" \ -H "Authorization: Bearer $STARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"received": true}' ``` ```javascript const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/receipt", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "received": true }), }); const data = await res.json(); if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`); console.log(data); ``` ```typescript type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } }; const res = await fetch("https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/receipt", { method: "POST", headers: { Authorization: `Bearer ${process.env.STARD_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "received": true }), }); if (!res.ok) { const { error } = (await res.json()) as StardError; throw new Error(`${error.code}: ${error.message} (${error.request_id})`); } const data: Record = await res.json(); ``` ```python import os import requests r = requests.post( "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/receipt", headers={ "Authorization": f"Bearer {os.environ['STARD_API_KEY']}", }, json={ "received": True }, timeout=20, ) data = r.json() if r.status_code >= 400: raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}") print(data) ``` ```php true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("STARD_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "received" => true ]), CURLOPT_TIMEOUT => 20, ]); $data = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($status >= 400) { throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]); } print_r($data); ``` ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { body := strings.NewReader(`{"received": true}`) req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/receipt", body) req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() b, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(b)) } ``` ### خطاها | HTTP | code | کی | |---|---|---| | `400` | `not_p2p_order` | این سفارش P2P نیست | | `403` | `insufficient_scope` | کلید scope `orders:write` را ندارد | | `401` | `invalid_api_key / missing_api_key / api_key_revoked / api_key_expired` | کلید نیامده، نامعتبر، باطل یا منقضی است | | `429` | `rate_limit_exceeded` | سقف درخواست در دقیقه پر شده؛ بعد از `Retry-After` ثانیه دوباره بفرست | ### محدودیت نرخ پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits). --- ## پرسش‌های رایج درباره‌ی Stard API > پاسخ کوتاه و دقیق به پرسش‌های رایج درباره‌ی API، هزینه، احراز هویت و خرید استارز. ### پاسخ‌ها اگر پاسخ پرسشت اینجا نیست، در [کانال Stard](https://t.me/Stard_market) بپرس. ### پرسش‌های رایج **Stard API چیست؟** API رسمی Stard Market که با آن برنامه‌ها می‌توانند قیمت استارز و محصولات تلگرام را بخوانند و سفارش واقعی ثبت کنند. **آیا Stard API برای خرید استارز تلگرام دارد؟** بله. `POST /api/v1/orders` با `type=stars`؛ [راهنما](https://stard-market.ir/docs/products/stars). **چطور کلید API بسازم؟** در [داشبورد](https://stard-market.ir/developers/dashboard) وارد شو و از بخش کلیدها یک کلید test یا live بساز. **احراز هویت چطور است؟** هدر `Authorization: Bearer sk_live_…`؛ کلید هرگز در URL نیاید. **استفاده از API چقدر هزینه دارد؟** خود API رایگان است؛ فقط مبلغ سفارش‌ها با همان قیمت فروشگاه از کیف پول کسر می‌شود. **محیط تست دارد؟** بله؛ کلیدهای `sk_test_` با ۱۰۰ میلیون تومان موجودی آزمایشی و بدون پول واقعی کار می‌کنند. **وب‌هوک دارد؟** بله. از داشبورد توسعه‌دهنده یک آدرس https ثبت کن و رویدادهای order.created، order.processing، order.completed، order.cancelled، order.refunded و order.failed را با امضای HMAC-SHA256 دریافت کن؛ تحویل ناموفق تا ۸ بار با فاصله‌ی افزایشی دوباره فرستاده می‌شود. جزئیات و نمونه‌ی بررسی امضا در /docs/webhooks. **چه چیزهایی را می‌شود با API خرید؟** همه‌ی چیزهایی که ربات و مینی‌اپ می‌فروشند: استارز، پریمیوم، گیفت استارزی (با فرستنده‌ی مخفی، پیام با ایموجی پریمیوم و زمان‌بندی)، محصولات فروشگاه، بوست، همه‌ی خدمات کانال (ممبر — حتی با ادمین کردن ربات و آمار ورود/خروج — بازدید، ری‌اکشن، کامنت، ارسال تدریجی…) و ری‌اکشن استارزی؛ همه در live و test. **پیام خطا انگلیسی هم دارد؟** بله؛ هر خطا code ماشینی، message فارسی و message_en انگلیسی دارد. **سقف درخواست چقدر است؟** پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید؛ هدرهای X-RateLimit وضعیت را می‌گویند. --- ## تغییرات API > تاریخچه‌ی نسخه‌ها و تغییرات Stard API: endpointهای تازه، تغییرات رفتار و سیاست نسخه‌بندی و سازگاری. ### ۱۱ اکتبر ۲۰۲۶ — خدمات کانال - بخش تازه‌ی [خدمات کانال](https://stard-market.ir/docs/reference/services): ری‌اکشن (با انتخاب دقیق ایموجی)، بازدید، بازدید خودکار پست‌های بعدی و چند پست آخر، ممبر و ممبر پریمیوم با ضمانت، استارت ربات، کامنت و کامنت دلخواه، فوروارد، بازدید استوری و رأی نظرسنجی. - `POST /services/post-info`: ری‌اکشن‌ها و بازدید فعلی پست و ری‌اکشن‌های مجاز کانال. - ارسال تدریجی با `drip_runs` و `drip_interval`؛ پیشرفت مرحله‌ها در `progress.drip`. ### ۱ اکتبر ۲۰۲۶ — v1 - انتشار نخست `/api/v1`: محصولات، قیمت‌ها، استارز، پریمیوم، مزایده، سفارش، کیف پول. - محیط test با موجودی آزمایشی، Idempotency-Key، خطاهای ساختاریافته، هدرهای محدودیت نرخ، OpenAPI. - داشبورد توسعه‌دهندگان: ورود با تلگرام/گوگل، پروژه‌ها، کلیدها، لاگ‌ها، آمار مصرف. سیاست نسخه‌بندی: تغییر ناسازگار فقط در نسخه‌ی تازه (`/api/v2`)؛ فیلدهای تازه بدون اعلام قبلی اضافه می‌شوند، پس کد تو باید فیلدهای ناشناخته را نادیده بگیرد.