> 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/estimate-energy.md).

# Estimate energy

POST /v1/estimate: the energy and bandwidth a transfer needs, before you rent.

Simulates a USDT transfer on chain. Both addresses are screened. Use it to size a transfer and to see what it would cost in TRX without delegated energy.

## At a glance

| Item            | Detail                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Method and path | `POST /v1/estimate`                                                                                                                       |
| Authentication  | Signed request. See [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md)             |
| Retry-safe      | Yes. The request simulates a transfer and does not create a rental                                                                        |
| Rate limit      | Per API key. See [Conventions and limits](https://docs.luganodes.com/tron-energy/energy-rental-api/conventions-and-limits.md#rate-limits) |

## Request body

| Name     | Type   | Required | Default | Description                                             |
| -------- | ------ | -------- | ------- | ------------------------------------------------------- |
| `from`   | string | Yes      | None    | Address sending the USDT                                |
| `to`     | string | Yes      | None    | Recipient address                                       |
| `token`  | string | Yes      | None    | `USDT`. Any other token returns `400 UNSUPPORTED_TOKEN` |
| `amount` | string | Yes      | None    | Amount in the smallest unit. 10 USDT = `"10000000"`     |

## Sample request

Sample IDs, addresses and hashes are illustrative.

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

```bash
TIMESTAMP=$(date +%s)
REQUEST_PATH="/v1/estimate"
BODY='{
  "from": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "to": "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
  "token": "USDT",
  "amount": "10000000"
}'
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="estimate-energy.mjs" %}

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

const { status, data } = await signedRequest("POST", "/v1/estimate", {
  from: "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  to: "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
  token: "USDT",
  amount: "10000000",
});
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="estimate\_energy.py" %}

```python
from tron_energy import signed_request

status, data = signed_request("POST", "/v1/estimate", {
    "from": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
    "to": "TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y",
    "token": "USDT",
    "amount": "10000000",
})
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

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

A transfer that would fail on chain, such as one with an insufficient USDT balance, returns `422 SIMULATION_FAILED`.

## Response fields

| Field                          | Type    | Description                                                               |
| ------------------------------ | ------- | ------------------------------------------------------------------------- |
| `energy_required`              | integer | Energy the transfer needs                                                 |
| `recipient_holds_token`        | boolean | Whether the recipient already holds USDT                                  |
| `bandwidth_required`           | integer | Bandwidth the transfer needs                                              |
| `sender_free_bandwidth_left`   | integer | Free bandwidth the sender has today                                       |
| `burn_cost_trx_if_unsponsored` | number  | TRX the network would burn without delegated energy                       |
| `receiver_activated`           | boolean | Whether the receiver, the sending address (`from`), is activated on chain |

### Reading the sample

`recipient_holds_token` explains the energy figure: a recipient that has never held USDT needs about 130,285 energy instead of 64,285. In the sample, the transfer needs 64,285 energy. At the network energy price of 100 sun per unit (28 Oct 2026) that is 6,428,500 sun, or 6.4285 TRX, shown rounded as `6.43`. The sender's 600 free bandwidth covers the 346 bandwidth the transfer needs, so the figure is the energy cost alone. [How TRON fees work](https://docs.luganodes.com/tron-energy/how-tron-fees-work.md) explains the model.

## 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`     | `from` or `to` has an invalid format or checksum                                    | Fix the address                                                 | No                       |
| 400  | `INVALID_AMOUNT`      | `amount` is not a positive whole number in the smallest unit                        | Fix the amount                                                  | No                       |
| 400  | `UNSUPPORTED_TOKEN`   | `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                       |
| 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              |
| 429  | `RATE_LIMITED`        | Too many requests                                                                   | Retry after `Retry-After`                                       | Yes, after `Retry-After` |
| 503  | `SERVICE_UNAVAILABLE` | Planned maintenance or an outage                                                    | Retry after `Retry-After`                                       | Yes, after `Retry-After` |

## Related

* [Create a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/create-a-rental.md): delegate the energy this estimate calls for.
* [How TRON fees work](https://docs.luganodes.com/tron-energy/how-tron-fees-work.md): bandwidth, energy and what a transaction costs.
