POST /apiv2/usdt/analyze

Tính toán chi phí chuyển USDT trên TRON (endpoint riêng tư — đã xác thực).

Trả về cấu trúc dữ liệu TransferAnalysis hoàn toàn giống với biến thể GET công khai, nhưng với giới hạn tần suất cao hơn nhiều (50 yêu cầu/giây trên mỗi node Kong thay vì 1 yêu cầu/giây) và dữ liệu yêu cầu được truyền trong body JSON thay vì trên URL. Hãy sử dụng endpoint này cho mọi tích hợp trên môi trường production.

URL Endpoint

POST https://netts.io/apiv2/usdt/analyze

Xác thực

Chấp nhận một trong hai header sau (cả hai đều được hỗ trợ đồng thời; ưu tiên dùng X-API-KEY vì nó đồng nhất với toàn bộ giao diện API /apiv2/* của Netts):

Header	Bắt buộc	Mô tả
`Content-Type`	Có	Phải là `application/json`.
`X-API-KEY`	Ưu tiên	API key Netts của bạn — định dạng hoàn toàn giống với định dạng dùng cho `/apiv2/order1h` và các endpoint Netts đã xác thực khác.
`Authorization`	Được chấp nhận thay thế	`Bearer {key}` hoặc chỉ `{key}` (không có tiền tố). Sử dụng tùy chọn này nếu HTTP client của bạn có sẵn quy trình bearer/auth tích hợp.

Nếu cả hai header đều được gửi, X-API-KEY sẽ được ưu tiên sử dụng.

Danh sách trắng IP: IP mà từ đó yêu cầu gửi đến edge của chúng tôi phải nằm trong danh sách trắng đã được cấu hình cho API key của bạn (cơ chế tương tự như các endpoint /apiv2/* khác). Các yêu cầu từ IP không nằm trong danh sách trắng sẽ trả về 401 Unauthorized kèm "Invalid API key or IP not in whitelist".

Tái sử dụng header từ order1h của bạn

Nếu bạn đã gọi /apiv2/order1h với X-API-KEY: {key}, bạn có thể gửi chính xác header X-API-KEY đó tới /apiv2/usdt/analyze — công cụ tính toán hiện đã nhận diện nó là header xác thực chính.

Body của yêu cầu

json

{
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
}

Các trường

Trường	Loại	Bắt buộc	Ràng buộc
`sender_address`	string	Có	Địa chỉ TRON hợp lệ — 34 ký tự, bắt đầu bằng `T`, checksum base58 hợp lệ.
`receiver_address`	string	Có	Địa chỉ TRON hợp lệ; phải khác với `sender_address`.

TIP

Không có trường amount. Công cụ tính toán sẽ trả về chi phí và yêu cầu tài nguyên cho một lần chuyển USDT duy nhất giữa hai địa chỉ; nếu bạn cần chi tiết cho một lượng USDT cụ thể, hãy nhân lượng Energy khuyến nghị với số lần chuyển ở phía bạn — một giao dịch chuyển TRC-20 USDT đơn lẻ sẽ tiêu tốn cùng một lượng ~130 k Energy bất kể số lượng chuyển.

Ví dụ về yêu cầu

cURL (ưu tiên — `X-API-KEY`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

cURL (thay thế — `Authorization`)

bash

curl -X POST "https://netts.io/apiv2/usdt/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
        "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
        "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL"
      }'

Python

python

import requests

API_KEY = "YOUR_API_KEY"

payload = {
    "sender_address":   "TFLit1TFohBtT2f8UVCLFVPmZxawxqByYe",
    "receiver_address": "TTKR9aQdJWTgXLK9cmzaDitT5VXE497thL",
}

r = requests.post(
    "https://netts.io/apiv2/usdt/analyze",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY":    API_KEY,           # preferred; same header as /apiv2/order1h
        # or, equivalently:
        # "Authorization": f"Bearer {API_KEY}",
    },
    json=payload,
    timeout=15,
)

if r.status_code == 200:
    data = r.json()["data"]
    print("Energy needed:", data["requirements"]["energy_with_buffer"])
    print("Total cost:   ", data["costs"]["total_cost_trx"], "TRX")
    print("Method:       ", data["costs"]["recommended_method"])
elif r.status_code == 401:
    print("Auth failed:", r.json())
elif r.status_code == 429:
    print("Rate-limited — Retry-After:", r.headers.get("Retry-After"))
else:
    print("Error:", r.status_code, r.json())

Phản hồi

Thành công (200 OK)

Cấu trúc bao đóng tương tự như endpoint công khai:

json

{
    "status": "success",
    "data": { /* TransferAnalysis — see the public-endpoint page */ },
    "current_utc_time": "2026-04-23 11:54:13",
    "processing_time_ms": 20.14
}

Mô tả chi tiết từng trường của data có tại trang của endpoint công khai — xem TransferAnalysis, AddressInfo, Requirements và Costs.

Lỗi

Thứ tự kiểm tra

Xác thực được kiểm tra trước khi kiểm tra tính hợp lệ của body. Nếu header Authorization bị thiếu/không hợp lệ hoặc IP của bạn không nằm trong danh sách trắng, bạn sẽ luôn luôn nhận mã lỗi 401 — ngay cả khi body JSON cũng bị sai định dạng. Hãy xử lý vấn đề xác thực trước, sau đó kiểm tra lại với key hợp lệ; chỉ khi đó các lỗi kiểm tra body của Pydantic (422) mới xuất hiện.

HTTP	Body	Thời điểm
401	`{"code": -1, "msg": "API key not provided (expected X-API-KEY or Authorization header)"}`	Cả hai header `X-API-KEY` và `Authorization` đều không có.
401	`{"code": -1, "msg": "Invalid API key or IP not in whitelist"}`	Key không tồn tại, hoặc IP gửi yêu cầu không nằm trong danh sách trắng của bạn.
404	`{"code": -1, "msg": "User not found"}`	Key hợp lệ nhưng không tìm thấy bản ghi người dùng (hiếm gặp).
422	`{"detail": [{"loc": ["body","sender_address"], "msg": "Invalid TRON address length", "type": "value_error"}]}`	Xác thực body của FastAPI/Pydantic thất bại. Trạng thái là `422 Unprocessable Entity`, không phải `400`.
422	`{"detail": [{..., "msg": "Sender and receiver cannot be the same address", "type": "value_error"}]}`	`sender_address == receiver_address`.
429	`{"message": "API rate limit exceeded"}`	Lượng truy cập liên tục vượt quá `50 req/sec` trên một node Kong.
500	`{"code": -1, "msg": "Internal server error"}`	Lỗi phía máy chủ không mong muốn.

Giới hạn tần suất

50 yêu cầu / giây trên mỗi node Kong (limit_by = ip, chính sách local).
Giới hạn theo minute / hour không được thiết lập — chỉ áp dụng giới hạn theo từng giây.
Mỗi phản hồi đều chứa các header chuẩn của Kong: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit-Second, X-RateLimit-Remaining-Second, và Retry-After khi gặp lỗi 429.

Ví dụ phản hồi 429

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 0

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

TIP

Nếu bạn đạt mức 50 yêu cầu/giây với một API key duy nhất và cần mức cao hơn, hãy liên hệ bộ phận hỗ trợ — giới hạn có thể được tăng lên theo từng key, hoặc một plugin rate-limit chuyên dụng có thể được gán cho consumer của bạn.

Header gỡ lỗi

Mỗi phản hồi cũng chứa các định danh hữu ích khi mở yêu cầu hỗ trợ — vui lòng đính kèm chính xác nguyên văn để chúng tôi có thể tìm thấy yêu cầu trong nhật ký hệ thống trong vài giây:

Header	Ý nghĩa
`X-Request-ID`	ID yêu cầu phía ứng dụng (do công cụ tính toán tạo ra).
`X-Process-Time`	Thời gian xử lý của ứng dụng tính bằng mili-giây (phía upstream, không bao gồm Kong).
`X-Kong-Request-Id`	ID yêu cầu phía Kong (có trong nhật ký truy cập của Kong).

Thời gian chờ (timeout) và thử lại phía client

Công cụ tính toán thực hiện các truy vấn on-chain trực tiếp tới các node TRON cho mỗi yêu cầu, vì vậy khi hệ thống chịu tải hoặc các node upstream phản hồi chậm, một lệnh gọi duy nhất có thể mất vài giây. Thời gian chờ phía client quá ngắn sẽ dẫn đến lỗi ngay cả đối với các phản hồi bình thường — đây là nguyên nhân gốc rễ của hầu hết các báo cáo lỗi cURL error 28 (Connection timed out) từ phía tích hợp.

Các thiết lập khuyến nghị:

Thời gian chờ ≥ 15 giây (30 giây sẽ an toàn hơn). Mức mặc định 10 giây được sử dụng bởi nhiều HTTP client là quá ngắn.
Đối với HTTP 429, hãy tuân thủ header Retry-After (tính bằng giây). Thêm một khoảng dao động nhỏ (jitter, ví dụ 0–200 ms) trước khi thử lại, sau đó áp dụng exponential backoff nếu bạn vẫn chạm mức giới hạn 50 yêu cầu/giây.
Đối với HTTP 5xx hoặc lỗi mạng, thử lại tối đa 2–3 lần với exponential backoff; không gửi dồn dập các yêu cầu tới endpoint.
Lưu cache kết quả phía client trong 30–60 giây cho mỗi cặp (sender_address, receiver_address) — giá tài nguyên cơ bản và trạng thái on-chain hiếm khi thay đổi đủ nhanh để cần phải tính toán lại thường xuyên hơn.

Hỗ trợ trình duyệt / CORS

Endpoint này được thiết kế cho việc tích hợp server-to-server và hiện không hỗ trợ gọi trực tiếp từ trình duyệt: ứng dụng FastAPI upstream chỉ khai báo Access-Control-Allow-Methods: GET, vì vậy yêu cầu preflight OPTIONS cho một POST cross-origin sẽ thất bại trên trình duyệt.

Nếu bạn cần gọi công cụ tính toán từ front-end của trình duyệt, hãy chuyển tiếp yêu cầu thông qua back-end của chính bạn (nơi lưu giữ API key) thay vì để lộ key cho phía client.

TIP

Nếu trường hợp sử dụng của bạn thực sự đòi hỏi gửi yêu cầu POST từ phía trình duyệt kèm API key (ví dụ: trang quản trị nội bộ đáng tin cậy trên một origin đã biết), hãy liên hệ bộ phận hỗ trợ — một plugin CORS có thể được gắn ở cấp độ Kong cho route của bạn.

Ghi chú

Định dạng phản hồi được cố ý thiết kế giống hệt với endpoint công khai, do đó mã phía client phân tích cú pháp phản hồi công khai vẫn tiếp tục hoạt động sau khi bạn chuyển sang biến thể đã xác thực — chỉ có bản thân lệnh gọi là thay đổi.
Cả X-API-KEY: {key} (ưu tiên, đồng nhất với /apiv2/order1h) và Authorization: Bearer {key} / Authorization: {key} đều được chấp nhận; nếu cả hai đều được gửi, X-API-KEY sẽ được ưu tiên sử dụng.
Việc đặt thêm Cloudflare / reverse-proxy không ảnh hưởng đến endpoint này theo cách mà nó ảnh hưởng đến endpoint công khai, bởi vì lưu lượng đã xác thực được giới hạn tần suất theo từng node Kong và các ngữ nghĩa theo từng consumer có thể được kích hoạt theo yêu cầu.

POST /apiv2/usdt/analyze ​

URL Endpoint ​

Xác thực ​

Body của yêu cầu ​

Các trường ​

Ví dụ về yêu cầu ​

cURL (ưu tiên — X-API-KEY) ​

cURL (thay thế — Authorization) ​

Python ​

Phản hồi ​

Thành công (200 OK) ​

Lỗi ​

Giới hạn tần suất ​

Ví dụ phản hồi 429 ​

Header gỡ lỗi ​

Thời gian chờ (timeout) và thử lại phía client ​

Hỗ trợ trình duyệt / CORS ​

Ghi chú ​