Cách tự động hóa việc thuê năng lượng TRON qua API
Nếu bạn vận hành một ví nóng, một engine rút tiền cho sàn, hay một hợp đồng phát giao dịch TRC-20 thay người dùng, bạn đã quen với nỗi khổ này: năng lượng TRON phải sẵn đúng lúc giao dịch được phát. Nạp năng lượng bằng tay qua giao diện không theo kịp quá vài giao dịch mỗi ngày; lỡ nhịp, giao dịch sẽ đốt TRX của địa chỉ gửi, thường đắt hơn hẳn năng lượng thuê trước.
Cách giải quyết là gọi API thuê ngay khi backend chuẩn bị phát giao dịch, để năng lượng được cấp bằng chương trình, không cần ai can thiệp.
API làm gì trên chuỗi
Mô hình tài nguyên của TRON tách phần tính toán (năng lượng) khỏi kích thước giao dịch (bandwidth). Một lệnh chuyển USDT TRC-20 tiêu chuẩn tiêu khoảng 65,000 năng lượng khi người nhận đã có USDT, và khoảng 130,000 khi số dư USDT của người nhận bằng không: lệnh chuyển đầu tiên trả chi phí lưu trữ để tạo mục số dư, nên chi phí phụ thuộc hoàn toàn vào người nhận chứ không phải người gửi. Bandwidth cho một giao dịch khoảng 345 byte, đủ nhỏ để hạn mức miễn phí hằng ngày của hầu hết tài khoản bù được.
Khi bạn gọi API thuê, dịch vụ stake TRX của chính mình và ủy quyền năng lượng sinh ra cho địa chỉ bạn chỉ định bằng DelegateResourceContract của Stake 2.0. Ủy quyền gắn với đúng địa chỉ đó và có thời hạn; hết hạn thuê, năng lượng tự động được thu về.
Việc thuê là bất đồng bộ. Lệnh gọi API trả về ngay với một orderId và trạng thái PAID_BY_USER, còn giao dịch ủy quyền trên chuỗi được phát ở nền và thường xác nhận trong vài giây. Hãy coi phản hồi đầu là xác nhận đơn đã được nhận và đã thanh toán, rồi hỏi endpoint chi tiết đơn hàng cho đến khi trạng thái chuyển sang ENERGY_DELEGATED.
Chọn thời hạn thuê
Tham số period nhận bốn giá trị: 1h, 1d, 3d, 30d. Giá đi theo thị trường năng lượng trên chuỗi và đổi trong ngày, nên con số hiện tại luôn nằm trên trang giá. Thứ tự thì ổn định: 1h rẻ nhất cho mỗi lần gọi, 30d rẻ nhất khi chia cho nhiều giao dịch từ cùng một địa chỉ.
Với hệ thống hướng sự kiện, mỗi giao dịch đi ra kéo theo một lần thuê, gói 1h gần như luôn đúng: bạn trả giá tuyệt đối thấp nhất và năng lượng được tiêu chỉ vài giây sau khi ủy quyền. Gói 1d và dài hơn hợp với các workload theo lô dự đoán được, chẳng hạn job chi trả hằng đêm, khi bạn muốn thuê một khối năng lượng lớn một lần thay vì gọi API hàng chục lần.
Nếu hệ thống đều đặn gửi hơn 20-30 giao dịch mỗi giờ từ cùng một địa chỉ, thuê một khối 1d tính đủ cho khối lượng dự kiến gọn hơn gọi theo từng giao dịch. Chi phí trả trước cao hơn, nhưng overhead của API và độ trễ xác nhận trên chuỗi biến mất khỏi đường nóng.
Xác thực và cấu trúc yêu cầu
Endpoint thuê:
GET https://api.tronenergyrent.com/place-energy-order
Một yêu cầu GET thuần với tham số truy vấn. Xác thực bằng tham số apiKey, tạo trong bảng điều khiển sau khi đăng ký và nạp tiền vào tài khoản. Không có xác thực qua header, không có body JSON.
Các tham số:
apiKey(bắt buộc): API key lấy từ bảng điều khiển.period(bắt buộc): thời hạn thuê, một trong1h,1d,3d,30d.energyAmount(bắt buộc): lượng năng lượng cần ủy quyền, tối thiểu15000. Với một lệnh chuyển USDT tiêu chuẩn tới người nhận đã có USDT,65000là mức an toàn; với lệnh chuyển đầu tiên tới người chưa từng giữ USDT, dùng130000.destinationAddress(bắt buộc): địa chỉ TRON (base58check, bắt đầu bằngT) sẽ nhận năng lượng.preActivateDestinationAddress(tùy chọn, mặc định0): đặt1nếu địa chỉ đích chưa từng nhận TRX, tức chưa được kích hoạt trên chuỗi. Dịch vụ sẽ gửi1.5 TRXtừ số dư trả trước của bạn để kích hoạt địa chỉ trước khi ủy quyền. Địa chỉ đã hoạt động thì để0cho khỏi tốn thêm.
Phản hồi luôn về với HTTP status 200, đơn thành công hay thất bại cũng vậy. Hãy rẽ nhánh theo trường status trong body JSON, không theo HTTP status. Body thành công:
{
"status": "SUCCESS",
"errorCode": null,
"errorDescription": null,
"requestId": "2651eacd-2428",
"payload": {
"orderId": "128de799-501e-44b2-8d6f-1fa825c2deed",
"totalPriceSun": 5662800,
"totalPriceTrx": 5.6628,
"state": "PAID_BY_USER"
}
}
Body lỗi có status: "ERROR", một errorCode cho máy đọc và một errorDescription cho người đọc:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
Luôn log requestId ở cả hai nhánh. Khi cần nhờ bộ phận hỗ trợ truy một lần thuê cụ thể, đó là ID họ sẽ tìm.
Vòng đời đơn hàng
Trường state trong payload đi qua một chuỗi cố định ngắn:
PAID_BY_USER: trạng thái đầu, đơn đã được thanh toán từ số dư của bạn nhưng chưa có gì diễn ra trên chuỗi.WAITING_DELEGATION: dịch vụ đã nhận đơn và đang chuẩn bị giao dịch ủy quyền.ENERGY_DELEGATED: giao dịch ủy quyền đã được xác nhận trên chuỗi. Địa chỉ đích đang giữ năng lượng thuê và dùng được cho giao dịch đi ra kế tiếp.ERROR_DELEGATION: ủy quyền thất bại. Hiếm, nhưng có thể xảy ra khi mạng tắc nặng.CANCELLED: đơn bị hủy, tiền hoàn về số dư của bạn.
Để xem trạng thái hiện tại:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
Phản hồi dùng cùng lớp vỏ status / errorCode / payload, với state hiện tại nằm trong payload. Hỏi endpoint này mỗi một hai giây sau khi đặt đơn và chỉ phát giao dịch TRC-20 khi đã thấy ENERGY_DELEGATED. Thực tế thường chỉ cần một hai lần hỏi.
Ví dụ Python chạy được
Dưới đây là một mẫu tối giản nhưng theo dáng production: đặt thuê, hỏi cho đến khi ủy quyền lên chuỗi, và báo lỗi rõ ràng khi có gì trục trặc.
import logging
import time
import requests
API_BASE = "https://api.tronenergyrent.com"
API_KEY = "your_api_key_here"
ENERGY_FOR_TRANSFER = 65_000 # use 130_000 if recipient has zero USDT balance
HTTP_TIMEOUT_SECS = 10
POLL_INTERVAL_SECS = 1
POLL_TIMEOUT_SECS = 30
def place_order(destination_address: str, period: str = "1h",
energy_amount: int = ENERGY_FOR_TRANSFER) -> dict:
resp = requests.get(
f"{API_BASE}/place-energy-order",
params={
"apiKey": API_KEY,
"period": period,
"energyAmount": energy_amount,
"destinationAddress": destination_address,
"preActivateDestinationAddress": 0,
},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"place-energy-order failed: {body.get('errorCode')} "
f"({body.get('errorDescription')}) requestId={body.get('requestId')}"
)
return body["payload"]
def wait_for_delegation(order_id: str) -> dict:
deadline = time.monotonic() + POLL_TIMEOUT_SECS
while time.monotonic() < deadline:
resp = requests.get(
f"{API_BASE}/single-order-details",
params={"apiKey": API_KEY, "orderId": order_id},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"single-order-details failed: {body.get('errorCode')} "
f"({body.get('errorDescription')})"
)
state = body["payload"]["state"]
if state == "ENERGY_DELEGATED":
return body["payload"]
if state == "ERROR_DELEGATION":
raise RuntimeError(f"Delegation failed for order {order_id}")
if state == "CANCELLED":
raise RuntimeError(f"Order {order_id} was cancelled")
time.sleep(POLL_INTERVAL_SECS)
raise TimeoutError(f"Order {order_id} did not reach ENERGY_DELEGATED in {POLL_TIMEOUT_SECS}s")
def rent_energy(destination_address: str) -> dict:
placed = place_order(destination_address)
logging.info(
"Order placed: id=%s priceSun=%s priceTrx=%s",
placed["orderId"], placed["totalPriceSun"], placed["totalPriceTrx"],
)
delegated = wait_for_delegation(placed["orderId"])
logging.info("Order delegated: id=%s", delegated["orderId"])
return delegated
Vài điểm đáng nói. Kiểm tra tường minh status == "SUCCESS" là bắt buộc vì HTTP status luôn là 200, nên riêng resp.raise_for_status() không nói gì về kết quả thật. Vòng hỏi có timeout cứng để một đơn kẹt không chặn luồng chuyển tiền của bạn vô hạn. Rẽ nhánh theo state xử lý rõ ba kết cục (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) thay vì một kiểu “không thành công” chung chung.
Trong luồng chuyển tiền, gọi rent_energy() trước, rồi mới phát giao dịch TRC-20. Thứ tự này quan trọng: phát trước thì giao dịch đốt TRX của người gửi, vì ủy quyền chưa được xác nhận.
Giữ số dư trả trước đủ dùng
Chi phí thuê trừ từ số dư trả trước trong tài khoản tronenergyrent.com của bạn. Hãy đặt cảnh báo hoặc nạp tự động khi số dư xuống dưới một ngưỡng; một mức sàn hợp lý là đủ cho hai giờ khối lượng cao điểm. Để đọc số dư bằng chương trình:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
Payload gồm số dư hiện tại và trạng thái tài khoản. Nối nó vào hệ giám sát và bạn sẽ không bao giờ bị hết số dư bất ngờ lúc 2 giờ sáng. Mức nạp tối thiểu vào số dư tronenergyrent.com là 10 TRX.
Xử lý lỗi trong thực tế
Ba kiểu lỗi gặp nhiều nhất trong production. Các mã dưới đây là mã thật của API, rẽ nhánh theo chúng là an toàn.
INSUFFICIENT_BALANCE: số dư trả trước không đủ cho lần thuê cộng chi phí kích hoạt trước nếu có. Đừng thử lại, thử lại không sửa được gì. Bắt riêng lỗi này và chạy luồng cảnh báo hoặc nạp tiền, kèmrequestIdtrong payload cảnh báo.INVALID_ADDRESS:destinationAddresskhông qua được bước giải mã base58check phía server. Nếu hệ thống của bạn dựng địa chỉ động, chẳng hạn từ dữ liệu người dùng nhập, hãy kiểm tra cục bộ trước khi gọi API. Thư viện Pythontronpycóis_address()cho việc này; loại dữ liệu xấu ở phía client nhanh hơn nhiều so với chờ một vòng round trip.INACTIVE_DESTINATION_ADDRESS_ERROR: địa chỉ đích chưa từng được kích hoạt trên chuỗi và bạn không yêu cầu dịch vụ kích hoạt. Khắc phục bằng cách nạp trước một ít TRX vào địa chỉ từ nơi khác, hoặc truyềnpreActivateDestinationAddress=1ở lần gọi tiếp theo để dịch vụ kích hoạt với1.5 TRX.
Một trường hợp tinh tế hơn: ORDER_IS_ALREADY_IN_PROGRESS có thể trả về khi nhiều worker đặt thuê cho cùng một đích cùng lúc. Lỗi này sửa ở phía tiến trình, không phải phía API: đặt một khóa phân tán (Redis là đủ) theo địa chỉ đích và giữ cho đến khi ủy quyền hoàn tất.
Kiểm chứng trên chuỗi
Với hầu hết tích hợp, hỏi /single-order-details đến khi ENERGY_DELEGATED là đủ. Muốn chắc hơn, bạn có thể hỏi thẳng full node TRON sau khi ủy quyền được xác nhận:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
Phản hồi chứa trạng thái tài nguyên hiện tại của địa chỉ, gồm cả năng lượng được các địa chỉ khác ủy quyền cho nó. Tên trường chính xác tùy view Stake 2.0 hiện hành, nên hãy đối chiếu tài liệu TRON HTTP API khi nối phần này vào hệ thống. Dùng như một bước kiểm tra mềm chỉ ghi cảnh báo thay vì chặn chuyển tiền, nó là tín hiệu sớm hữu ích cho trường hợp hiếm hoi khi có gì đó lệch ở phía sau API thuê, và tiết kiệm cho bạn hàng giờ debug vào cái lần duy nhất mà đơn thuê trông thành công trong API nhưng trên chuỗi lại khác.