API로 TRON 에너지 임대 자동화하기

2026-05-13

에너지 임대를 자동화해야 하는 이유

핫월렛이나 거래소 출금 엔진, 사용자를 대신해 TRC-20 전송을 일으키는 컨트랙트를 운영한다면 이미 겪어 본 문제일 것입니다. 트랜잭션이 나가는 바로 그 순간에 TRON 에너지가 준비되어 있어야 합니다. UI에서 손으로 에너지를 채우는 방식은 하루 몇 건을 넘기면 감당이 안 되고, 타이밍을 놓치면 트랜잭션은 발신 주소의 TRX를 소각하는데, 이는 미리 임대한 에너지보다 훨씬 비쌉니다.

해법은 백엔드가 트랜잭션을 브로드캐스트하기 직전에 임대 API를 호출해 사람 손을 거치지 않고 에너지를 받는 것입니다.

이 API가 온체인에서 하는 일

코드를 쓰기 전에 온체인 메커니즘을 알아 두면 디버깅을 더듬거리며 하지 않게 됩니다.

TRON의 리소스 모델은 연산(에너지)과 트랜잭션 크기(bandwidth)를 분리합니다. 표준 USDT TRC-20 전송은 수신자가 이미 USDT를 보유하면 약 65,000 에너지, 수신자의 USDT 잔액이 0이면 약 130,000 에너지를 소비합니다. 첫 입금 전송이 잔액 항목을 만드는 저장 비용을 치르기 때문에, 비용은 전적으로 수신자에게 달려 있고 발신자와는 무관합니다. 전송 한 건의 bandwidth는 약 345 바이트로, 대부분의 계정에서 일일 무료 한도로 덮을 수 있을 만큼 작습니다.

임대 API를 호출하면 서비스는 자체 TRX를 스테이킹하고 Stake 2.0의 DelegateResourceContract로 거기서 나온 에너지를 지정한 주소에 위임합니다. 위임은 주소 단위이고 기한이 있어서, 임대 기간이 끝나면 에너지는 서비스로 자동 회수됩니다.

중요한 세부 사항 하나는 임대가 비동기라는 점입니다. API 호출은 orderId와 PAID_BY_USER 상태를 담아 즉시 돌아오지만, 온체인 위임 트랜잭션은 백그라운드에서 브로드캐스트되어 보통 몇 초 안에 확정됩니다. 연동할 때는 첫 응답을 주문이 접수되고 결제되었다는 확인으로만 다루고, 주문 상세 엔드포인트를 폴링해 상태가 ENERGY_DELEGATED로 바뀌기를 기다려야 합니다.

임대 기간 고르기

period 파라미터는 1h, 1d, 3d, 30d 네 값을 받습니다. 가격은 온체인 에너지 시장에 따라 움직이고 하루 안에서도 달라지므로 실시간 수치는 늘 가격 페이지에 있습니다. 상대적 순서는 안정적입니다. 호출당 비용은 1h가 가장 싸고, 같은 주소에서 많은 전송에 비용을 분산할 때는 30d가 가장 싸집니다.

나가는 전송 한 건마다 임대 한 번을 일으키는 이벤트 기반 시스템에서는 거의 언제나 1h 등급이 정답입니다. 절대 비용이 가장 낮고, 위임된 에너지는 몇 초 안에 소비됩니다. 1d 이상 등급은 예측 가능한 배치 작업을 돌릴 때 의미가 있습니다. 예를 들어 야간 일괄 지급 작업에서 API를 수십 번 호출하는 대신 큰 에너지 블록을 한 번에 임대하고 싶을 때입니다.

같은 주소에서 시간당 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 전송 한 건에는 65000이 안전한 값이고, USDT를 처음 받는 수신자에게 보내는 첫 전송에는 130000을 쓰십시오.
  • destinationAddress(필수): 위임된 에너지를 받을 TRON 주소(T로 시작하는 base58check 형식).
  • 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 전송을 진행하십시오. 실제로는 한두 번의 폴링으로 보통 충분합니다.

동작하는 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 분기는 막연한 "성공 아님"에 기대지 않고 세 가지 최종 결과(ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED)를 각각 처리합니다.

전송 워크플로에서는 먼저 rent_energy()를 호출한 다음 TRC-20 전송을 브로드캐스트하십시오. 순서가 중요합니다. 먼저 브로드캐스트하면 위임이 아직 확정되지 않은 상태라 트랜잭션이 발신자의 TRX를 소각합니다.

선불 잔액 관리

임대 비용은 tronenergyrent.com 계정의 선불 잔액에서 차감됩니다. 잔액이 임계값 아래로 내려가면 알림을 보내거나 자동 충전을 설정하십시오. 피크 두 시간 분량을 덮는 정도가 합리적인 하한선입니다.

현재 잔액을 프로그램으로 조회하려면 다음을 호출합니다.

GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY

payload에 현재 잔액과 계정 상태가 들어 있습니다. 모니터링 스택에 연결해 두면 새벽 2시에 잔액이 바닥나 당황할 일이 없습니다. tronenergyrent.com 잔액의 최소 충전 금액은 10 TRX입니다.

실전 에러 처리

프로덕션에서 가장 자주 만나는 실패 유형은 셋입니다. 아래 에러 코드는 실제 API에서 나오는 값이므로 안전하게 분기할 수 있습니다.

  1. INSUFFICIENT_BALANCE: 선불 잔액이 요청한 임대 비용과 사전 활성화 비용을 감당하지 못합니다. 재시도해도 해결되지 않으니 재시도하지 말고, 이 경우를 따로 잡아 알림이나 충전 흐름을 트리거하십시오. 알림 payload에 requestId를 넣으십시오.
  2. INVALID_ADDRESS: destinationAddress가 서버에서 base58check 디코드에 실패했습니다. 사용자 입력 등으로 주소를 동적으로 만든다면 API를 호출하기 전에 로컬에서 검증하십시오. Python 라이브러리 tronpy에 is_address()가 있습니다. 잘못된 입력을 클라이언트에서 거르는 것이 왕복 호출을 기다리는 것보다 빠릅니다.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: 대상 주소가 온체인에서 활성화된 적이 없는데 서비스에 활성화를 요청하지도 않은 경우입니다. 다른 곳에서 소량의 TRX를 보내 주소를 활성화하거나, 다음 호출에 preActivateDestinationAddress=1을 넘겨 서비스가 1.5 TRX로 활성화하게 하면 해결됩니다.

조금 더 미묘한 경우로, 여러 워커가 같은 대상 주소에 동시에 임대를 주문하면 ORDER_IS_ALREADY_IN_PROGRESS가 돌아올 수 있습니다. 해법은 API 쪽이 아니라 프로세스 쪽에 있습니다. 대상 주소를 키로 하는 분산 락(Redis면 충분합니다)을 위임이 끝날 때까지 잡으십시오.

온체인 검증

대부분의 연동에서는 ENERGY_DELEGATED가 될 때까지 /single-order-details를 폴링하는 것으로 충분합니다. 이중으로 확인하고 싶다면 위임이 확정된 뒤 TRON 풀 노드에 직접 질의할 수도 있습니다.

GET https://api.trongrid.io/v1/accounts/{destinationAddress}

응답에는 외부 주소에서 위임받은 에너지를 포함한 해당 주소의 현재 리소스 상태가 들어 있습니다. 정확한 필드명은 현재 Stake 2.0 뷰에 따라 다르므로 연결할 때 최신 TRON HTTP API 문서를 참고하십시오. 전송을 막지 않고 경고만 로깅하는 소프트 체크로 두면, 임대 API에서는 성공으로 보이는데 온체인에서 무언가 어긋난 드문 경우를 잡아내는 카나리가 되고, 그 한 번에 디버깅 몇 시간을 아껴 줍니다.

TRON 거래 수수료를 절약하고 싶으신가요? 에너지 가격을 확인하세요. 가격 계산
블로그로 돌아가기