Tích hợp API v2 để báo giá, tạo và theo dõi các đơn đặt hàng cho thuê TRON Energy theo chương trình. Thanh toán trực tuyến hoặc từ số dư TronBid của bạn và giảm TRX bị đốt cháy bởi các lệnh gọi hợp đồng thông minh.
API thuê nhanh là một cách để thuê TRON Energy một cách tự động mà không cần thực hiện thủ công. Energy giúp việc chuyển USDT (TRC-20) và các cuộc gọi hợp đồng thông minh khác rẻ hơn so với việc đốt TRX.
Nói một cách dễ hiểu: chương trình của bạn (trang web, bot hoặc dịch vụ) tự mua năng lượng, chính xác khi cần — ví dụ: trước mỗi lần chuyển USDT mà khách hàng của bạn thực hiện.
Hãy nghĩ về một máy bán hàng tự động: bạn kiểm tra giá, nhét tiền, lấy món hàng của mình. API là cùng một bộ nút - chỉ có chương trình của bạn nhấn chúng.
Chương trình của bạn hỏi API hiện tại gói năng lượng cần thiết có giá bao nhiêu.
Chương trình của bạn tạo một đơn đặt hàng và thanh toán đơn đặt hàng đó — bằng cách gửi TRX đến địa chỉ đã cho hoặc bằng cách tính phí số dư TronBid của bạn.
Trong vòng vài giây, năng lượng sẽ xuất hiện trên ví mục tiêu và USDT có thể được gửi với giá rẻ hơn.
Quan trọng: API là công cụ dành cho nhà phát triển. Để sử dụng nó, ai đó phải viết mã gửi yêu cầu.
Nếu không có ai viết mã - hãy sử dụng giao dịch mua năng lượng làm sẵn trên trang web (Thuê nhanh) hoặc bot Telegram @tronbid. Kết quả tương tự, chỉ được thực hiện thủ công.
Một ví dụ đầy đủ từ đầu đến cuối về kịch bản đơn giản nhất (trên chuỗi). Bốn bước và năng lượng có trên ví.
Dưới đây là những gì xảy ra ở mỗi bước và những gì API trả về. Cắm khóa API, địa chỉ và id đơn hàng của bạn.
Gửi lượng năng lượng và thời lượng. Bạn nhận lại price_trx và nó bị khóa trong bao nhiêu giây.
Gửi gói, idempotency_key và payer_address của bạn. Bạn nhận được pay_address (thanh toán ở đâu), money_trx (bao nhiêu) và Expires_at (cho đến khi nào).
Gửi chính xác số tiền_trx TRX đến pay_address từ payer_address của bạn. Đó là một giao dịch chuyển TRON đơn giản.
Thăm dò trạng thái vài giây một lần cho đến khi nó được ủy quyền. Điều đó có nghĩa là năng lượng được giao cho ví — xong.
{
"price_trx": "3.200000",
"available": true,
"save_percent": 62,
"expires_in_sec": 30
}{
"id": "uuid",
"status": "pending_payment",
"payment_mode": "onchain",
"pay_address": "TDeposit...",
"amount_trx": "3.200000",
"energy_amount": 131000,
"duration_minutes": 15,
"expires_at": "2026-04-29T13:15:00.000Z",
"qr_payload": "tron:TDeposit...?amount=3.200000",
"duplicate": false,
"target_address": "TTarget..."
}# poll every 3s until the order is done
while true; do
STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
-H "Authorization: Bearer $API_KEY" | jq -r .status)
echo "status: $STATUS"
case "$STATUS" in
delegated|failed|expired|cancelled) break ;;
esac
sleep 3
done{
"id": "uuid",
"status": "delegated",
"payment_mode": "onchain",
"amount_trx": "3.200000",
"energy_amount": 131000,
"effective_energy_amount": 131000,
"duration_minutes": 15,
"pay_address": "TDeposit...",
"payer_address": "TPayer...",
"target_address": "TTarget...",
"error_code": null,
"error_message": null
}Giải thích ngắn gọn về các từ được sử dụng trong tài liệu này.
Những gì cần chuẩn bị trước khi thực hiện yêu cầu đầu tiên của bạn.
Nhắn tin @tronbid trên Telegram - bạn sẽ nhận được khóa liên kết với tài khoản TronBid của mình. Yêu cầu sẽ không vượt qua nếu không có nó.
Quyết định địa chỉ (target_address) cần năng lượng. Thông thường, đó là ví mà khách hàng của bạn gửi USDT từ đó.
Năng lượng được bán theo gói (thường là 65000 hoặc 131000 năng lượng trong 15 hoặc 60 phút). Nhận danh sách trực tiếp từ điểm cuối danh mục, không cần xác thực.
Đối với trên chuỗi — một ví có TRX để thanh toán. Để thanh toán số dư - tài khoản TronBid được nạp tiền và bật chế độ số dư.
API thuê nhanh cho phép dịch vụ của bạn tự động thuê TRON Energy, do đó, việc chuyển USDT TRC-20 và các cuộc gọi hợp đồng thông minh khác có chi phí thấp hơn so với việc đốt TRX.
Tất cả các điểm cuối đều chia sẻ một URL cơ sở.
https://tronbid.com/api/v2/quick-rentCó hai cách để thanh toán cho một đơn đặt hàng. Trên chuỗi là mặc định và không cần thiết lập. Thanh toán số dư là tùy chọn và phải được kích hoạt cho khóa của bạn.
Nếu không kích hoạt, yêu cầu có Payment_mode: số dư sẽ trả về 403 BALANCE_PAYMENT_NOT_ENABLED. Để kích hoạt nó, hãy liên hệ với bộ phận hỗ trợ TronBid.
| Mode | Cách kích hoạt | Thanh toán |
|---|---|---|
on-chain | Mặc định — bỏ qua Payment_mode (hoặc "onchain") | Gửi TRX đến pay_address từ payer_address |
balance | Payment_mode: số dư + kích hoạt cho khóa của bạn | Được ghi nợ từ số dư TRX TronBid của bạn |
lượng năng lượng và thời lượng_phút phải khớp với gói Thuê nhanh đang hoạt động — thường là 65000 hoặc 131000 năng lượng và 15 hoặc 60 phút.
Tìm nạp danh mục hiện tại bất kỳ lúc nào (không cần xác thực):
curl -sS https://tronbid.com/api/public/quick-rent/skusBước 1 - ĐĂNG /báo giá để tìm hiểu giá. Bước 2 — ĐĂNG /đơn đặt hàng để tạo đơn hàng và nhận pay_address, money_trx và Expires_at. Bước 3 — gửi chính xác số tiền_trx TRX đến pay_address từ payer_address của bạn. Bước 4 - thăm dò GET /orders/:id cho đến khi trạng thái được ủy quyền (hoặc không thành công/hết hạn/bị hủy).
target_address là tùy chọn - nếu bị bỏ qua, năng lượng sẽ được ủy quyền cho payer_address.
Mỗi lần chỉ được phép có một đơn hàng mở trên chuỗi (pending_ Payment) cho mỗi payer_address; nếu không bạn sẽ nhận được 409 PENDING_PAYMENT_INTENT_EXISTS. Khi thanh toán thiếu/thừa, năng lượng cuối cùng có thể khác nhau — hãy kiểm tra hiệu quả_energy_amount trong GET /orders/:id.
{
"energy_amount": 131000,
"duration_minutes": 15,
"idempotency_key": "your-unique-key-001",
"payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
"target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}{
"id": "uuid",
"status": "pending_payment",
"payment_mode": "onchain",
"pay_address": "TDeposit...",
"amount_trx": "3.200000",
"energy_amount": 131000,
"duration_minutes": 15,
"expires_at": "2026-04-29T13:15:00.000Z",
"qr_payload": "tron:TDeposit...?amount=3.200000",
"duplicate": false,
"target_address": "TTarget..."
}Bước 1 — NHẬN/số dư để kiểm tra TRX của bạn. Bước 2 - ĐĂNG /báo giá. Bước 3 — ĐĂNG /đơn đặt hàng với Payment_mode: số dư để ghi nợ và bắt đầu ủy quyền. Bước 4 — thăm dò GET /orders/:id cho đến khi được ủy quyền (do lỗi ủy quyền, nó sẽ không thành công và TRX được hoàn trả vào số dư của bạn).
payer_address không cần thiết — tài khoản được liên kết với khóa API của bạn sẽ thanh toán. Lượng năng lượng trong phản hồi có thể cao hơn SKU đã đặt hàng (phần thưởng ma trận giá).
{
"energy_amount": 131000,
"duration_minutes": 15,
"idempotency_key": "your-unique-key-balance-001",
"payment_mode": "balance",
"target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}{
"id": "uuid",
"status": "delegating",
"payment_mode": "balance",
"pay_address": null,
"amount_trx": "3.200000",
"energy_amount": 132310,
"duration_minutes": 15,
"expires_at": null,
"qr_payload": null,
"duplicate": false,
"target_address": "TTarget..."
}Mọi đơn hàng đều chuyển qua các trạng thái này. Thăm dò GET /orders/:id để theo dõi nó.
| Status | Ý nghĩa |
|---|---|
pending_payment | Đang chờ thanh toán trên chuỗi |
delegating | Thanh toán đã nhận hoặc số dư đã tính phí; đang tiến hành phái đoàn |
delegated | Năng lượng được ủy thác |
cancelled | Đã hủy trước khi thanh toán (trên chuỗi) |
expired | Thời hạn thanh toán trực tuyến đã trôi qua |
failed | Lỗi (đối với số dư, TRX được hoàn lại) |
idempotency_key (8–128 ký tự) là id đơn hàng duy nhất về phía bạn. Việc lặp lại POST /orders với cùng một khóa (cho cùng một ứng dụng khách API) sẽ trả về cùng một thứ tự với "trùng lặp": true.
Không sử dụng lại một idempotency_key trên các phương thức thanh toán khác nhau (onchain so với số dư) — trả về 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.
Ước tính lượng năng lượng mà một địa chỉ cần để chuyển. Chuyển ví người nhận và xem nó đã giữ USDT chưa.
/api/v2/quick-rent/calculator| tham số | Type | Mô tả | Example |
|---|---|---|---|
ví_địa chỉ | string | Địa chỉ TRON để phân tích | TXXXXXXXX...XXXX |
has_usdt | boolean | null | Liệu người nhận đã nắm giữ USDT hay chưa (ảnh hưởng đến năng lượng) hay không. đúng, sai hoặc bỏ qua. | true |
{
"wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"has_usdt": true
}curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'Trả về giá hiện tại của một gói: price_trx, tình trạng còn hàng, save_percent và thời gian báo giá có hiệu lực (expires_in_sec).
/api/v2/quick-rent/quote| tham số | Type | Mô tả | Example |
|---|---|---|---|
năng lượng_số lượng | int | Lượng năng lượng từ danh mục hoạt động | 131000 |
thời lượng_phút | int | Thời gian thuê từ danh mục | 15 |
{
"price_trx": "3.200000",
"available": true,
"save_percent": 62,
"expires_in_sec": 30
}export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"
curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"energy_amount":131000,"duration_minutes":15}'Tạo một đơn đặt hàng cho thuê. Đối với trên chuỗi, chuyển payer_address và thanh toán số tiền_trx được trả lại cho pay_address. Đối với số dư, hãy thêm Payment_mode: số dư và tài khoản được liên kết sẽ được tính phí ngay lập tức.
target_address là tùy chọn (mặc định là payer_address). Hãy lưu ý 409 quy tắc: một đơn hàng mở trên chuỗi cho mỗi người trả tiền và không có ủy quyền Thuê nhanh nào đang hoạt động trên mục tiêu (ACTIVE_DELEGATION_EXISTS).
/api/v2/quick-rent/orders| tham số | Type | Mô tả | Example |
|---|---|---|---|
năng lượng_số lượng | int | Lượng năng lượng từ danh mục | 131000 |
thời lượng_phút | int | Thời gian thuê từ danh mục | 15 |
idempotency_key | string | Id đơn hàng duy nhất của bạn (8–128 ký tự) | partner-onchain-001 |
chế độ thanh toán | string | Tùy chọn. "onchain" (mặc định) hoặc "cân bằng". | balance |
người trả tiền_địa chỉ | string | Trên chuỗi: ví gửi TRX. Không cần thiết cho sự cân bằng. | TPayer... |
target_address | string | Tùy chọn. Ví nhận năng lượng (mặc định là payer_address). | TTarget... |
{
"id": "uuid",
"status": "pending_payment",
"payment_mode": "onchain",
"pay_address": "TDeposit...",
"amount_trx": "3.200000",
"energy_amount": 131000,
"duration_minutes": 15,
"expires_at": "2026-04-29T13:15:00.000Z",
"qr_payload": "tron:TDeposit...?amount=3.200000",
"duplicate": false,
"target_address": "TTarget..."
}{
"id": "uuid",
"status": "delegating",
"payment_mode": "balance",
"pay_address": null,
"amount_trx": "3.200000",
"energy_amount": 132310,
"duration_minutes": 15,
"expires_at": null,
"qr_payload": null,
"duplicate": false,
"target_address": "TTarget..."
}curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"energy_amount": 131000,
"duration_minutes": 15,
"idempotency_key": "partner-onchain-001",
"payer_address": "TPayer...",
"target_address": "TTarget..."
}'curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"energy_amount": 131000,
"duration_minutes": 15,
"idempotency_key": "partner-balance-001",
"payment_mode": "balance",
"target_address": "TTarget..."
}'Trả về trạng thái hiện tại, chế độ thanh toán, số tiền, địa chỉ và error_code / error_message nếu có lỗi xảy ra. hiệu quả_energy_amount phản ánh năng lượng được ủy quyền thực tế sau khi thanh toán thiếu/thừa.
/api/v2/quick-rent/orders/:id| tham số | Type | Mô tả | Example |
|---|---|---|---|
mã số | string | Id đơn hàng (tham số đường dẫn) | uuid |
{
"id": "uuid",
"status": "delegated",
"payment_mode": "onchain",
"amount_trx": "3.200000",
"energy_amount": 131000,
"effective_energy_amount": 131000,
"duration_minutes": 15,
"pay_address": "TDeposit...",
"payer_address": "TPayer...",
"target_address": "TTarget...",
"error_code": null,
"error_message": null
}curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
-H "Authorization: Bearer $API_KEY"Hủy đơn hàng vẫn đang chờ xử lý_thanh toán (chỉ trên chuỗi). Khi năng lượng đã được ủy quyền, đơn hàng sẽ không thể bị hủy nữa.
/api/v2/quick-rent/orders/:id/cancel| tham số | Type | Mô tả | Example |
|---|---|---|---|
mã số | string | Id đơn hàng (tham số đường dẫn) | uuid |
curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
-H "Authorization: Bearer $API_KEY"Thay đổi ví thanh toán cho đơn hàng đang chờ xử lý thanh toán trên chuỗi — hữu ích nếu khách hàng quyết định thanh toán từ một ví khác trước khi gửi TRX.
/api/v2/quick-rent/orders/:id/set-payer| tham số | Type | Mô tả | Example |
|---|---|---|---|
mã số | string | Id đơn hàng (tham số đường dẫn) | uuid |
người trả tiền_địa chỉ | string | Ví thanh toán mới | TNewPayer... |
curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"payer_address":"TNewPayer..."}'Trả về số dư TRX của tài khoản TronBid được liên kết với khóa API của bạn (số dư trong ứng dụng của bạn, không phải ví trên chuỗi). Yêu cầu tiêu đề Ủy quyền.
/api/v2/quick-rent/balance{ "balance_trx": "150.500000" }curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
-H "Authorization: Bearer $API_KEY"Lỗi trả về trạng thái HTTP và trường lỗi. Dưới đây là những người bạn có thể gặp phải.
| HTTP | error | Khi nào |
|---|---|---|
| 400 | Invalid body | JSON hoặc trường không hợp lệ |
| 400 | INVALID_SKU / SKU_INACTIVE | Gói không có sẵn |
| 400 | INVALID_PAYER_ADDRESS / INVALID_TARGET_ADDRESS | Địa chỉ TRON không đúng định dạng |
| 400 | INSUFFICIENT_BALANCE | Không đủ TRX trên số dư (chế độ cân bằng) |
| 401 | Unauthorized | Khóa API bị thiếu hoặc không hợp lệ |
| 403 | BALANCE_PAYMENT_NOT_ENABLED | Thanh toán số dư chưa được kích hoạt cho khóa của bạn |
| 409 | PENDING_PAYMENT_INTENT_EXISTS | Đã tồn tại một đơn hàng mở trên chuỗi cho người trả tiền này |
| 409 | ACTIVE_DELEGATION_EXISTS | Mục tiêu đã có ủy quyền Thuê nhanh đang hoạt động |
| 409 | POOL_ENERGY_INSUFFICIENT | Hiện tại không có năng lượng hồ bơi miễn phí |
| 409 | IDEMPOTENCY_PAYMENT_MODE_MISMATCH | Cùng một idempotency_key nhưng có chế độ thanh toán khác |
| 429 | Too Many Requests | Giới hạn tỷ lệ |
| 503 | — | Dịch vụ tạm thời không khả dụng, hãy thử lại sau |
Những tình huống thường gặp và những việc cần làm, nói một cách dễ hiểu.
Đảm bảo số tiền được chuyển chính xác bằng money_trx và số tiền được chuyển đến pay_address từ địa chỉ payer_address chính xác. Việc chuyển tiền phải đến trước khi hết hạn_at. Trạng thái thường cập nhật trong vòng một phút sau khi xác nhận mạng — tiếp tục bỏ phiếu GET /orders/:id.
Phái đoàn không thành công. Đối với các khoản thanh toán số dư, TRX sẽ tự động được trả về số dư của bạn. Lý do là ở error_code và error_message của GET /orders/:id. Bạn có thể tạo một đơn đặt hàng mới.
Payer_address này đã có một đơn hàng trên chuỗi chưa thanh toán. Thanh toán, đợi cho đến khi hết hạn (expires_at) hoặc hủy qua /orders/:id/cancel, sau đó tạo một cái mới.
Thanh toán số dư không được kích hoạt cho khóa của bạn. Liên hệ với bộ phận hỗ trợ TronBid để kích hoạt nó hoặc sử dụng trên chuỗi (mặc định).
Quá nhiều yêu cầu trong một thời gian ngắn. Giảm tần suất thăm dò (ví dụ: 3 giây một lần) và thử lại sau.
Với việc thanh toán thiếu/thanh toán vượt mức trên chuỗi, số tiền cuối cùng sẽ thay đổi. Kiểm tra hiệu quả_energy_amount trong GET /orders/:id — đó là năng lượng thực sự được ủy quyền.
Cần quyền truy cập API, giới hạn cao hơn hoặc kích hoạt thanh toán số dư? Hãy liên hệ và chúng tôi sẽ giúp đỡ.