> For the complete documentation index, see [llms.txt](https://docs.luganodes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luganodes.com/tron-energy/energy-rental-api/quickstart.md).

# Quickstart

Make your first energy rental in about five minutes, once you have credentials.

This guide takes one USDT transfer from estimate to reclaim: check capacity, estimate the energy, rent it, broadcast inside the 10-second window and confirm the reclaim. Steps 2 to 6 have cURL, Node.js and Python code.

## Before you begin

* **Credentials from our team.** An API key, an API secret and the base URL. [Getting access](https://docs.luganodes.com/tron-energy/getting-access.md) explains how to request them.
* **Node.js 18 or later, or Python 3.9 or later** with `requests` (`pip install requests`). The cURL examples also need `openssl`, which ships with macOS and most Linux distributions.
* **A synced clock.** We reject a request whose timestamp is more than 30 seconds from our clock, so keep your machine on network time.
* **A USDT sending address.** A TRON address that holds USDT (TRC-20), is activated on chain and can sign transfers with your existing signing setup. Keep a few TRX on it for bandwidth beyond the free daily allowance; we can also cover bandwidth and account activation on request. The API calls this address the `receiver`: it sends the transfer and receives the energy. [Check an address](https://docs.luganodes.com/tron-energy/energy-rental-api/check-an-address.md) shows whether it is activated, and [Activate an address](https://docs.luganodes.com/tron-energy/energy-rental-api/activate-an-address.md) activates a new one.

Export your values. Sample IDs, addresses and hashes are illustrative: replace them with your own sending address and a recipient you control.

{% code title="env.sh" %}

```bash
export BASE_URL="https://<your-base-url>"   # shared with your credentials; leave out any trailing /v1
export API_KEY="<your-api-key>"
export API_SECRET="<your-api-secret>"
export SENDER="TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg"      # your USDT sending address
export RECIPIENT="TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y"   # the address that receives the USDT
export AMOUNT="1000000"                                  # 1 USDT, in the smallest unit
```

{% endcode %}

{% hint style="warning" %}
Steps 4 and 5 create a real rental and send a real USDT transfer on TRON mainnet. Use a small amount.
{% endhint %}

## Make your first rental

{% stepper %}
{% step %}

### Set up the signing helper

Every request is signed with HMAC-SHA256 and your API secret. Save the signing helper for your language from [Authentication and signing › Signing helpers](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md#signing-helpers): `tron_energy.sh` (cURL), `tron_energy.mjs` (Node.js) or `tron_energy.py` (Python). Steps 2 to 6 call it. Run `source env.sh` in the shell you use, and for cURL also `source tron_energy.sh`. Nothing is sent in this step.
{% endstep %}

{% step %}

### Check capacity

`GET /v1/capacity` returns the energy available now and the current wait. It is a signed `GET` with no body.

{% tabs %}
{% tab title="cURL" %}
{% code title="capacity.sh" %}

```bash
signed_curl GET /v1/capacity
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
Save as `capacity.mjs` and run `node capacity.mjs`.

{% code title="capacity.mjs" %}

```javascript
import { signedRequest } from "./tron_energy.mjs";

const { status, data } = await signedRequest("GET", "/v1/capacity");
console.log(status);
console.log(JSON.stringify(data, null, 2));
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
Save as `capacity.py` and run `python3 capacity.py`.

{% code title="capacity.py" %}

```python
import json

from tron_energy import signed_request

status, data = signed_request("GET", "/v1/capacity")
print(status)
print(json.dumps(data, indent=2))
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response:

{% code title="200 OK" %}

```json
{
  "status": "busy",
  "energy_available_now": 0,
  "max_single_rental": 140000,
  "daily_remaining": 41000000,
  "queue_length": 2,
  "estimated_wait_seconds": 31
}
```

{% endcode %}

In this sample the status is `busy`, so a new rental would be queued for about 31 seconds. When the status is `ok`, a rental returns `201` and the energy is on your address at once. [Check capacity](https://docs.luganodes.com/tron-energy/energy-rental-api/check-capacity.md) lists every status.
{% endstep %}

{% step %}

### Estimate energy

`POST /v1/estimate` simulates your USDT transfer and returns the energy and bandwidth it needs. Both addresses are screened.

{% tabs %}
{% tab title="cURL" %}
{% code title="estimate.sh" %}

```bash
BODY=$(printf '{"from":"%s","to":"%s","token":"USDT","amount":"%s"}' "$SENDER" "$RECIPIENT" "$AMOUNT")
signed_curl POST /v1/estimate "$BODY"
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
Save as `estimate.mjs` and run `node estimate.mjs`.

{% code title="estimate.mjs" %}

```javascript
import { signedRequest } from "./tron_energy.mjs";

const { SENDER, RECIPIENT, AMOUNT } = process.env;
const { status, data } = await signedRequest("POST", "/v1/estimate", {
  from: SENDER,
  to: RECIPIENT,
  token: "USDT",
  amount: AMOUNT,
});
console.log(status);
console.log(JSON.stringify(data, null, 2));
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
Save as `estimate.py` and run `python3 estimate.py`.

{% code title="estimate.py" %}

```python
import json
import os

from tron_energy import signed_request

status, data = signed_request("POST", "/v1/estimate", {
    "from": os.environ["SENDER"],
    "to": os.environ["RECIPIENT"],
    "token": "USDT",
    "amount": os.environ["AMOUNT"],
})
print(status)
print(json.dumps(data, indent=2))
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response:

{% code title="200 OK" %}

```json
{
  "energy_required": 64285,
  "recipient_holds_token": true,
  "bandwidth_required": 346,
  "sender_free_bandwidth_left": 600,
  "burn_cost_trx_if_unsponsored": 6.43,
  "receiver_activated": true
}
```

{% endcode %}

`energy_required` is the energy the transfer needs: about 64,285 when the recipient already holds USDT and about 130,285 when it has never held USDT. `burn_cost_trx_if_unsponsored` is the TRX the network would burn without delegated energy, 6.43 TRX in this sample.
{% endstep %}

{% step %}

### Create a rental

`POST /v1/rentals` in `transaction` mode simulates your transfer and delegates the energy it needs, plus 5%, to the `receiver`. The status code tells you where the rental stands:

* `201 Created`: the energy is on your sending address and the 10-second window is open.
* `202 Accepted`: the request is queued. Poll `GET /v1/rentals/{id}` every 2 to 5 seconds until `status` is `active`.

The window opens as soon as the rental is active, so have your signed transfer ready first. Step 5 signs the transfer, calls the code below and broadcasts.

{% tabs %}
{% tab title="cURL" %}
cURL shows the responses, but a rental made by hand usually expires before you can broadcast, so use the Node.js or Python code for steps 4 and 5. A response with `"status": "pending"` means the request is queued: paste its `rental_id` below and repeat the call until `status` is `active`.

{% code title="rental.sh" %}

```bash
BODY=$(printf '{"mode":"transaction","receiver":"%s","transaction":{"token":"USDT","to":"%s","amount":"%s"},"max_wait_seconds":300}' "$SENDER" "$RECIPIENT" "$AMOUNT")
signed_curl POST /v1/rentals "$BODY"

RENTAL_ID="rnt_01J9X5..."   # paste the rental_id from the response above
signed_curl GET "/v1/rentals/$RENTAL_ID"
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
Save as `rental.mjs`. The file defines `createRental`, which returns the rental once it is `active`. Step 5 calls it, so do not run it on its own.

{% code title="rental.mjs" %}

```javascript
import { signedRequest } from "./tron_energy.mjs";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Creates a transaction-mode rental and returns it once it is active.
// 201: the energy is already on the receiver. 202: queued, so poll until active.
export async function createRental(sender, recipient, amount, maxWaitSeconds = 300) {
  let { status, data } = await signedRequest("POST", "/v1/rentals", {
    mode: "transaction",
    receiver: sender, // the address that sends the transfer and receives the energy
    transaction: { token: "USDT", to: recipient, amount },
    max_wait_seconds: maxWaitSeconds,
  });
  if (status !== 201 && status !== 202) {
    throw new Error(`Rental request failed: HTTP ${status} ${JSON.stringify(data)}`);
  }

  const rentalId = data.rental_id;
  while (data.status === "pending") {
    await sleep(2000); // poll every 2 to 5 seconds
    ({ status, data } = await signedRequest("GET", `/v1/rentals/${rentalId}`));
    if (status !== 200) {
      throw new Error(`Rental lookup failed: HTTP ${status} ${JSON.stringify(data)}`);
    }
  }

  if (data.status !== "active") {
    throw new Error(`Rental ${rentalId} ended as ${data.status} (${data.failure_reason ?? "no failure reason"})`);
  }
  return data;
}
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
Save as `rental.py`. The file defines `create_rental`, which returns the rental once it is `active`. Step 5 calls it, so do not run it on its own.

{% code title="rental.py" %}

```python
import time

from tron_energy import signed_request

def create_rental(sender, recipient, amount, max_wait_seconds=300):
    """Create a transaction-mode rental and return it once it is active.

    201: the energy is already on the receiver. 202: queued, so poll until active.
    """
    status, rental = signed_request(
        "POST",
        "/v1/rentals",
        {
            "mode": "transaction",
            "receiver": sender,  # the address that sends the transfer and receives the energy
            "transaction": {"token": "USDT", "to": recipient, "amount": amount},
            "max_wait_seconds": max_wait_seconds,
        },
    )
    if status not in (201, 202):
        raise RuntimeError(f"Rental request failed: HTTP {status} {rental}")

    rental_id = rental["rental_id"]
    while rental["status"] == "pending":
        time.sleep(2)  # poll every 2 to 5 seconds
        status, rental = signed_request("GET", f"/v1/rentals/{rental_id}")
        if status != 200:
            raise RuntimeError(f"Rental lookup failed: HTTP {status} {rental}")

    if rental["status"] != "active":
        raise RuntimeError(f"Rental {rental_id} ended as {rental['status']} ({rental.get('failure_reason')})")
    return rental
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response:

{% tabs %}
{% tab title="201 Created" %}

```json
{
  "rental_id": "rnt_01J9X4...",
  "status": "active",
  "mode": "transaction",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "energy_delegated": 67500,
  "energy_used": null,
  "delegator": "T...",
  "delegate_tx": "8f3c...",
  "activation_tx": null,
  "created_at": "2026-10-19T10:00:00Z",
  "starts_at": "2026-10-19T10:00:03Z",
  "expires_at": "2026-10-19T10:00:13Z"
}
```

{% endtab %}

{% tab title="202 Accepted" %}

```json
{
  "rental_id": "rnt_01J9X5...",
  "status": "pending",
  "pending_reason": "waiting_for_energy",
  "reason": "busy",
  "estimated_wait_seconds": 31,
  "estimated_ready_at": "2026-10-19T10:00:31Z",
  "queue_position": 1,
  "serve_by": "2026-10-19T10:05:00Z",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "created_at": "2026-10-19T10:00:00Z"
}
```

{% endtab %}
{% endtabs %}

`energy_delegated` is the simulated need plus 5%: 64,285 energy becomes 67,500. A queued rental is served first in, first out, and ends as `expired` if it is still waiting at `serve_by`. [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md) covers the queue and every status.
{% endstep %}

{% step %}

### Broadcast your signed transfer

The energy is on the receiver for 10 seconds, from `starts_at` to `expires_at`. Sign the USDT transfer before you create the rental, hold it, and broadcast it the moment the rental is `active`. The Node.js and Python code does this in one run: it signs, calls `createRental` or `create_rental` from step 4, then broadcasts.

TronWeb (Node.js) and tronpy (Python) stand in for your existing signing setup. Replace the marked block with your own signer and key custody. Your private key never reaches Luganodes: only the signed transaction leaves your system, and it goes to a TRON node.

TRON libraries set a transaction to expire 60 seconds after it is built, so the code extends the expiry by `max_wait_seconds` to outlast a queued rental.

{% tabs %}
{% tab title="cURL" %}
Run this from a script the moment the rental is `active`: typed by hand, it usually misses the window. `signed-transaction.json` is the signed transaction from your own signing setup, since cURL cannot sign it.

{% code title="broadcast.sh" %}

```bash
export TRON_NODE_URL="https://<your-tron-node>"   # the TRON node or RPC provider you already use
curl -sS -X POST "$TRON_NODE_URL/wallet/broadcasttransaction" \
  -H "Content-Type: application/json" \
  --data-binary @signed-transaction.json
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
Run `npm install tronweb`, then set `TRON_NODE_URL` to the node you already use and `SENDER_PRIVATE_KEY` to the key of your sending address. Save as `transfer.mjs` and run `node transfer.mjs`.

{% code title="transfer.mjs" %}

```javascript
import { TronWeb } from "tronweb";
import { createRental } from "./rental.mjs";

const { SENDER, RECIPIENT, AMOUNT, TRON_NODE_URL, SENDER_PRIVATE_KEY } = process.env;
const USDT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"; // USDT (TRC-20) on TRON mainnet
const MAX_WAIT_SECONDS = 300;

// Your existing signing setup: replace this block with your own signer.
const tronWeb = new TronWeb({ fullHost: TRON_NODE_URL, privateKey: SENDER_PRIVATE_KEY });
const { transaction } = await tronWeb.transactionBuilder.triggerSmartContract(
  USDT,
  "transfer(address,uint256)",
  { feeLimit: 30000000 }, // caps the TRX burned if the energy falls short: 30 TRX, in sun
  [
    { type: "address", value: RECIPIENT },
    { type: "uint256", value: AMOUNT },
  ],
  SENDER,
);
// A transaction expires 60 seconds after it is built. Extend it to outlast a queued rental.
const extended = await tronWeb.transactionBuilder.extendExpiration(transaction, MAX_WAIT_SECONDS);
const signedTransaction = await tronWeb.trx.sign(extended);

// Create the rental and wait until it is active.
const rental = await createRental(SENDER, RECIPIENT, AMOUNT, MAX_WAIT_SECONDS);
console.log(`Rental ${rental.rental_id} is active until ${rental.expires_at}`);

// Broadcast at once, inside the 10-second window.
const result = await tronWeb.trx.sendRawTransaction(signedTransaction);
console.log(JSON.stringify({ result: result.result, txid: result.txid, code: result.code, message: result.message }, null, 2));
if (!result.result) process.exitCode = 1;
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
Run `pip install tronpy`, then set `TRON_NODE_URL` to the node you already use and `SENDER_PRIVATE_KEY` to the hex key of your sending address. Save as `transfer.py` and run `python3 transfer.py`.

{% code title="transfer.py" %}

```python
import json
import os

from tronpy import Tron
from tronpy.keys import PrivateKey
from tronpy.providers import HTTPProvider

from rental import create_rental

SENDER = os.environ["SENDER"]
RECIPIENT = os.environ["RECIPIENT"]
AMOUNT = os.environ["AMOUNT"]
USDT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"  # USDT (TRC-20) on TRON mainnet
MAX_WAIT_SECONDS = 300

# Your existing signing setup: replace this block with your own signer.
client = Tron(HTTPProvider(os.environ["TRON_NODE_URL"]))
private_key = PrivateKey(bytes.fromhex(os.environ["SENDER_PRIVATE_KEY"]))
signed_transaction = (
    client.get_contract(USDT)
    .functions.transfer(RECIPIENT, int(AMOUNT))
    .with_owner(SENDER)
    .fee_limit(30000000)  # caps the TRX burned if the energy falls short: 30 TRX, in sun
    # A transaction expires 60 seconds after it is built. Expire later, in milliseconds,
    # to outlast a queued rental.
    .expiration(60000 + MAX_WAIT_SECONDS * 1000)
    .build()
    .sign(private_key)
)

# Create the rental and wait until it is active.
rental = create_rental(SENDER, RECIPIENT, AMOUNT, MAX_WAIT_SECONDS)
print(f"Rental {rental['rental_id']} is active until {rental['expires_at']}")

# Broadcast at once, inside the 10-second window.
result = signed_transaction.broadcast()
print(json.dumps({"result": result.get("result"), "txid": result.txid}, indent=2))
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected output:

{% code title="Output" %}

```
Rental rnt_01J9X5... is active until 2026-10-19T10:00:41Z
{
  "result": true,
  "txid": "4f9a..."
}
```

{% endcode %}

`"result": true` means the transaction was accepted for broadcast. Keep the `rental_id` for step 6.

{% hint style="warning" %}
After `expires_at` the energy is reclaimed, and a transfer broadcast later has no delegated energy: TRON burns TRX from the sending address for the shortfall, or the transaction fails if the address holds none. Create a new rental if the window closes first.
{% endhint %}
{% endstep %}

{% step %}

### Confirm the reclaim

After the window closes we reclaim the energy. `GET /v1/rentals/{id}` then shows the final `status`, the `energy_used` and the `reclaim_tx`.

{% tabs %}
{% tab title="cURL" %}
{% code title="confirm.sh" %}

```bash
export RENTAL_ID="rnt_01J9X5..."   # the rental_id from step 4
signed_curl GET "/v1/rentals/$RENTAL_ID"
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
Set `RENTAL_ID`, save as `confirm.mjs` and run `node confirm.mjs`.

{% code title="confirm.mjs" %}

```javascript
import { signedRequest } from "./tron_energy.mjs";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const path = `/v1/rentals/${process.env.RENTAL_ID}`;

// The reclaim follows the end of the window. Poll until the rental reaches a final status.
let { status, data } = await signedRequest("GET", path);
for (let attempt = 0; attempt < 20 && status === 200 && ["pending", "active"].includes(data.status); attempt++) {
  await sleep(3000);
  ({ status, data } = await signedRequest("GET", path));
}
console.log(status);
console.log(JSON.stringify(data, null, 2));
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
Set `RENTAL_ID`, save as `confirm.py` and run `python3 confirm.py`.

{% code title="confirm.py" %}

```python
import json
import os
import time

from tron_energy import signed_request

path = f"/v1/rentals/{os.environ['RENTAL_ID']}"

# The reclaim follows the end of the window. Poll until the rental reaches a final status.
status, data = signed_request("GET", path)
for _ in range(20):
    if status != 200 or data["status"] not in ("pending", "active"):
        break
    time.sleep(3)
    status, data = signed_request("GET", path)

print(status)
print(json.dumps(data, indent=2))
```

{% endcode %}
{% endtab %}
{% endtabs %}

Expected response:

{% code title="200 OK" %}

```json
{
  "rental_id": "rnt_01J9X5...",
  "status": "reclaimed",
  "energy_delegated": 67500,
  "energy_used": 64285,
  "delegate_tx": "8f3c...",
  "reclaim_tx": "a91d...",
  "queued_at": "2026-10-19T10:00:00Z",
  "starts_at": "2026-10-19T10:00:31Z",
  "expires_at": "2026-10-19T10:00:41Z",
  "reclaimed_at": "2026-10-19T10:00:44Z",
  "failure_reason": null
}
```

{% endcode %}

`status: reclaimed` means the window closed and the energy was reclaimed. `energy_used` is the energy your transfer consumed and is final, and `reclaim_tx` is the hash of the reclaim transaction.

To verify on chain, open `delegate_tx`, your transfer's `txid` and `reclaim_tx` on Tronscan. A transaction page is at `https://tronscan.org/#/transaction/<hash>`.
{% endstep %}
{% endstepper %}

## If it fails

Every error uses the format described in [Errors](https://docs.luganodes.com/tron-energy/energy-rental-api/errors.md), which lists every code and whether to retry. These are the most likely problems on a first run.

| Symptom                                   | Cause                                                                                                   | Fix                                                                                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 UNAUTHORIZED` on any call            | A wrong key or secret, a clock more than 30 seconds off, or a signature that does not match the request | Work through the causes in [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md#troubleshooting-401-errors)                                  |
| `422 RECEIVER_NOT_ACTIVATED` in step 4    | The sending address has never been activated on chain                                                   | Call [Activate an address](https://docs.luganodes.com/tron-energy/energy-rental-api/activate-an-address.md), or set `activate_if_needed` to `true` on the rental                                 |
| `422 SIMULATION_FAILED` in step 3 or 4    | The transfer would fail on chain, usually because the sending address holds too little USDT             | Check the sender's USDT balance. `details.chain_message` holds the chain's message                                                                                                               |
| `409 ACTIVE_RENTAL_EXISTS` in step 4      | The address already has a `pending` or `active` rental                                                  | Poll the rental in `details.rental_id` until it ends, then create a new one                                                                                                                      |
| `503 CAPACITY_EXHAUSTED` in step 4        | The estimated wait is longer than `max_wait_seconds`, or no energy is available                         | Check capacity again and retry later, or send the transfer and pay TRX                                                                                                                           |
| The transfer fails or burns TRX in step 5 | The window closed before the broadcast, or the signed transaction expired in the queue                  | Create a new rental, sign with a longer expiration and broadcast as soon as it is `active`. See [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md) |

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>API reference</strong></td><td>Every Energy Rental API endpoint, with its method, path and what it does.</td><td><a href="https://docs.luganodes.com/tron-energy/energy-rental-api.md">API reference</a></td></tr></tbody></table>
