شارژ موجودی TON
POST
/api/v1/wallet/topupsscope: wallet:readاحراز هویت: Bearerlive و test
یک درخواست شارژ با آدرس و memo یکتا میسازد؛ لینکهای ton:// و Tonkeeper را به کاربر یا خودت بده تا از ولت خودش TON بفرستد. بعد از تأیید شبکه موجودی TON حساب شارژ میشود. فقط با کلید live؛ هیچ کلید خصوصی یا عبارت بازیابی گرفته نمیشود. برداشت پول از API عمداً وجود ندارد.
درخواست
| نام | محل | نوع | توضیح | |
|---|---|---|---|---|
Authorization | header | string | الزامی | Bearer sk_live_… یا Bearer sk_test_… |
بدنه (JSON)
| فیلد | نوع | توضیح | |
|---|---|---|---|
amount_ton | number | اختیاری | مبلغ پیشنهادی در لینک پرداخت (حداقل ۰٫۱) |
نمونه
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}'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);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<string, unknown> = await res.json();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
$ch = curl_init("https://stard-market.ir/api/v1/wallet/topups");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => 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);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
{
"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-* برمیگردد — جزئیات.
