StardDevelopersداشبورد

فروش و ارسال TON

POST/api/v1/ton/sell
scope: ton:sendاحراز هویت: Bearerlive و test

کسر از کیف پول حساب و ارسال TON.

  • destination=address: به هر آدرس TON، کاملاً خودکار از کیف پول استارد (معمولاً زیر یک دقیقه)؛ موارد غیرعادی status=review می‌گیرند و بعد از بررسی ارسال یا کامل برگشت داده می‌شوند.
  • destination=telegram_username: به کیف پول تلگرامِ یک یوزرنیم؛ پشتیبانی ارسال می‌کند (pending → done؛ رد = برگشت کامل).
امنیت: scope ِ ton:send پیش‌فرض نیست و باید هنگام ساخت کلید انتخاب شود؛ سقف هر ارسال و سقف ۲۴ ساعته‌ی هر حساب اعمال می‌شود؛ Idempotency-Key الزامی است و تکرار آن دوباره پول نمی‌فرستد؛ max_pay جلوی کسر بیشتر از انتظار را می‌گیرد. با کلید test فقط شبیه‌سازی می‌شود.

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…
Idempotency-Keyheaderstringالزامیالزامی؛ تکرار همان کلید همان نتیجه را برمی‌گرداند

بدنه (JSON)

فیلدنوعتوضیح
destinationstringالزامیaddress یا telegram_username
amount_tonstringالزامیمقداری که گیرنده دقیقاً می‌گیرد (حداقل 0.1)
sourcestringاختیاریtoman (پیش‌فرض) یا ton
addressstringاختیاریبرای destination=address: آدرس TON (UQ… / EQ… / raw)
usernamestringاختیاریبرای destination=telegram_username: یوزرنیم گیرنده (با یا بدون @)
max_payintegerاختیاریمحافظ لغزش نرخ: حداکثر تومان قابل کسر (فقط source=toman)

نمونه

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}'
پاسخ — 201
{
  "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
}

خطاها

HTTPcodeکی
400parameter_missingIdempotency-Key یا address/username لازم است
400parameter_invalidآدرس TON یا مقدار نامعتبر
400amount_too_largeبیشتر از سقف هر ارسال
400send_failedموجودی کافی نیست یا ارسال ممکن نیست
403insufficient_scopeکلید scope ِ ton:send ندارد
409price_changedقیمت از max_pay بیشتر شد؛ چیزی کسر نشد
429daily_limitسقف ۲۴ ساعته پر شده
403insufficient_scopeکلید scope ton:send را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای X-RateLimit-* برمی‌گردد — جزئیات.