APIでTRONエネルギーのレンタルを自動化する
なぜエネルギーのレンタルを自動化するのか
ホットウォレット、取引所の出金エンジン、ユーザーの代わりにTRC-20送金を実行するコントラクトを運用しているなら、痛みはすでにご存じでしょう。トランザクションが発火する瞬間にTRONのエネルギーが用意されていなければならず、UIから手でエネルギーをチャージする方法は1日数件を超えると破綻します。タイミングを逃すと送信元アドレスのTRXが燃やされ、たいていは前もってレンタルするよりずっと高くつきます。
解決策は、バックエンドがトランザクションをブロードキャストする直前にレンタルAPIを呼び、人手を介さずにエネルギーを用意することです。
APIがオンチェーンで行うこと
コードを書く前に仕組みを押さえておくと、手探りのデバッグをせずに済みます。
TRONのリソースモデルは、計算(エネルギー)とトランザクションのサイズ(bandwidth)を分けています。標準的なUSDT TRC-20送金は、受取側がすでにUSDTを持っていれば約65,000 エネルギー、受取側のUSDT残高がゼロなら約130,000を消費します。最初の受け取りで残高エントリを作るストレージコストがかかるため、コストは送信側ではなく完全に受取側で決まります。bandwidthは送金1件あたり約345バイトで、多くのアカウントでは日々の無料枠に収まります。
レンタルAPIを呼ぶと、サービスは自分のTRXをステーキングし、Stake 2.0のDelegateResourceContractで指定されたアドレスへエネルギーを委任します。委任はアドレスごと、期間限定で、レンタル期間が終わるとエネルギーは自動的にサービス側へ戻ります。
重要なのは、レンタルが非同期だという点です。APIはすぐにorderIdとPAID_BY_USERのstateを返しますが、オンチェーンの委任トランザクションはバックグラウンドでブロードキャストされ、通常は数秒で確定します。組み込む側では、最初のレスポンスは注文が受理され支払われた確認とみなし、その後stateがENERGY_DELEGATEDになるまで注文詳細のエンドポイントをポーリングします。
レンタル期間の選び方
APIのperiodパラメータが受け付ける値は1h、1d、3d、30dの4つです。料金はオンチェーンのエネルギー市場に連動して1日の中でも動くので、最新の数値は料金ページにあります。相対的な順序は安定していて、1hは1回あたりが最も安く、30dは同じアドレスからの多数の送金で按分すると最も安くなります。
送金1件ごとにレンタルを1回起動するイベント駆動のシステムなら、ほぼ常に1hが正解です。絶対額が最も低く、エネルギーは委任から数秒以内に消費されます。1d以上は、夜間の支払いジョブのように予測できるバッチを回していて、APIを何十回も呼ぶ代わりに大きなエネルギーのブロックを一度にレンタルしたい場合に向いています。
同じアドレスから1時間に20件から30件を超える送金が続くシステムでは、想定量を賄うサイズの1dブロックをレンタルするほうが、送金ごとに呼ぶよりすっきりします。初期コストは上がりますが、APIのオーバーヘッドとオンチェーン確定の待ち時間がホットパスから消えます。
認証とリクエストの構造
レンタルのエンドポイントは次のとおりです。
GET https://api.tronenergyrent.com/place-energy-order
クエリパラメータ付きの素朴なGETリクエストです。認証はapiKeyクエリパラメータで行い、キーは登録と入金の後にダッシュボードで生成します。ヘッダー認証もJSONのリクエストボディもありません。
パラメータは次のとおりです。
apiKey(必須):ダッシュボードで取得したAPIキー。period(必須):レンタル期間。1h、1d、3d、30dのいずれか。energyAmount(必須):委任するエネルギー量。最小値は15000。すでにUSDTを持つ受取側への標準的なUSDT送金1件なら65000が安全な値で、USDTを初めて受け取る相手への送金には130000を使います。destinationAddress(必須):委任されたエネルギーを受け取るTRONアドレス(base58check形式、Tで始まります)。preActivateDestinationAddress(任意、デフォルト0):宛先アドレスがTRXを一度も受け取っておらず、オンチェーンでアクティベートされていない場合に1にします。サービスはエネルギーを委任する前に、アカウント残高から1.5 TRXを送ってアドレスをアクティベートします。すでにアクティブなアドレスなら、余分な費用を避けるため0のままにしてください。
レスポンスは注文の成否にかかわらず常にHTTPステータス200です。HTTPステータスではなく、JSONボディのstatusフィールドで分岐してください。成功時のボディは次の形です。
{
"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"
}
}
エラー時のボディにはstatus: "ERROR"、機械可読のerrorCode、人間向けのerrorDescriptionが入ります。
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
どちらの場合もrequestIdを必ずログに残してください。特定のレンタルをサポートに追ってもらうとき、検索に使われるのがこのIDです。
注文のライフサイクル
payload内のstateは、決まった短い順序で遷移します。
PAID_BY_USER:初期状態。注文は残高から支払われましたが、オンチェーンでは何も起きていません。WAITING_DELEGATION:サービスが注文を取り上げ、委任トランザクションを準備しています。ENERGY_DELEGATED:委任トランザクションがオンチェーンで確定しました。宛先アドレスはレンタルしたエネルギーを持っていて、次の送信トランザクションで使えます。ERROR_DELEGATION:何らかの理由で委任に失敗しました。まれですが、ネットワークが激しく混雑しているときに起こり得ます。CANCELLED:注文がキャンセルされ、資金は残高に戻りました。
現在の状態は次で確認します。
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
レスポンスは同じstatus / errorCode / payloadのエンベロープで、現在のstateはpayloadの中にあります。注文を出したらこれを1秒か2秒ごとにポーリングし、ENERGY_DELEGATEDを確認してからTRC-20送金に進んでください。実運用ではたいてい1回か2回のポーリングで済みます。
Pythonでの実装例
最小限ながら本番を想定した形です。レンタルを発注し、委任がオンチェーンに乗るまでポーリングし、問題があれば明確なエラーを出します。
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
いくつか補足します。HTTPステータスは常に200なので、resp.raise_for_status()だけでは結果は何も分かりません。だからstatus == "SUCCESS"の明示的なチェックが要ります。ポーリングループにはハードタイムアウトがあり、詰まった注文が送金パイプラインを無期限に止めることはありません。stateでの分岐は、漠然とした「成功ではない」に頼らず、3つの終端状態(ENERGY_DELEGATED、ERROR_DELEGATION、CANCELLED)を明示的に扱います。
送金のワークフローでは、まずrent_energy()を呼び、その後でTRC-20送金をブロードキャストしてください。順序が大事です。先にブロードキャストすると、委任がまだ確定していないので送信側のTRXが燃やされます。
アカウント残高の目安
レンタル料金は、tronenergyrent.comのアカウントに入金してある残高から差し引かれます。残高がしきい値を下回ったらアラートか自動チャージが走るようにしてください。妥当な下限は、ピーク時の2時間分の量を賄える金額です。
現在の残高をプログラムから読むには次を呼びます。
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
payloadには現在の残高とアカウントの状態が入ります。監視スタックに組み込んでおけば、午前2時に残高が尽きていて驚くことはありません。なお、tronenergyrent.comの残高への最低入金額は10 TRXです。
実運用でのエラー処理
本番でよく出る失敗は3つです。以下のエラーコードは実際のAPIが返すもので、安全に分岐に使えます。
INSUFFICIENT_BALANCE:アカウント残高が、要求したレンタルと事前アクティベート分を賄うには足りません。リトライしても解決しないので、明示的にキャッチしてアラートかチャージのフローを起動し、アラートのpayloadにrequestIdを含めてください。INVALID_ADDRESS:destinationAddressがサーバー側のbase58checkデコードに失敗しました。ユーザー入力からアドレスを組み立てるシステムなら、APIを呼ぶ前にローカルで検証してください。Pythonのtronpyにはis_address()があります。不正な入力をクライアント側で弾くほうが、往復を待つより速いです。INACTIVE_DESTINATION_ADDRESS_ERROR:宛先アドレスがオンチェーンで一度もアクティベートされておらず、サービスにアクティベートを依頼してもいません。別の場所から少額のTRXをそのアドレスへ先に送るか、次の呼び出しでpreActivateDestinationAddress=1を渡してサービスに1.5 TRXでアクティベートさせてください。
もう少し微妙なのがORDER_IS_ALREADY_IN_PROGRESSで、同じ宛先に対して複数のワーカーが同時にレンタルを発注すると返ることがあります。直すのはAPI側ではなくプロセス側です。宛先アドレスをキーにした分散ロック(Redisで十分です)を取り、委任が完了するまで保持してください。
オンチェーンでの検証
ほとんどの統合では、/single-order-detailsをENERGY_DELEGATEDまでポーリングすれば十分です。念を入れるなら、委任の確定後にTRONのフルノードへ直接問い合わせることもできます。
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
レスポンスにはそのアドレスの現在のリソース状態が含まれ、外部アドレスから委任されたエネルギーも入っています。正確なフィールド名は現行のStake 2.0のビューに依存するので、組み込むときは最新のTRON HTTP APIドキュメントを参照してください。送金を止めずに警告ログだけ出すソフトチェックにしておけば、APIではレンタルが成功して見えるのにオンチェーンの何かがずれているという年に一度あるかどうかの場面で、何時間ものデバッグを省いてくれます。