Energy rental · API reference

Two HTTP surfaces:

TRX-tier quote GET|POST /energy-rental/trx-quote: no API Key. Pass the energy you need, get the TRX to send.
Credits checkout /energy-rental/quote and /energy-rental/orders: requires X-API-Key.

Sending native TRX to the platform address is not itself HTTP; the quote only tells you how much to send. Duration is always 1 hour. Confirmed energy is not refundable.

Base URL

https://gateway.gelabs.org

Authentication

/energy-rental/trx-quote does not take an API Key.

Credits checkout requests:

X-API-Key: your-api-key
Content-Type: application/json

Create the key on the App page in Console. Energy rental must be enabled for that App. Omit appId and durationHours on the credits endpoints.

Response format

Same as Get started:

{
  "code": 0,
  "message": "success",
  "data": {}
}

code 0 is success. JSON is camelCase.

Endpoints

Method	Path	Purpose	Auth
GET / POST	`/energy-rental/trx-quote`	Energy → TRX to send	None
POST	`/energy-rental/quote`	Credits quote; no charge	`X-API-Key`
POST	`/energy-rental/orders`	Create	`X-API-Key`
GET	`/energy-rental/orders`	List	`X-API-Key`
GET	`/energy-rental/orders/:orderNo`	Detail	`X-API-Key`

After a credits order, poll detail until status is SUCCESS or FAILED.

GET / POST /energy-rental/trx-quote

Maps required energy up to the TRX-transfer tier. No API Key. Does not charge credits and does not send TRX.

How to use it:

Call this endpoint with energyAmount.
Check envelope code === 0.
Send data.trxAmount native TRX to data.payAddress.
Energy lands on the paying address. The amount is data.energyGranted, for data.durationHours hours. Confirm in an explorer; there is no order id.

This is not POST /energy-rental/quote, which prices in credits / USDT and requires a key.

Request

GET uses the query string; POST uses a JSON body.

Field	Type	Required	Description
`energyAmount`	integer	yes	Energy you need; must be > 0

Examples

curl "https://gateway.gelabs.org/energy-rental/trx-quote?energyAmount=80000"

curl -X POST \
  -H "Content-Type: application/json" \
  https://gateway.gelabs.org/energy-rental/trx-quote \
  -d '{"energyAmount":80000}'

Response `data`

Field	Type	Description
`energyAmount`	integer	The energy you asked for
`trxAmount`	integer	Native TRX to send
`energyGranted`	integer	Energy actually delegated after sending `trxAmount` (≥ requested)
`payAddress`	string	Pay-to address, currently `TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2`
`durationHours`	integer	Duration, always `1`

{
  "code": 0,
  "message": "success",
  "data": {
    "energyAmount": 80000,
    "trxAmount": 8,
    "energyGranted": 131000,
    "payAddress": "TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2",
    "durationHours": 1
  }
}

energyAmount ≤ 0 or unparseable returns HTTP 400 / code=10001.

POST /energy-rental/quote

Returns the credits / USDT that would be charged and whether the balance covers it. No charge.

Quote first. Do not create an order when data.sufficient is false.

Headers

Field	Required	Purpose
`X-API-Key`	yes	Key from Console
`Content-Type`	yes	`application/json`

Body

Field	Type	Required	Purpose
`energyAmount`	integer	yes	Energy to rent, ≥ `65000`
`receiverAddress`	string	no	TRON Base58 starting with `T`. Validated if sent. Required on create
`durationHours`	integer	no	Must be `1` or omitted

Example request

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  https://gateway.gelabs.org/energy-rental/quote \
  -d '{"energyAmount":65000,"receiverAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}'

Response `data`

Field	Type	Purpose
`energyAmount`	integer	Energy in this quote
`durationHours`	integer	Duration, always `1`
`creditsRequired`	integer	Credits from the energy formula
`planCode`	string	Current plan code
`creditsPerUsdt`	integer	Credits per 1 USDT
`creditsToDeduct`	integer	Credits that will be deducted
`usdtToDeductMicro`	integer	USDT to deduct if credits are short; micro, `1 USDT = 1_000_000`
`availableCredits`	integer	Credits available now
`availableUsdtMicro`	integer	USDT available now, micro
`sufficient`	boolean	Whether the balance covers the charge
`pricingBaseEnergy`	integer	Pricing base energy, currently `65000`
`pricingBaseCredits`	integer	Credits for the base, currently `90000`
`creditsPerEnergyDisplay`	string	Credits per extra energy unit, currently `"1.3846"`
`equivalentTrx`	string	Credits required, priced with `creditsPerUsdt`, then converted to TRX at the quote-time USD price. Decimal string, rounded up to 1 sun (`1 TRX = 1_000_000` sun). This call returns `503` when the price is unavailable

{
  "code": 0,
  "message": "success",
  "data": {
    "energyAmount": 65000,
    "durationHours": 1,
    "creditsRequired": 90000,
    "planCode": "basic",
    "creditsPerUsdt": 61224,
    "creditsToDeduct": 90000,
    "usdtToDeductMicro": 0,
    "availableCredits": 500000,
    "availableUsdtMicro": 0,
    "sufficient": true,
    "pricingBaseEnergy": 65000,
    "pricingBaseCredits": 90000,
    "creditsPerEnergyDisplay": "1.3846",
    "equivalentTrx": "5.880048"
  }
}

`"5.880048"` in the sample is what `0.25` USD per TRX produces. The number moves when the TRX price moves.

POST /energy-rental/orders

Creates a rental: reserve credits, then delegate energy to receiverAddress.

Headers

Field	Required	Purpose
`X-API-Key`	yes	Same as quote
`Content-Type`	yes	`application/json`
`Idempotency-Key`	yes	Idempotency key, preferably a UUID

Body

Field	Type	Required	Purpose
`energyAmount`	integer	yes	Same as the quote, ≥ `65000`
`receiverAddress`	string	yes	TRON address that receives energy, Base58, starts with `T`
`durationHours`	integer	no	Must be `1` or omitted
`gatewayOrderNo`	string	no	Do not send. The platform mints `GER_…`
`authorizationId`	string	no	Do not send on the product API

Idempotency

Idempotency-Key stops a timeout retry from charging twice:

Case	Result
First use of this key	New order, credits reserved
Same key, same address and energy	Original order, no extra charge
Same key, different address or energy	`409` / `code=10003`
Rent again (even to the same address)	New key

Example request

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  https://gateway.gelabs.org/energy-rental/orders \
  -d '{"energyAmount":65000,"receiverAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}'

On success data is one order (see Order fields). If the request times out, retry with the same Idempotency-Key.

GET /energy-rental/orders

Lists orders for this App.

X-API-Key

Query

Param	Type	Required	Purpose
`status`	string	no	`PROCESSING` / `SUCCESS` / `FAILED`
`orderNo`	string	no	Exact fulfillment id
`receiverAddress`	string	no	Exact receiver
`page`	integer	no	Default `1`
`pageSize`	integer	no	Default `50`

Example request

curl -H "X-API-Key: $API_KEY" \
  "https://gateway.gelabs.org/energy-rental/orders?page=1&pageSize=20"

Response `data`

Field	Type	Purpose
`list`	object[]	Orders on this page
`total`	integer	Total count
`page`	integer	Current page
`pageSize`	integer	Page size

GET /energy-rental/orders/:orderNo

Fetch one order. Path param is orderNo from create, not gatewayOrderNo.

curl -H "X-API-Key: $API_KEY" \
  https://gateway.gelabs.org/energy-rental/orders/ER_20260915120000_123456

data is the order object (no list wrapper).

Poll every 2–3 seconds until SUCCESS or FAILED.

Order fields

Times are UTC Unix seconds, or null if not yet set.

Field	Type	Purpose
`orderNo`	string	Fulfillment id; use it for detail
`gatewayOrderNo`	string	Platform-minted `GER_…`
`appId`	string	Owning App
`receiverAddress`	string	Energy receiver
`status`	string	`PROCESSING` / `SUCCESS` / `FAILED`
`creditsReserved`	integer	Reserved credits; not charged until confirm
`usdtReservedMicro`	integer	Reserved USDT micro
`creditsCharged`	integer	Charged credits; `0` while processing
`usdtCharged`	string	Charged USDT, 6 decimal places
`usdtChargedMicro`	integer	Charged USDT micro
`energyAmount`	integer	Ordered energy
`completedEnergyAmount`	integer	Delegated energy; `0` before success
`durationHours`	integer	Duration, currently always `1`
`paidAt`	integer / null	When the reserve succeeded
`delegatedAt`	integer / null	When energy was delegated
`expiresAt`	integer / null	When the lease expires
`source`	string	`api` or `console`
`upstreamOrderId`	string / null	Upstream id; `null` before submit
`createdAt`	integer	Created
`updatedAt`	integer	Last updated
`failReason`	string / null	Failure reason; `null` while processing or on success

{
  "code": 0,
  "message": "success",
  "data": {
    "orderNo": "ER_20260915120000_123456",
    "gatewayOrderNo": "GER_20260915120000_123456",
    "appId": "app_xxx",
    "receiverAddress": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
    "status": "PROCESSING",
    "creditsReserved": 90000,
    "usdtReservedMicro": 0,
    "creditsCharged": 0,
    "usdtCharged": "0.000000",
    "usdtChargedMicro": 0,
    "energyAmount": 65000,
    "completedEnergyAmount": 0,
    "durationHours": 1,
    "paidAt": 1757923200,
    "delegatedAt": null,
    "expiresAt": null,
    "source": "api",
    "upstreamOrderId": null,
    "createdAt": 1757923200,
    "updatedAt": 1757923200,
    "failReason": null
  }
}

Status

`status`	Meaning
`PROCESSING`	Reserved; delegation in progress
`SUCCESS`	Energy on `receiverAddress`; credits charged
`FAILED`	Failed; reserve released

How to confirm energy arrived

Detail status is SUCCESS and completedEnergyAmount > 0.
Open receiverAddress on TronScan and check Energy.
Optional, call a TRON node:

curl -X POST https://api.trongrid.io/wallet/getaccountresource \
  -H "Content-Type: application/json" \
  -d '{"address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","visible":true}'

Read EnergyLimit / EnergyUsed.

Errors

Read HTTP status together with envelope code. Do not treat code !== 0 as success.

HTTP	`code`	When
400	`10001`	Bad input: energy ≤ 0 (TRX quote), energy below 65000 (credits API), address not starting with `T`, duration not 1
401	`20001`	Missing or invalid `X-API-Key`
403	`20002`	Energy rental not enabled for this App
404	`10002`	Order not found or not owned by this App
409	`10003`	Same `Idempotency-Key` but address / energy differs from the original
402	`50001`	Not enough credits / USDT (check quote `sufficient` first)
503	`10005`	Upstream temporarily unavailable

TRX tiers

Send native TRX to TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2. Energy goes to the paying address. Received amount rounds down.

TRX received	Energy
Under 4	No rent; TRX is kept
4	65,000
8	131,000 (special case, not 130,000)
`4n` (n≥3)	`65000 × n`

When you know the energy you need, round up or call GET|POST /energy-rental/trx-quote. 80,000 energy needs 8 TRX (you get 131,000).

Base URL​

Authentication​

Response format​

Endpoints​

GET / POST /energy-rental/trx-quote​

Request​

Examples​

Response data​

POST /energy-rental/quote​

Headers​

Body​

Example request​

Response data​

POST /energy-rental/orders​

Headers​

Body​

Idempotency​

Example request​

GET /energy-rental/orders​

Header​

Query​

Example request​

Response data​

GET /energy-rental/orders/:orderNo​

Order fields​

Status​

How to confirm energy arrived​

Errors​

TRX tiers​

Base URL

Authentication

Response format

Endpoints

GET / POST /energy-rental/trx-quote

Request

Examples

Response `data`

POST /energy-rental/quote

Headers

Body

Example request

Response `data`

POST /energy-rental/orders

Headers

Body

Idempotency

Example request

GET /energy-rental/orders

Header

Query

Example request

Response `data`

GET /energy-rental/orders/:orderNo

Order fields

Status

How to confirm energy arrived

Errors

TRX tiers