StardDevelopersداشبورد

شارژ موجودی TON

POST/api/v1/wallet/topups
scope: wallet:readاحراز هویت: Bearerlive و test

یک درخواست شارژ با آدرس و memo یکتا می‌سازد؛ لینک‌های ton:// و Tonkeeper را به کاربر یا خودت بده تا از ولت خودش TON بفرستد. بعد از تأیید شبکه موجودی TON حساب شارژ می‌شود. فقط با کلید live؛ هیچ کلید خصوصی یا عبارت بازیابی گرفته نمی‌شود. برداشت پول از API عمداً وجود ندارد.

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…

بدنه (JSON)

فیلدنوعتوضیح
amount_tonnumberاختیاریمبلغ پیشنهادی در لینک پرداخت (حداقل ۰٫۱)

نمونه

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

خطاها

HTTPcodeکی
400live_onlyبا کلید test
503topup_unavailableواریز TON موقتاً غیرفعال است
403insufficient_scopeکلید scope wallet:read را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

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