POST /apiv2/bandwidth

Thuê Bandwidth TRON và ủy quyền cho một địa chỉ người nhận trong một khoảng thời gian cố định: 5 phút, hoặc 1 giờ đối với tài khoản được công nhận.

⚠️ Các cấp truy cập.
Tài khoản được công nhận thuê bất kỳ số lượng nào (lên đến 5000) trong 5 phút hoặc 1 giờ trong giới hạn pool và giới hạn tối đa, với nhiều đơn hàng đồng thời. Việc công nhận được cấp bởi hỗ trợ Netts.
Không có công nhận bạn có thể thuê 400 đơn vị trong 5 phút, một lần — đơn hàng tiếp theo chỉ được phép sau khi lượt thuê trước đó kết thúc. Yêu cầu cho các số lượng khác 400, thuê 1 giờ, hoặc đơn hàng thứ hai trong khi đơn hàng đầu tiên vẫn đang hoạt động, sẽ bị từ chối.

URL của Endpoint

POST https://netts.io/apiv2/bandwidth

Headers của yêu cầu

Header	Bắt buộc	Mô tả
Content-Type	Có	application/json
X-API-KEY	Có	Khóa API của bạn từ bảng điều khiển Netts
X-Real-IP	Có	Địa chỉ IP từ danh sách trắng của bạn
X-Idempotency-Key	Không	Khóa tùy chọn do máy khách tạo (base64) để thử lại một cách an toàn mà không bị trùng lặp đơn hàng. Nếu bỏ qua, máy chủ sẽ tự động tạo một khóa

Body của yêu cầu

json

{
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m"
}

Tham số yêu cầu

Tham số	Loại	Bắt buộc	Mô tả
amount	integer	Có	Đơn vị Bandwidth cần thuê (tối thiểu: 400, tối đa: 5000)
receiveAddress	string	Có	Địa chỉ TRON sẽ nhận Bandwidth (`T…`, 34 ký tự, base58)
period	string	Có	Thời gian thuê: `"5m"` (5 phút) hoặc `"1h"` (1 giờ, chỉ dành cho tài khoản được công nhận)
trx_send	boolean	Không	Giao dịch được đảm bảo: nếu không có sẵn Bandwidth, thay vào đó sẽ gửi TRX đến địa chỉ để giao dịch vẫn được thực hiện thành công. Chỉ hoạt động khi `amount = 400` (bị bỏ qua trong trường hợp khác). Mặc định là `false`
check	boolean	Không	Nếu là `true` và người nhận đã có hơn 400 Bandwidth, đơn hàng sẽ không được ủy quyền và không bị tính phí (trạng thái `enough`). Mặc định là `false`
test	boolean	Không	Chạy thử. Nếu là `true`, toàn bộ quy trình đặt hàng sẽ được mô phỏng — phản hồi cho bạn biết kết quả sẽ diễn ra và mức giá sẽ bị tính phí — mà không có bất kỳ hành động on-chain nào và không bị trừ tiền. Mặc định là `false`

Ví dụ

Các ví dụ bên dưới cũng tạo và gửi X-Idempotency-Key để việc lặp lại vô tình không tạo ra đơn hàng thứ hai. Xem Tính lũy đẳng để biết toàn bộ quy tắc.

cURL

bash

API_KEY="your_api_key"
ADDR="TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AMOUNT=1500
PERIOD="5m"
NONCE=$(( $(date +%s) / 2 ))   # stable for retries within a 2s window; or your own order UUID

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
IDEMP=$(printf '%s' "${ADDR}:${AMOUNT}:${PERIOD}:${NONCE}" \
  | openssl dgst -sha256 -hmac "$API_KEY" -binary | base64)

curl -X POST https://netts.io/apiv2/bandwidth \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -H "X-Idempotency-Key: $IDEMP" \
  -d "{\"amount\": $AMOUNT, \"receiveAddress\": \"$ADDR\", \"period\": \"$PERIOD\"}"

Python

python

import time, hmac, hashlib, base64, requests

API_KEY = "your_api_key"
url = "https://netts.io/apiv2/bandwidth"
payload = {
    "amount": 1500,
    "receiveAddress": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "period": "5m",
}

# X-Idempotency-Key = base64( HMAC-SHA256( API_KEY, "addr:amount:period:nonce" ) )
# Generate ONCE per order and resend the same value on every retry.
nonce = str(int(time.time() // 2))   # 2s bucket; or your own order UUID
message = f"{payload['receiveAddress']}:{payload['amount']}:{payload['period']}:{nonce}"
idem_key = base64.b64encode(
    hmac.new(API_KEY.encode(), message.encode(), hashlib.sha256).digest()
).decode()

headers = {
    "Content-Type": "application/json",
    "X-API-KEY": API_KEY,
    "X-Real-IP": "your_whitelisted_ip",
    "X-Idempotency-Key": idem_key,
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
detail = data.get("detail", {})

if response.status_code == 200 and detail.get("status") == "completed":
    d = detail["data"]
    print(f"Order ID: {d['orderId']}")
    print(f"Hashes:   {d['hash']}")          # array of delegation tx hashes
    print(f"Bandwidth: {d['bandwidth']} for {d['period']}")
    print(f"Cost:     {d['paidTRX']} TRX")
else:
    print(f"Code: {detail.get('code')} | {detail.get('msg', detail)}")

Ví dụ máy khách đầy đủ (Python + cURL) được cung cấp cùng với gói dịch vụ (handler_bandwidth/doc/client_example/).

Phản hồi

Thành công — Bandwidth đã được ủy quyền (200 OK)

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "bandwidth",
            "hash": ["a1b2c3...", "d4e5f6..."],
            "bandwidth": 1500,
            "period": "5m"
        }
    }
}

Thành công — TRX được gửi thay vì Bandwidth (200 OK, chỉ khi `amount=400` + `trx_send=true`)

Khi pool không còn Bandwidth và trx_send được bật, TRX sẽ được gửi đến địa chỉ để giao dịch vẫn được thực hiện thành công. Một khoản phí cố định sẽ được áp dụng trong trường hợp này, bất kể thời gian thuê được yêu cầu.

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful (sent TRX, bandwidth unavailable)",
        "data": {
            "orderId": "B5M<key14>",
            "paidTRX": "<amount charged in TRX>",
            "fulfilledBy": "trx",
            "trxSendHash": ["<txid>"],
            "hash": [],
            "bandwidth": 400,
            "period": "5m"
        }
    }
}

Đã có đủ — không bị tính phí (200 OK, chỉ khi `check=true`)

json

{
    "detail": {
        "code": 10002,
        "status": "enough",
        "msg": "enough band for 1 transfer",
        "data": { "orderId": "B5M<key14>", "paidTRX": 0, "bandwidth": 400, "period": "5m" }
    }
}

Đang xử lý — nhà cung cấp bên ngoài (202 Accepted)

Được trả về khi đơn hàng được chuyển giao bất đồng bộ cho nhà cung cấp bên ngoài. Thăm dò status endpoint (bên dưới) bằng orderId cho đến khi hoàn tất.

json

{
    "detail": {
        "code": 10001,
        "status": "processing",
        "msg": "Order accepted, processed by an external provider. Poll the status endpoint.",
        "data": { "orderId": "B5M<key14>", "bandwidth": 1500, "period": "5m" }
    }
}

Lượt chạy thử (200 OK, chỉ khi `test=true`)

Toàn bộ quy trình đơn hàng được mô phỏng. testAction cho bạn biết điều gì sẽ xảy ra và wouldCostTRX cho biết mức phí sẽ bị tính. Không có gì được ủy quyền, không có TRX nào được gửi, không bị tính phí (paidTRX: 0).

json

{
    "detail": {
        "code": 10003,
        "status": "test",
        "msg": "Test run — no on-chain action, no charge",
        "data": {
            "orderId": "B5M<...>",
            "testAction": "would_delegate",
            "wouldCostTRX": "<amount that would be charged in TRX>",
            "paidTRX": 0,
            "bandwidth": 400,
            "period": "5m",
            "receiverFreeBandwidth": 600
        }
    }
}

Các giá trị testAction: would_delegate (Bandwidth sẽ được ủy quyền), would_trx_send (không có Bandwidth, amount=400 + trx_send → TRX sẽ được gửi), enough (người nhận đã có đủ, với check=true), hoặc would_error:<reason> (ví dụ: no_bandwidth, not_whitelisted).

Các trường phản hồi

Trường	Loại	Mô tả
detail.code	integer	`10000` đã ủy quyền/TRX, `10002` đã đủ, `10001` đang xử lý
detail.status	string	`completed` / `enough` / `processing` / `failed`
detail.data.orderId	string	ID đơn hàng, định dạng `B5M…` (5m) / `B1H…` (1h) — sử dụng cho status endpoint
detail.data.paidTRX	number	Số tiền bị tính bằng TRX (`0` khi `enough`)
detail.data.fulfilledBy	string	`bandwidth` (đã ủy quyền) / `trx` (đã gửi TRX)
detail.data.hash	array	Các hash giao dịch ủy quyền (tối đa 10). Luôn là một mảng (rỗng đối với nhánh TRX)
detail.data.trxSendHash	array	(Các) hash chuyển TRX, chỉ xuất hiện khi `fulfilledBy = trx`
detail.data.bandwidth	integer	Đơn vị Bandwidth đã ủy quyền
detail.data.period	string	Thời hạn thuê (`5m` / `1h`)

Endpoint trạng thái

GET https://netts.io/apiv2/bandwidth/status/{orderId}

Headers: X-API-KEY + X-Real-IP (đơn hàng phải thuộc về người dùng đã xác thực).

Trạng thái đơn hàng	HTTP	code	status
Đã hoàn tất	200	10000	`completed` (kèm theo `hash` / `trxSendHash`)
Đang tiến hành	200	10001	`processing`
Đã có đủ	200	10002	`enough`
Thất bại	200	5003	`failed`
Không tìm thấy / không thuộc về bạn	404	-1	—

Thu hồi Endpoint

Tự nguyện thu hồi (hủy ủy quyền) Bandwidth của một trong các đơn hàng đã ủy quyền của bạn trước khi thời hạn của nó hết hạn. Bandwidth sẽ được hủy ủy quyền tự động và hash giao dịch sẽ được trả về.

POST https://netts.io/apiv2/bandwidth/reclaim/{orderId}

Headers: X-API-KEY + X-Real-IP (đơn hàng phải thuộc về người dùng đã xác thực).

Trạng thái đơn hàng	HTTP	code	status	Kết quả
Đã ủy quyền → thu hồi ngay bây giờ	200	10004	`reclaimed`	`reclaimHash` (các hash tx hủy ủy quyền)
Đã thu hồi	200	10004	`reclaimed`	`reclaimHash` + thông báo "already reclaimed"
Không ở trạng thái được ủy quyền (không có gì để thu hồi)	400	5005	`failed`	—
Việc thu hồi chưa hoàn tất	503	5003	`failed`	thử lại sau chốc lát
Không tìm thấy / không thuộc về bạn	404	-1	—	—

bash

curl -X POST https://netts.io/apiv2/bandwidth/reclaim/B5M<...> \
  -H "X-API-KEY: your_api_key" -H "X-Real-IP: your_whitelisted_ip"

json

{
    "detail": {
        "code": 10004,
        "status": "reclaimed",
        "msg": "Bandwidth reclaimed",
        "data": { "orderId": "B5M<...>", "reclaimHash": ["<txid>"] }
    }
}

python

import requests

order_id = "B5M..."   # the orderId from your rental response
url = f"https://netts.io/apiv2/bandwidth/reclaim/{order_id}"
headers = {"X-API-KEY": "your_api_key", "X-Real-IP": "your_whitelisted_ip"}

resp = requests.post(url, headers=headers)
detail = resp.json()["detail"]

if resp.status_code == 200 and detail["status"] == "reclaimed":
    print(f"Reclaimed: {detail['data']['reclaimHash']} ({detail['msg']})")
else:
    print(f"Code {detail.get('code')}: {detail.get('msg', detail)}")

Phí thuê không được hoàn lại khi chủ động thu hồi sớm — việc thu hồi chỉ trả lại Bandwidth đã ủy quyền về pool trước thời hạn.

Phản hồi lỗi

Lỗi xác thực (401)

json

{ "detail": { "code": -1, "msg": "Invalid API key or IP not in whitelist" } }

Không đủ số dư (403)

json

{ "detail": { "code": 1004, "status": "failed", "msg": "Insufficient funds" } }

Lỗi xác thực dữ liệu (400)

json

{ "detail": { "code": 5004, "status": "failed", "msg": "Bandwidth amount out of range (400..5000)" } }

Ủy quyền thất bại / Dịch vụ không khả dụng (503)

json

{ "detail": { "code": 5003, "status": "failed", "msg": "Bandwidth delegation failed" } }

Tra cứu mã lỗi

Mã	Mô tả	Trạng thái HTTP
`10000`	Thành công (đã ủy quyền, hoặc đã gửi TRX)	200
`10000`	Thành công (phản hồi được lưu trong bộ nhớ cache)	208
`10001`	Đã chấp nhận, đang được xử lý bởi nhà cung cấp bên ngoài	202
`10002`	Người nhận đã có đủ Bandwidth (không bị tính phí)	200
`10003`	Lượt chạy thử — xem trước kết quả + giá, không bị tính phí (`test=true`)	200
`10004`	Bandwidth đã được thu hồi (tự nguyện hủy ủy quyền) — trả về `reclaimHash`	200
`-`	Yêu cầu trùng lặp vẫn đang được xử lý	409
`-1`	Khóa API không hợp lệ / IP không có trong danh sách trắng	401
`1004`	Không đủ số dư	403
`1005`	Không có địa chỉ thanh toán cho người dùng	400
`5004`	Số lượng/thời hạn không hợp lệ (xác thực dữ liệu)	400
`5005`	Không có gì để thu hồi (đơn hàng không ở trạng thái được ủy quyền)	400
`5007`	Không có công nhận — chỉ được thuê một lần tại một thời điểm; đơn hàng trước vẫn đang hoạt động (chờ cho đến khi kết thúc)	503
`5008`	Không có công nhận — chỉ cho phép đơn hàng 400 đơn vị trong 5 phút; yêu cầu công nhận đối với các số lượng lớn hơn hoặc thời hạn 1 giờ	503
`5003`	Ủy quyền Bandwidth thất bại / không khả dụng	503
`5000`	Lỗi máy chủ nội bộ	500

Giới hạn tốc độ

Chu kỳ	Giới hạn	Mô tả
1 giây	50 yêu cầu	Tối đa 50 yêu cầu mỗi giây trên mỗi IP

Vượt quá giới hạn tần suất (429)

json

{ "message": "API rate limit exceeded" }

Tính lũy đẳng

Gửi tiêu đề X-Idempotency-Key tùy chọn để việc lặp lại vô tình không tạo ra đơn hàng thứ hai — phản hồi gốc được trả về với HTTP 208. Nếu bạn không gửi tiêu đề, máy chủ sẽ tự động suy ra một khóa từ các tham số yêu cầu của bạn trong một khoảng thời gian ngắn.

Cách tạo khóa

Khóa là base64( HMAC-SHA256( secret, message ) ) — một chuỗi base64 gồm 44 ký tự, trong đó:

secret = khóa API của bạn (X-API-KEY);
message = các trường được nối với dấu : — receiveAddress:amount:period:nonce.

nonce là bất kỳ giá trị nào ổn định qua các lần thử lại của cùng một đơn hàng hợp lý nhưng khác nhau giữa các đơn hàng riêng biệt — ví dụ: một UUID bạn giữ cho đơn hàng đó, hoặc một nhóm dấu thời gian khái quát. Tạo khóa một lần cho mỗi đơn hàng và gửi lại giá trị chính xác đó trên mọi lần thử lại.

python

import hmac, hashlib, base64, time

def make_idempotency_key(api_key, receive_address, amount, period, nonce=None):
    if nonce is None:
        nonce = str(int(time.time() // 2))   # 2-second bucket; or your own order UUID
    message = f"{receive_address}:{amount}:{period}:{nonce}"
    digest = hmac.new(api_key.encode(), message.encode(), hashlib.sha256).digest()
    return base64.b64encode(digest).decode()  # 44-char base64

bash

# then send it as a header:
-H "X-Idempotency-Key: <base64_key>"

Bao gồm period trong thông điệp là rất quan trọng: việc thuê cho cùng một địa chỉ trong 5m và trong 1h là các đơn hàng khác nhau và phải tạo ra các khóa khác nhau.

Xác thực. Một X-Idempotency-Key được cung cấp phải là một chuỗi base64 gồm 16–64 ký tự (tập ký tự A–Z a–z 0–9 + / = _ -). Một khóa không đúng định dạng hoặc quá dài sẽ bị từ chối với HTTP 400 (code 5004).

Mã trạng thái	Ý nghĩa
200	Đã xử lý thành công (yêu cầu đầu tiên)
208	Đã xử lý thành công trước đó — phản hồi được lưu trong bộ nhớ cache được trả về (không tính phí lần hai)
409	Yêu cầu tương tự hiện đang được xử lý — vui lòng đợi, chưa thử lại ngay

Thử lại sau khi thất bại. Chỉ các kết quả thành công (completed / enough) mới được lưu trong bộ nhớ cache. Nếu lần thử trước đó thất bại hoặc quá thời gian (không có tiền nào bị trừ), bạn có thể thử lại một cách an toàn với cùng một X-Idempotency-Key — đơn hàng sẽ được thử lại thay vì trả về lỗi cũ. Trong khi một lượt thử vẫn đang được tiến hành, bạn sẽ nhận được 409; hãy đợi và thử lại.

Tài khoản trả sau

Các tài khoản thuộc diện thanh toán trả sau sử dụng cùng endpoint, URL, các header và request body như những người khác. Điểm khác biệt là cách đơn hàng được thanh toán:

Không có khoản tiền nào bị khấu trừ từ tiền đặt cọc của bạn. Mỗi đơn hàng được giao thành công sẽ được cộng vào số dư nợ trên tài khoản của bạn theo loại tiền quyết toán đã thỏa thuận trong hợp đồng của bạn. Bạn thanh toán khoản này qua hóa đơn, theo thỏa thuận của bạn.
Tài khoản của bạn có một hạn mức tín dụng. Khi số tiền nợ còn nằm trong hạn mức, các đơn hàng vẫn được chấp nhận ngay cả khi số tiền đặt cọc bằng 0. Các lượt thuê trong 5 phút và 1 giờ đều được tính vào cùng một hạn mức Bandwidth.
Chỉ những dịch vụ đã được bàn giao mới được lập hóa đơn: Bandwidth được ủy quyền cho địa chỉ, hoặc TRX được gửi thay thế (fulfilledBy = trx). Số tiền tương đương với các đơn hàng trả trước.
Một đơn hàng bị từ chối, không được thực thi, một lượt chạy thử (test: true) hoặc được phản hồi bằng enough (check: true) sẽ không tốn chi phí.
Việc tự nguyện thu hồi sớm không làm giảm số tiền phải trả, tương tự như đối với các đơn hàng trả trước.
Các cấp truy cập, số lượng, khoảng thời gian và tất cả các quy tắc khác của endpoint này đều giống như đối với các tài khoản trả trước.

Thanh toán trả sau được Netts kích hoạt cho một tài khoản theo yêu cầu. Mỗi phản hồi sẽ cho bạn biết cách đơn hàng được thanh toán: paymentMode là postpaid hoặc prepaid.

Kiểm tra giá (`test: true`)

json

{
    "amount": 1000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "period": "5m",
    "test": true
}

json

{
    "detail": {
        "code": 10003,
        "status": "test",
        "msg": "Test run — no on-chain action, no charge",
        "data": {
            "orderId": "B5M1a2b3c4d5e6f70",
            "testAction": "would_delegate",
            "wouldCostTRX": 0.7,
            "paidTRX": 0,
            "bandwidth": 1000,
            "period": "5m",
            "receiverFreeBandwidth": 600,
            "paymentMode": "postpaid"
        }
    }
}

wouldCostTRX là số tiền sẽ được thêm vào số dư nợ của bạn, tính bằng TRX. Không có gì được ủy quyền hoặc lập hóa đơn.

Đơn hàng thành công

json

{
    "detail": {
        "code": 10000,
        "status": "completed",
        "msg": "Successful, 0.700000 TRX, postpaid",
        "data": {
            "orderId": "B5M0f9e8d7c6b5a41",
            "paidTRX": 0.7,
            "fulfilledBy": "bandwidth",
            "hash": ["<txid>"],
            "bandwidth": 1000,
            "period": "5m",
            "paymentMode": "postpaid",
            "totalTRX": "0.700000"
        }
    }
}

Trường	Mô tả
paidTRX	Chi phí dịch vụ tính bằng TRX. Đối với các tài khoản trả sau, khoản này không bị trừ vào khoản tiền đặt cọc
paymentMode	`postpaid`
totalTRX	Số tiền chính xác, 6 chữ số thập phân

Tất cả các trường khác, bao gồm cả nhánh TRX (fulfilledBy = trx, trxSendHash), đều giống như đối với các đơn hàng trả trước.

Đã đạt đến hạn mức tín dụng (402)

json

{
    "detail": {
        "code": 1004,
        "msg": "Postpaid credit limit reached.",
        "paymentMode": "postpaid",
        "reason": "limit_reached"
    }
}

Đơn hàng không được thực thi và không có gì được lập hóa đơn. Các đơn hàng mới sẽ được chấp nhận trở lại sau khi khoản thanh toán của bạn được ghi nhận hoặc hạn mức của bạn được tăng lên.

Các mã lỗi cho tài khoản trả sau

Mã	HTTP	Mô tả
`1004`	402	Đã đạt đến hạn mức tín dụng trả sau
`5032`	503	Giá tạm thời không khả dụng
`5034`	503	Hệ thống thanh toán tạm thời không khả dụng — đơn hàng không được chấp nhận
`5036`	503	Việc kiểm tra tín dụng tạm thời không khả dụng — thử lại sau

Đối với tất cả các phản hồi ở trên, không có gì được đặt hàng và không có gì được lập hóa đơn. Tất cả các mã khác đều giống như đối với các đơn hàng trả trước.

Ghi chú

Các cấp truy cập: các tài khoản được công nhận thuê bất kỳ số lượng nào trong giới hạn pool/tối đa với các đơn hàng đồng thời; không có công nhận — 400 đơn vị trong 5 phút, một lần (đơn hàng tiếp theo chỉ sau khi lần thuê trước kết thúc). Liên hệ hỗ trợ Netts để được công nhận.
Tối thiểu: 400 đơn vị. Tối đa: 5000 đơn vị cho mỗi đơn hàng (cấu hình hiện tại).
Các khoảng thời gian: 5m (300 giây) và 1h (3600 giây, chỉ dành cho tài khoản được công nhận). Bandwidth sẽ được tự động thu hồi khi hết thời hạn.
Không có vùng đệm: chính xác số lượng yêu cầu sẽ được ủy quyền.
hash là một mảng: một đơn hàng duy nhất có thể tạo ra tối đa 10 hash ủy quyền — tất cả đều được trả về.
Định giá: được tính bằng TRX, dựa trên số lượng và khoảng thời gian yêu cầu; biểu giá có thể thay đổi tùy theo thời điểm trong ngày. Liên hệ hỗ trợ để biết mức giá hiện tại.
Bồi hoàn đơn hàng nhỏ (ủy quyền): đối với các đơn hàng dưới 1000 đơn vị, một khoản cố định 0.372 TRX sẽ được cộng vào giá để bồi hoàn cho việc ủy quyền và thu hồi on-chain. Các đơn hàng từ 1000 đơn vị trở lên không có khoản cộng thêm này.
Bồi hoàn gửi TRX: khi đơn hàng được thực hiện bằng cách gửi TRX (fulfilledBy = trx), một khoản cố định 0.268 TRX sẽ được cộng thêm vào thay thế (bồi hoàn cho việc chuyển TRX on-chain).
trx_send: chỉ dành cho amount = 400; nếu không có sẵn Bandwidth, TRX sẽ được gửi đến địa chỉ để giao dịch vẫn được thực hiện thành công.
check: bỏ qua việc ủy quyền (và tính phí) khi người nhận đã có hơn 400 Bandwidth.
Định dạng ID đơn hàng: B5M… (5 phút) / B1H… (1 giờ).
Thời gian chờ phản hồi: lên tới khoảng 12 giây trong khi chờ ủy quyền; thông thường là 1–2 giây.

POST /apiv2/bandwidth ​

URL của Endpoint ​

Headers của yêu cầu ​

Body của yêu cầu ​

Tham số yêu cầu ​

Ví dụ ​

cURL ​

Python ​

Phản hồi ​

Thành công — Bandwidth đã được ủy quyền (200 OK) ​

Thành công — TRX được gửi thay vì Bandwidth (200 OK, chỉ khi amount=400 + trx_send=true) ​

Đã có đủ — không bị tính phí (200 OK, chỉ khi check=true) ​

Đang xử lý — nhà cung cấp bên ngoài (202 Accepted) ​

Lượt chạy thử (200 OK, chỉ khi test=true) ​

Các trường phản hồi ​

Endpoint trạng thái ​

Thu hồi Endpoint ​

Phản hồi lỗi ​

Lỗi xác thực (401) ​

Không đủ số dư (403) ​

Lỗi xác thực dữ liệu (400) ​

Ủy quyền thất bại / Dịch vụ không khả dụng (503) ​

Tra cứu mã lỗi ​

Giới hạn tốc độ ​

Vượt quá giới hạn tần suất (429) ​

Tính lũy đẳng ​

Cách tạo khóa ​

Tài khoản trả sau ​

Kiểm tra giá (test: true) ​

Đơn hàng thành công ​

Đã đạt đến hạn mức tín dụng (402) ​

Các mã lỗi cho tài khoản trả sau ​

Ghi chú ​

POST /apiv2/bandwidth

URL của Endpoint

Headers của yêu cầu

Body của yêu cầu

Tham số yêu cầu

Ví dụ

cURL

Python

Phản hồi

Thành công — Bandwidth đã được ủy quyền (200 OK)

Thành công — TRX được gửi thay vì Bandwidth (200 OK, chỉ khi `amount=400` + `trx_send=true`)

Đã có đủ — không bị tính phí (200 OK, chỉ khi `check=true`)

Đang xử lý — nhà cung cấp bên ngoài (202 Accepted)

Lượt chạy thử (200 OK, chỉ khi `test=true`)

Các trường phản hồi

Endpoint trạng thái

Thu hồi Endpoint

Phản hồi lỗi

Lỗi xác thực (401)

Không đủ số dư (403)

Lỗi xác thực dữ liệu (400)

Ủy quyền thất bại / Dịch vụ không khả dụng (503)

Tra cứu mã lỗi

Giới hạn tốc độ

Vượt quá giới hạn tần suất (429)

Tính lũy đẳng

Cách tạo khóa

Tài khoản trả sau

Kiểm tra giá (`test: true`)

Đơn hàng thành công

Đã đạt đến hạn mức tín dụng (402)

Các mã lỗi cho tài khoản trả sau

Ghi chú