POST /apiv2/order5m

Tạo đơn thuê Energy 5 phút thông qua các nhóm Energy nội bộ của Netts.

URL endpoint

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

Header yêu cầu

Header	Required	Description
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

Body yêu cầu

json

{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

Tham số yêu cầu

Parameter	Type	Required	Description
amount	integer	Có	Số lượng Energy cần thuê (tối thiểu: 61.000, tối đa: 650.000)
receiveAddress	string	Có	Địa chỉ TRON sẽ nhận Energy (định dạng TRC-20)

Giới hạn Energy

Endpoint 5 phút chấp nhận số lượng Energy từ 61.000 đến 650.000 đơn vị cho mỗi đơn hàng. Các yêu cầu ngoài phạm vi này sẽ bị từ chối với mã HTTP 400.

Thông tin nhà cung cấp

Các đơn hàng Energy 5 phút được thực hiện độc quyền thông qua các nhóm Energy nội bộ của Netts. Không giống như endpoint 1 giờ, các nhà cung cấp bên ngoài không được sử dụng.

Tính khả dụng & Chiến lược thử lại

Vì việc ủy quyền chỉ đến từ các nhóm nội bộ, tình trạng tạm thời không khả dụng có thể xảy ra trong các khoảng thời gian nhu cầu cao. Nếu bạn nhận được lỗi 503, hãy thử lại yêu cầu sau một khoảng thời gian ngắn hoặc chuyển hướng dự phòng sang endpoint 1 giờ vốn có quyền truy cập vào nhiều nhà cung cấp bên ngoài.

Ví dụ

cURL

bash

curl -X POST https://netts.io/apiv2/order5m \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'

Python

python

import requests

url = "https://netts.io/apiv2/order5m"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "your_api_key",
    "X-Real-IP": "your_whitelisted_ip"
}

payload = {
    "amount": 65000,
    "receiveAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

if response.status_code == 200:
    detail = data.get('detail', {})
    order_data = detail.get('data', {})
    print(f"Order ID: {order_data.get('orderId')}")
    print(f"Transaction Hash: {order_data.get('hash')}")
    print(f"Energy Delivered: {order_data.get('energy')}")
    print(f"Cost: {order_data.get('paidTRX')} TRX")
    print(f"Delegate Address: {order_data.get('delegateAddress')}")
elif response.status_code == 503:
    # Pool temporarily unavailable - retry or fallback to 1h
    print("Pool busy, retrying in 2 seconds...")
else:
    error_detail = data.get('detail', data)
    print(f"Error Code: {error_detail.get('code', 'N/A')}")
    print(f"Error Message: {error_detail.get('msg', error_detail)}")

Phản hồi

Phản hồi thành công (200 OK)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050
        }
    }
}

Thành công kèm kích hoạt địa chỉ (200 OK)

Khi địa chỉ người nhận chưa được kích hoạt trên mạng lưới TRON, Netts sẽ tự động kích hoạt nó. Chi phí kích hoạt được cộng vào tổng số tiền:

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX for energy + 1.100 TRX for address activation",
        "data": {
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 2.53,
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq",
            "energy": 65050,
            "activationHash": "bab38070a64b237acc9110ecf5135acc..."
        }
    }
}

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

Field	Type	Description
detail.code	integer	Luôn là `10000` cho các đơn hàng thành công
detail.msg	string	Thông báo thành công kèm số tiền bị khấu trừ
detail.data.orderId	string	ID đơn hàng hợp nhất (định dạng: `5M{id}`)
detail.data.paidTRX	number	Tổng chi phí bằng TRX (bao gồm phí kích hoạt nếu có)
detail.data.hash	string	Mã băm giao dịch ủy quyền
detail.data.delegateAddress	string	Địa chỉ nhóm đã ủy quyền Energy
detail.data.energy	integer	Số lượng Energy + phần đệm (thường là +50)
detail.data.activationHash	string	Chỉ xuất hiện nếu thao tác kích hoạt địa chỉ đã được thực hiện

Phản hồi lỗi

Số lượng Energy không hợp lệ (400)

json

{
    "code": 1003,
    "msg": "Energy amount must be between 61000 and 650000. Requested: 50000"
}

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

json

{
    "detail": "Invalid API key or IP not in whitelist"
}

Số dư không đủ (403)

json

{
    "code": 1004,
    "msg": "Insufficient funds. Required: 1.43 TRX, Available: 0.50 TRX"
}

Dịch vụ không khả dụng (503)

json

{
    "code": 5003,
    "msg": "Service temporarily unavailable. Energy delegation failed after retries."
}

Xử lý lỗi 503

Phản hồi 503 có nghĩa là các nhóm nội bộ đang tạm thời hết công suất. Chiến lược khuyến nghị:

Đợi 2-3 giây và thử lại đơn hàng 5 phút
Nếu vẫn không khả dụng, hãy chuyển hướng dự phòng sang endpoint 1 giờ vốn sử dụng nhiều nhà cung cấp

Lỗi máy chủ nội bộ (500)

json

{
    "code": 5000,
    "msg": "Internal server error occurred"
}

Bảng tham chiếu mã lỗi

Code	Description	HTTP Status
`10000`	Thành công	200
`10000`	Thành công (phản hồi được lưu trong bộ nhớ tạm)	208
`-`	Yêu cầu trùng lặp vẫn đang được xử lý	409
`1003`	Số lượng Energy nằm ngoài phạm vi	400
`1004`	Số dư không đủ	403
`1005`	Chưa cấu hình địa chỉ người thanh toán của người dùng	400
`5000`	Lỗi máy chủ nội bộ	500
`5003`	Dịch vụ Energy không khả dụng	503

Giới hạn tốc độ

Các giới hạn tốc độ sau áp dụng cho endpoint này (trên mỗi địa chỉ IP):

Giai đoạn	Giới hạn	Description
1 giây	50 yêu cầu	Tối đa 50 yêu cầu mỗi giây

Header giới hạn tốc độ

http

RateLimit-Limit: 50
RateLimit-Remaining: 49
RateLimit-Reset: 1
X-RateLimit-Limit-Second: 50
X-RateLimit-Remaining-Second: 49

Vượt quá giới hạn tốc độ (429)

json

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

Tính lũy quyền (Idempotency)

API hỗ trợ tính lũy quyền để ngăn chặn việc xử lý đơn hàng trùng lặp. Khi bạn gửi nhiều yêu cầu giống hệt nhau, hệ thống đảm bảo đơn hàng chỉ được xử lý một lần duy nhất.

Cơ chế hoạt động của tính lũy quyền

Tính duy nhất của yêu cầu được xác định bởi sự kết hợp của:

Dấu thời gian yêu cầu (khoảng thời gian 2 giây)
Số lượng Energy
Địa chỉ người nhận
Khóa API

Mỗi yêu cầu được cấp một khoảng thời gian duy nhất 2 giây. Các yêu cầu có tham số giống hệt nhau trong khoảng thời gian này sẽ được coi là trùng lặp.

Cung cấp khóa của riêng bạn

Bạn có thể chủ động kiểm soát tính lũy quyền bằng cách gửi header X-Idempotency-Key. Khi nó xuất hiện, chỉ riêng giá trị đó sẽ quyết định xem một yêu cầu có phải là lặp lại hay không, và sự kết hợp tự động ở trên sẽ không được sử dụng. Khi vắng mặt, không có gì thay đổi — máy chủ sẽ tự suy ra khóa cho bạn.

Các quy tắc tương tự như trên /apiv2/order1h:


Header	`X-Idempotency-Key`
Định dạng	Chính xác 64 ký tự thập lục phân viết thường — một chuỗi băm SHA-256
Thời gian tồn tại	24 giờ kể từ yêu cầu đầu tiên mang khóa đó
Phạm vi	Tài khoản của bạn. Cùng một giá trị được gửi bởi một tài khoản khác sẽ không bao giờ trả về kết quả của bạn

Một khóa có bất kỳ định dạng nào khác — một UUID có dấu gạch ngang, base64, chữ thập lục phân viết hoa — sẽ bị từ chối với mã 400 trước khi đơn hàng được đặt và trước khi bất kỳ khoản phí nào được tính:

json

{
    "detail": "Invalid idempotency key format. Must be 64-character hexadecimal string."
}

Hãy tạo khóa từ khóa API của bạn để nó là duy nhất cho tài khoản của bạn và có thể tái tạo khi thử lại — ví dụ chi tiết có trên trang 1 giờ. Hãy đưa thời hạn thuê vào thông điệp mà bạn băm: thuê cùng một địa chỉ trong 5 phút và trong 1 giờ là các đơn hàng khác nhau, và việc tái sử dụng một khóa cho cả hai sẽ trả về phản hồi của đơn hàng đầu tiên cho yêu cầu thứ hai.

Đặt hai đơn hàng giống hệt nhau

Cùng một cái bẫy như trên endpoint theo giờ, với một khoảng thời gian rộng hơn. Hai đơn hàng giống hệt nhau — cùng số lượng đến cùng một địa chỉ — không thể phân biệt được với một lần thử lại, và chỉ có thời điểm gửi đến mới tách biệt được chúng.

Khi không có khóa của riêng bạn:

Khoảng cách giữa hai yêu cầu	Điều gì xảy ra
Trong cùng khoảng thời gian 2 giây	Yêu cầu thứ hai được coi là lặp lại. Nó không được thực thi: bạn nhận được `208` và phản hồi của đơn hàng đầu tiên. Không có khoản phí nào bị tính cho nó
Cách nhau hơn hai giây	Hai khóa khác nhau — cả hai đơn hàng đều được đặt và cả hai đều bị tính phí

Vì vậy, hãy để cách nhau hơn hai giây giữa hai đơn hàng giống hệt nhau, và đọc mã trạng thái: 208 có nghĩa là đơn hàng bạn vừa gửi đã không được đặt.

Việc tạm dừng chỉ là một giải pháp tình thế, không phải là một cách khắc phục triệt để — nó cũng tách biệt các yêu cầu mà bạn chưa bao giờ có ý định lặp lại, chẳng hạn như thử lại sau khi hết thời gian chờ hoặc một tin nhắn được gửi lại bởi hàng đợi của bạn, và mỗi yêu cầu đó sẽ trở thành một đơn hàng riêng biệt với một khoản phí riêng biệt. Gửi khóa của riêng bạn là cách giải quyết triệt để vấn đề: một nonce mới cho một đơn hàng mới, nonce của lần thử đầu tiên cho một lần thử lại. Toàn bộ lập luận chi tiết có trên trang 1 giờ.

Mã trạng thái HTTP cho các yêu cầu trùng lặp

Mã trạng thái	Tên	Description
200	OK	Đơn hàng đã được xử lý thành công (yêu cầu đầu tiên)
208	Already Reported	Đơn hàng đã được xử lý, trả về phản hồi được lưu trong bộ nhớ tạm
409	Conflict	Yêu cầu hiện đang được xử lý, không thử lại

Yêu cầu trùng lặp - Đã được xử lý (208)

json

{
    "detail": {
        "code": 10000,
        "msg": "Successful, 1.430 TRX deducted",
        "data": {
            "hash": "3636f97dde244fca17cdc0b2cf7fd157...",
            "energy": 65050,
            "orderId": "5Mb4ee11ef86",
            "paidTRX": 1.43,
            "delegateAddress": "TNp5gsJhBmZFXgCdgjMgr8pEZ8fHgXUHDq"
        }
    },
    "idempotency": {
        "status": "completed",
        "cached": true,
        "original_created_at": "2026-03-21T08:53:52.498000"
    }
}

Yêu cầu trùng lặp - Vẫn đang xử lý (409)

json

{
    "success": false,
    "error": "duplicate_request_processing",
    "message": "This request is currently being processed. Please wait and do not retry.",
    "retry_after_seconds": 3
}

Các phương pháp hay nhất

Không gửi các yêu cầu song song với cùng các tham số - hãy đợi từng phản hồi
Xử lý phản hồi 409 bằng cách chờ đợi, không thử lại ngay lập tức
Kiểm tra trường idempotency.cached để xác định các phản hồi được lưu trong bộ nhớ tạm

So sánh: Đơn hàng 5 phút so với 1 giờ

Tính năng	Đơn hàng 5 phút	Đơn hàng 1 giờ
Endpoint	`/apiv2/order5m`	`/apiv2/order1h`
Thời hạn	5 phút	1 giờ
Phạm vi Energy	61.000 - 650.000	61.000 - 3.000.000
Nhà cung cấp	Chỉ các nhóm nội bộ của Netts	Các nhóm nội bộ + nhà cung cấp bên ngoài
Giá	Thấp hơn (giá 5 phút)	Giá tiêu chuẩn theo giờ
Tính khả dụng	Có thể bị giới hạn trong giờ cao điểm	Cao (dự phòng nhiều nhà cung cấp)
Phù hợp nhất cho	Các giao dịch nhỏ thường xuyên	Khối lượng lớn hoặc đảm bảo phân phối

Ghi chú

Energy được phân phối ngay lập tức sau khi đặt hàng thành công (thường trong vòng 0,5-2 giây)
Thời gian chờ phản hồi API: Tối đa 10 giây (bao gồm các lần thử lại nội bộ)
Kích hoạt địa chỉ: Nếu địa chỉ người nhận chưa được kích hoạt, Netts sẽ kích hoạt theo giá gốc. Chi phí kích hoạt chỉ được tính một lần cho mỗi địa chỉ
Thời hạn: Cố định 5 phút (300 giây)
Số lượng Energy tối thiểu: 61.000 đơn vị
Số lượng Energy tối đa: 650.000 đơn vị cho mỗi đơn hàng
Phần đệm Energy: Tự động cộng thêm +50 đơn vị (miễn phí)
Định dạng ID đơn hàng: 5M{id} để theo dõi hợp nhất
Định giá: Linh hoạt dựa trên thời gian trong ngày thông qua Pricing API
Giới hạn tốc độ: 50 yêu cầu mỗi giây trên mỗi địa chỉ IP
Chỉ nhóm nội bộ: Nếu các nhóm hết công suất, hãy thử lại sau một khoảng thời gian ngắn hoặc sử dụng endpoint 1 giờ để dự phòng

POST /apiv2/order5m ​

URL endpoint ​

Header yêu cầu ​

Body yêu cầu ​

Tham số yêu cầu ​

Thông tin nhà cung cấp ​

Ví dụ ​

cURL ​

Python ​

Phản hồi ​

Phản hồi thành công (200 OK) ​

Thành công kèm kích hoạt địa chỉ (200 OK) ​

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

Phản hồi lỗi ​

Số lượng Energy không hợp lệ (400) ​

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

Số dư không đủ (403) ​

Dịch vụ không khả dụng (503) ​

Lỗi máy chủ nội bộ (500) ​

Bảng tham chiếu mã lỗi ​

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

Header giới hạn tốc độ ​

Vượt quá giới hạn tốc độ (429) ​

Tính lũy quyền (Idempotency) ​

Cơ chế hoạt động của tính lũy quyền ​

Cung cấp khóa của riêng bạn ​

Đặt hai đơn hàng giống hệt nhau ​

Mã trạng thái HTTP cho các yêu cầu trùng lặp ​

Yêu cầu trùng lặp - Đã được xử lý (208) ​

Yêu cầu trùng lặp - Vẫn đang xử lý (409) ​

Các phương pháp hay nhất ​

So sánh: Đơn hàng 5 phút so với 1 giờ ​

Ghi chú ​

POST /apiv2/order5m

URL endpoint

Header yêu cầu

Body yêu cầu

Tham số yêu cầu

Thông tin nhà cung cấp

Ví dụ

cURL

Python

Phản hồi

Phản hồi thành công (200 OK)

Thành công kèm kích hoạt địa chỉ (200 OK)

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

Phản hồi lỗi

Số lượng Energy không hợp lệ (400)

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

Số dư không đủ (403)

Dịch vụ không khả dụng (503)

Lỗi máy chủ nội bộ (500)

Bảng tham chiếu mã lỗi

Giới hạn tốc độ

Header giới hạn tốc độ

Vượt quá giới hạn tốc độ (429)

Tính lũy quyền (Idempotency)

Cơ chế hoạt động của tính lũy quyền

Cung cấp khóa của riêng bạn

Đặt hai đơn hàng giống hệt nhau

Mã trạng thái HTTP cho các yêu cầu trùng lặp

Yêu cầu trùng lặp - Đã được xử lý (208)

Yêu cầu trùng lặp - Vẫn đang xử lý (409)

Các phương pháp hay nhất

So sánh: Đơn hàng 5 phút so với 1 giờ

Ghi chú