---
title: شارژ موجودی TON — POST /api/v1/wallet/topups | Stard API
url: https://stard-market.ir/docs/reference/wallet-topup
markdown: https://stard-market.ir/docs/reference/wallet-topup.md
language: fa
updated: 2026-11-18
description: یک درخواست شارژ با آدرس و memo یکتا می‌سازد؛ لینک‌های ton:// و Tonkeeper را به کاربر یا خودت بده تا از ولت خودش TON بفرستد. بعد از تأیید شبکه موجودی TON حس
---

# شارژ موجودی 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<string, unknown> = 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
<?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);
```

```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).
