> 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/create-a-rental.md).

# Create a rental

POST /v1/rentals: delegate energy to a sending address for one transaction.

The receiver is the address that sends the transaction and receives the energy. The endpoint returns `201` when the energy is on the address, `202` when the request is queued and `503 CAPACITY_EXHAUSTED` when the request cannot be queued.

## At a glance

| Item            | Detail                                                                                                                                                                             |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method and path | `POST /v1/rentals`                                                                                                                                                                 |
| Authentication  | Signed request. See [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md)                                                      |
| Retry-safe      | Yes, while the first rental is `pending` or `active`: a repeated request returns `409 ACTIVE_RENTAL_EXISTS` with the existing `rental_id`. See [Retry behaviour](#retry-behaviour) |
| Rate limit      | Per API key. See [Conventions and limits](https://docs.luganodes.com/tron-energy/energy-rental-api/conventions-and-limits.md#rate-limits)                                          |

## Modes

| Mode          | You send                                                                                                                  | We delegate                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `transaction` | The USDT transfer in `transaction`: `token`, `to` and `amount`. Any token other than USDT returns `400 UNSUPPORTED_TOKEN` | The energy the simulated transfer needs, plus 5% |
| `energy`      | An amount of energy in `energy`, from 10,000 to 140,000                                                                   | The amount you set, for any contract call        |

## Request body

| Name                 | Type    | Required              | Default | Description                                                                |
| -------------------- | ------- | --------------------- | ------- | -------------------------------------------------------------------------- |
| `mode`               | string  | Yes                   | None    | `transaction` or `energy`                                                  |
| `receiver`           | string  | Yes                   | None    | Address that sends the transaction and receives the energy                 |
| `transaction`        | object  | In `transaction` mode | None    | `token`, `to` and `amount` of the transfer                                 |
| `energy`             | integer | In `energy` mode      | None    | Energy to delegate. 10,000 to 140,000                                      |
| `max_wait_seconds`   | integer | No                    | 300     | Longest wait in seconds if the request is queued                           |
| `activate_if_needed` | boolean | No                    | `false` | If the receiver is not activated, activate it before delegating the energy |

The `transaction` object holds the transfer. Its fields match the [Estimate energy](https://docs.luganodes.com/tron-energy/energy-rental-api/estimate-energy.md) body, without `from`:

| Name     | Type   | Description                                         |
| -------- | ------ | --------------------------------------------------- |
| `token`  | string | `USDT`                                              |
| `to`     | string | Recipient address                                   |
| `amount` | string | Amount in the smallest unit. 10 USDT = `"10000000"` |

## Sample request

Sample IDs, addresses and hashes are illustrative.

### Transaction mode

{% tabs %}
{% tab title="cURL" %}
{% code title="create-a-rental.sh" %}

```bash
TIMESTAMP=$(date +%s)
REQUEST_PATH="/v1/rentals"
BODY='{
  "mode": "transaction",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "transaction": {
    "token": "USDT",
    "to": "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
    "amount": "10000000"
  },
  "max_wait_seconds": 300,
  "activate_if_needed": true
}'
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "POST" "$REQUEST_PATH" "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')
curl -X POST "$BASE_URL$REQUEST_PATH" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"
```

{% endcode %}

The request is signed inline. It needs `BASE_URL`, `API_KEY` and `API_SECRET` in your environment.
{% endtab %}

{% tab title="Node.js" %}
{% code title="create-a-rental.mjs" %}

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

const { status, data } = await signedRequest("POST", "/v1/rentals", {
  mode: "transaction",
  receiver: "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  transaction: {
    token: "USDT",
    to: "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
    amount: "10000000",
  },
  max_wait_seconds: 300,
  activate_if_needed: true,
});
console.log(status, data);
```

{% endcode %}

`signedRequest` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.mjs`.
{% endtab %}

{% tab title="Python" %}
{% code title="create\_a\_rental.py" %}

```python
from tron_energy import signed_request

status, data = signed_request("POST", "/v1/rentals", {
    "mode": "transaction",
    "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
    "transaction": {
        "token": "USDT",
        "to": "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
        "amount": "10000000",
    },
    "max_wait_seconds": 300,
    "activate_if_needed": True,
})
print(status, data)
```

{% endcode %}

`signed_request` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.py`.
{% endtab %}
{% endtabs %}

### Energy mode

Set the amount of energy yourself. The response has the same fields, with `mode` set to `energy`.

{% tabs %}
{% tab title="cURL" %}
{% code title="create-a-rental-energy.sh" %}

```bash
TIMESTAMP=$(date +%s)
REQUEST_PATH="/v1/rentals"
BODY='{
  "mode": "energy",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "energy": 100000
}'
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "POST" "$REQUEST_PATH" "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')
curl -X POST "$BASE_URL$REQUEST_PATH" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"
```

{% endcode %}

The request is signed inline. It needs `BASE_URL`, `API_KEY` and `API_SECRET` in your environment.
{% endtab %}

{% tab title="Node.js" %}
{% code title="create-a-rental-energy.mjs" %}

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

const { status, data } = await signedRequest("POST", "/v1/rentals", {
  mode: "energy",
  receiver: "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  energy: 100000,
});
console.log(status, data);
```

{% endcode %}

`signedRequest` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.mjs`.
{% endtab %}

{% tab title="Python" %}
{% code title="create\_a\_rental\_energy.py" %}

```python
from tron_energy import signed_request

status, data = signed_request("POST", "/v1/rentals", {
    "mode": "energy",
    "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
    "energy": 100000,
})
print(status, data)
```

{% endcode %}

`signed_request` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.py`.
{% endtab %}
{% endtabs %}

## Responses

{% tabs %}
{% tab title="201 Created" %}
The energy is on the receiver and the rental is `active`. Broadcast now.

```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" %}
The request is queued. Poll [`GET /v1/rentals/{id}`](https://docs.luganodes.com/tron-energy/energy-rental-api/get-a-rental.md) every 2 to 5 seconds and broadcast once the status is `active`.

```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 %}

{% tab title="409 Conflict" %}
The address already has a `pending` or `active` rental. `details` holds the existing `rental_id`.

```json
{
  "status": 409,
  "code": "ACTIVE_RENTAL_EXISTS",
  "message": "This address already has a rental in progress.",
  "details": { "rental_id": "rnt_01J9X5...", "status": "pending" },
  "request_id": "req_01JA2..."
}
```

{% endtab %}
{% endtabs %}

When the request cannot be queued, the API returns `503 CAPACITY_EXHAUSTED` in place of `202`. `details` has `reason` and `estimated_wait_seconds`. See [Errors](#errors).

## Response fields

| Field                    | Type            | In sample   | Description                                                                        |
| ------------------------ | --------------- | ----------- | ---------------------------------------------------------------------------------- |
| `rental_id`              | string          | 201 and 202 | Rental ID. Use it to poll `GET /v1/rentals/{id}`                                   |
| `status`                 | string          | 201 and 202 | `active` or `pending`                                                              |
| `mode`                   | string          | 201         | `transaction` or `energy`                                                          |
| `receiver`               | string          | 201 and 202 | Address that sends the transaction and receives the energy                         |
| `energy_delegated`       | integer         | 201         | Energy delegated to the receiver. In `transaction` mode the simulated need plus 5% |
| `energy_used`            | integer or null | 201         | Energy the transaction consumed. `null` until the rental is `reclaimed`            |
| `delegator`              | string          | 201         | Luganodes address that delegated the energy                                        |
| `delegate_tx`            | string          | 201         | Hash of the delegation transaction                                                 |
| `activation_tx`          | string or null  | 201         | Hash of the activation transaction. `null` when none was needed                    |
| `created_at`             | string          | 201 and 202 | Time the rental was created                                                        |
| `starts_at`              | string          | 201         | Start of the 10-second window                                                      |
| `expires_at`             | string          | 201         | End of the 10-second window                                                        |
| `pending_reason`         | string          | 202         | `waiting_for_energy` or `confirming`                                               |
| `reason`                 | string          | 202         | Why the rental is queued: `busy` or `daily_limit`                                  |
| `estimated_wait_seconds` | integer         | 202         | Expected wait before energy is delegated                                           |
| `estimated_ready_at`     | string          | 202         | Expected time the rental turns `active`                                            |
| `queue_position`         | integer         | 202         | Position in the queue                                                              |
| `serve_by`               | string          | 202         | Latest time the rental can be served                                               |

[Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md) explains the window, the queue and every status.

## Retry behaviour

Each address can hold one `pending` or `active` rental at a time. That rule makes a repeated request safe while the first rental is in progress.

| Situation                                                               | What the API does                                                                             | What to do                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The request is repeated while the first rental is `pending` or `active` | Returns `409 ACTIVE_RENTAL_EXISTS` with the existing `rental_id`. No second rental is created | Poll `GET /v1/rentals/{id}` for that rental                                                                                                                                                                                                                                                                                                                            |
| The first rental has ended as `reclaimed`, `failed` or `expired`        | The address has no `pending` or `active` rental, so a new request is a new rental             | Send a new request only if you still need energy for a transaction                                                                                                                                                                                                                                                                                                     |
| The request timed out and the outcome is unknown                        | The rental may or may not exist                                                               | Call `GET /v1/accounts/{address}`: a value in `active_rental_id` means the address has a `pending` or `active` rental. If there is none, call `GET /v1/rentals` with the `receiver` filter: rentals come back newest first, and one created after your request was sent means the first call succeeded. Send the request again only if neither check finds that rental |
| `429 RATE_LIMITED`                                                      | Returns `Retry-After`                                                                         | Wait for `Retry-After`, then send the request again                                                                                                                                                                                                                                                                                                                    |
| `502 CHAIN_ERROR`                                                       | The network was unreachable or the delegation did not land                                    | Check `GET /v1/rentals/{id}` and send the request again if the rental is `failed`                                                                                                                                                                                                                                                                                      |
| `503 CAPACITY_EXHAUSTED`                                                | The request cannot be queued                                                                  | Send the transfer and pay TRX, or retry later                                                                                                                                                                                                                                                                                                                          |
| `503 SERVICE_UNAVAILABLE`                                               | Returns `Retry-After`                                                                         | Wait for `Retry-After`, then send the request again                                                                                                                                                                                                                                                                                                                    |

## Errors

The full list is in [Errors](https://docs.luganodes.com/tron-energy/energy-rental-api/errors.md).

| HTTP | Code                     | When                                                                                                                             | Action                                                            | Retry?                   |
| ---- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------ |
| 400  | `INVALID_REQUEST`        | Malformed JSON, missing field or wrong type                                                                                      | Fix the request                                                   | No                       |
| 400  | `INVALID_ADDRESS`        | `receiver` or `transaction.to` has an invalid format or checksum                                                                 | Fix the address                                                   | No                       |
| 400  | `INVALID_AMOUNT`         | `transaction.amount` is not a positive whole number in the smallest unit                                                         | Fix the amount                                                    | No                       |
| 400  | `INVALID_DURATION`       | `max_wait_seconds` is out of range                                                                                               | Fix the value                                                     | No                       |
| 400  | `UNSUPPORTED_TOKEN`      | `transaction.token` is not USDT                                                                                                  | Use USDT                                                          | No                       |
| 401  | `UNAUTHORIZED`           | Invalid API key, signature or timestamp                                                                                          | Check your credentials and server clock                           | After a fix              |
| 403  | `ADDRESS_BLOCKED`        | An address matched a sanctions list                                                                                              | Stop the transfer. Contact us if you believe the match is wrong   | No                       |
| 409  | `ACTIVE_RENTAL_EXISTS`   | The address already has a `pending` or `active` rental                                                                           | Poll the rental in `details.rental_id`                            | No                       |
| 422  | `SIMULATION_FAILED`      | The transfer would fail on chain. `details.chain_message` holds the chain's message                                              | Check the sender's USDT balance                                   | After a fix              |
| 422  | `RECEIVER_NOT_ACTIVATED` | The receiver has never been activated on chain                                                                                   | Activate the address first, or set `activate_if_needed` to `true` | After a fix              |
| 422  | `RECEIVER_IS_CONTRACT`   | The receiver is a smart contract                                                                                                 | Send from a wallet address                                        | No                       |
| 422  | `RENTAL_TOO_LARGE`       | Energy above `max_single_rental`                                                                                                 | Request less energy                                               | No                       |
| 429  | `RATE_LIMITED`           | Too many requests                                                                                                                | Retry after `Retry-After`                                         | Yes, after `Retry-After` |
| 429  | `QUOTA_EXCEEDED`         | Daily energy quota or queued-rental cap used                                                                                     | Contact us to raise the quota                                     | After a fix              |
| 502  | `CHAIN_ERROR`            | The network was unreachable or the delegation did not land                                                                       | Check `GET /v1/rentals/{id}` and retry if the rental is `failed`  | Yes, after checking      |
| 503  | `CAPACITY_EXHAUSTED`     | Estimated wait is longer than `max_wait_seconds`, or no energy is available. `details` has `reason` and `estimated_wait_seconds` | Send the transfer and pay TRX, or retry later                     | Yes, later               |
| 503  | `SERVICE_UNAVAILABLE`    | Planned maintenance or an outage                                                                                                 | Retry after `Retry-After`                                         | Yes, after `Retry-After` |

## Related

* [Check capacity](https://docs.luganodes.com/tron-energy/energy-rental-api/check-capacity.md): see how this endpoint will respond before you call it.
* [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md): the 10-second window, queued requests and statuses.
