# Nạp tiền bằng crypto

> API LocalSERP Proxy: nạp tiền bằng tiền mã hóa, số tiền chính xác, xác nhận đã gửi thanh toán (TXID không bắt buộc) và trạng thái. Tham số, phản hồi mẫu, mã curl, Python và Node.js.

- URL: https://localserpproxy.com/vi/docs/api/top-ups/
- Cập nhật lần cuối: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Nạp tiền bằng crypto: lấy địa chỉ nạp và số tiền chính xác, gửi đúng số tiền đó, báo đã gửi khoản thanh toán (không bắt buộc cung cấp ID giao dịch), sau đó theo dõi khoản nạp cho đến khi tiền được cộng vào số dư. Số dư dùng để thanh toán cho mọi gói dịch vụ của chúng tôi.

**Các điểm cuối trên trang này**

- `GET /v1/catalog/coins`: Các loại tiền mã hóa và mạng được chấp nhận (kèm địa chỉ nạp cố định)
- `POST /v1/topups`: Bắt đầu nạp tiền mã hóa vào số dư (địa chỉ cố định, số tiền chính xác)
- `POST /v1/topups/{topUpId}/txid`: Báo đã gửi thanh toán (TXID không bắt buộc)
- `GET /v1/topups/{topUpId}`: Lấy thông tin giao dịch nạp tiền (kiểm tra trạng thái hiện tại)
- `GET /v1/topups`: Liệt kê các giao dịch nạp tiền bằng tiền mã hóa

URL cơ sở `https://localserpproxy.com/api/v1`. Xem [tổng quan API](https://localserpproxy.com/vi/docs/api/)] để biết về xác thực, lỗi và giới hạn.

## Các loại tiền mã hóa và mạng được chấp nhận (kèm địa chỉ nạp cố định)

`GET /v1/catalog/coins`

Công khai: không cần khóa API.

**Phản hồi** `200 OK`

```json
{
  "data": [
    {
      "code": "BTC",
      "name": "Bitcoin",
      "networks": [
        {
          "id": "bitcoin",
          "name": "Bitcoin",
          "confirmationsRequired": 2,
          "estimatedMinutes": null,
          "memoRequired": false,
          "address": "DEPOSIT_ADDRESS"
        }
      ]
    }
  ]
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/catalog/coins"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"

r = requests.get(f"{API}/catalog/coins", timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/catalog/coins`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Bắt đầu nạp tiền mã hóa vào số dư (địa chỉ cố định, số tiền chính xác)

`POST /v1/topups`

- `amountUsd` ≥ 25.00 USD và ≤ mức tối đa (mặc định là 10,000.00): `422` trên `amountUsd` nếu không thì.
- `coin` + `network` phải là một trong các giá trị `GET /v1/catalog/coins` (nếu không thì `409 coin_unavailable`).
- Trả về `address` **cố định** của mạng và `amountCrypto` chính xác = `amountUsd` / `rate`, làm tròn **lên** theo độ chính xác của đồng tiền (BTC/LTC/ETH/SOL 8 chữ số thập phân, USDT/USDC 6), cộng thêm một khoản chênh lệch nhỏ, duy nhất ở các chữ số cuối để không có 2 lần nạp đang mở trên cùng mạng yêu cầu cùng một số tiền. `rate` được khóa đến `expiresAt` (30 phút); `txidDeadline` = `expiresAt` + 72 h.
- `purchase` không bắt buộc (cùng nội dung với `POST /v1/orders`): được xác thực và tính giá ngay (`422` với tên trường có tiền tố `purchase.`, `409 plan_unavailable`…). `amountUsd` phải đủ để thanh toán `purchase` tổng − số dư hiện tại (`422 too_small` trên `amountUsd`). Khi tiền nạp được ghi có, đơn hàng sẽ được tạo từ số dư trong cùng một giao dịch; `purchase.status` trở thành `completed` (kèm `orderId`) hoặc `failed` (`failureReason`; tiền vẫn nằm trong số dư).

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất (ví dụ UUID) để thử lại POST an toàn. Được lưu trong 24 h. — tối đa 128 ký tự |

**Nội dung yêu cầu**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `amountUsd` | string (USD, 2 decimals) | Có | Số USD cần nạp: ≥ 25.00, ≤ 10,000.00 theo mặc định. |
| `coin` | string | Có | — |
| `network` | string | Có | — |
| `purchase` | object | Không | Dự định mua bằng số dư sau khi tiền nạp được ghi có (cùng nội dung với `POST /v1/orders`). |

*Ví dụ: Số dư*

```json
{
  "amountUsd": "50.00",
  "coin": "USDT",
  "network": "tron"
}
```

*Ví dụ: Thanh toán*

```json
{
  "amountUsd": "25.00",
  "coin": "BTC",
  "network": "bitcoin",
  "purchase": {
    "planId": "res-10",
    "quantity": 1
  }
}
```

**Phản hồi** `201 Created`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://localserpproxy.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amountUsd":"50.00","coin":"USDT","network":"tron"}'
```

*Python*

```python
import os, uuid
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/topups", headers=HEADERS, json={"amountUsd": "50.00", "coin": "USDT", "network": "tron"}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ amountUsd: '50.00', coin: 'USDT', network: 'tron' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Báo đã gửi thanh toán (TXID không bắt buộc)

`POST /v1/topups/{topUpId}/txid`

Báo đã gửi thanh toán sau khi tiền đã rời khỏi ví hoặc sàn giao dịch của bạn: đây là phiên bản API của nút “Tôi đã gửi thanh toán”. Mã giao dịch (TXID) không bắt buộc: gửi nội dung trống (`{}`), hoặc thêm `txid` nếu có. Khoản thanh toán được đối chiếu với lần nạp này theo số tiền chính xác (`amountCrypto`) trên mạng lưới và địa chỉ của lần nạp, vì vậy hãy gửi đúng số tiền đó.

Có thể báo khi lần nạp ở trạng thái `awaiting_payment`, `expired` hoặc `rejected`, và trước `txidDeadline` (`expiresAt` + 72 h): báo muộn không làm mất khoản thanh toán. `txid`, nếu được cung cấp, sẽ được kiểm tra theo định dạng của mạng lưới (`422` trên `txid`) và không được dùng cho lần nạp khác (`409 txid_already_used`). Lần nạp đã đóng sẽ trả về `409 topup_closed`. Sau đó, lần nạp chuyển sang trạng thái `verifying` trong khi khoản thanh toán được kiểm tra trên blockchain, và kết thúc ở trạng thái `credited` khi mạng lưới xác nhận giao dịch, hoặc `rejected` (kèm `rejection`).

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `topUpId` | path | string | Có | — |

**Nội dung yêu cầu**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `txid` | string | Không | Không bắt buộc. Mã giao dịch: 64 ký tự hex (bitcoin, litecoin, tron), 0x + 64 ký tự hex (ethereum), chữ ký base58 (solana). Để trống hoặc không cung cấp: khoản thanh toán được đối chiếu theo số tiền chính xác. — tối đa 128 ký tự |

*Ví dụ: Đã gửi thanh toán*

```json
{}
```

*Ví dụ: Kèm TXID (không bắt buộc)*

```json
{
  "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
}
```

**Phản hồi** `200 OK`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://localserpproxy.com/api/v1/topups/top_7d2kq9x1/txid" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.post(f"{API}/topups/top_7d2kq9x1/txid", headers=HEADERS, json={}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1/txid`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Nạp tiền (kiểm tra trạng thái trực tiếp)

`GET /v1/topups/{topUpId}`

Gọi tuyến này để theo dõi khoản nạp: cứ 10 giây khi `status = verifying`, cứ 30 giây trong khi chờ thanh toán và dừng khi `final = true`. Khoản nạp chuyển sang trạng thái `expired` nếu chưa báo đã gửi thanh toán trước `expiresAt`; bạn vẫn có thể báo đã gửi thanh toán cho đến `txidDeadline`.

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `topUpId` | path | string | Có | — |

**Phản hồi** `200 OK`

```json
{
  "id": "top_7d2kq9x1",
  "status": "verifying",
  "final": false,
  "amountUsd": "25.00",
  "coin": "USDT",
  "network": "tron",
  "address": "DEPOSIT_ADDRESS",
  "amountCrypto": "25.000137",
  "rate": "1.00",
  "paymentUri": "PAYMENT_URI",
  "expiresAt": "2026-10-05T14:33:11Z",
  "txidDeadline": "2026-10-08T14:33:11Z",
  "confirmationsRequired": 20,
  "confirmations": 7,
  "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "txidSubmittedAt": "2026-10-05T14:09:42Z",
  "amountReceivedCrypto": "25.000137",
  "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
  "creditedUsd": null,
  "creditedAt": null,
  "rejection": null,
  "purchase": {
    "planId": "res-10",
    "planName": "Local team",
    "quantity": 1,
    "options": {},
    "promoCode": null,
    "total": "7.50",
    "status": "pending",
    "orderId": null,
    "failureReason": null
  },
  "createdAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/topups/top_7d2kq9x1" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups/top_7d2kq9x1", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups/top_7d2kq9x1`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Liệt kê các khoản nạp bằng tiền mã hóa

`GET /v1/topups`

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `page` | query | integer | Không | ≥ 1, mặc định `1` |
| `perPage` | query | integer | Không | 1–100, mặc định `20` |
| `status` | query | `awaiting_payment` · `verifying` · `credited` · `rejected` · `expired` | Không | `final` = đã ghi có, hoặc hết hạn / bị từ chối sau `txidDeadline`. |

**Phản hồi** `200 OK`

```json
{
  "data": [
    {
      "id": "top_7d2kq9x1",
      "status": "verifying",
      "final": false,
      "amountUsd": "25.00",
      "coin": "USDT",
      "network": "tron",
      "address": "DEPOSIT_ADDRESS",
      "amountCrypto": "25.000137",
      "rate": "1.00",
      "paymentUri": "PAYMENT_URI",
      "expiresAt": "2026-10-05T14:33:11Z",
      "txidDeadline": "2026-10-08T14:33:11Z",
      "confirmationsRequired": 20,
      "confirmations": 7,
      "txid": "9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "txidSubmittedAt": "2026-10-05T14:09:42Z",
      "amountReceivedCrypto": "25.000137",
      "explorerUrl": "https://tronscan.org/#/transaction/9d2e5c0b1f7a4e3d8c6b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f41c7",
      "creditedUsd": null,
      "creditedAt": null,
      "rejection": null,
      "purchase": {
        "planId": "res-10",
        "planName": "Local team",
        "quantity": 1,
        "options": {},
        "promoCode": null,
        "total": "7.50",
        "status": "pending",
        "orderId": null,
        "failureReason": null
      },
      "createdAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/topups" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/topups", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/topups`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

---

LocalSERP Proxy: LocalSERP Proxy là dịch vụ proxy dân cư tại Hoa Kỳ để kiểm tra kết quả tìm kiếm địa phương, quảng cáo và giá theo từng thành phố, thanh toán bằng tiền mã hóa và không cần tải lên giấy tờ tùy thân.