> For the complete documentation index, see [llms.txt](https://tron-energy-doc.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tron-energy-doc.crypto-chief.com/getting-started/readme.md).

# General Information

The **TRON Energy API** rents the energy a TRC-20 transfer needs, so the sending wallet does not burn TRX for it.

A USDT transfer on TRON runs contract code, and the network charges **energy** for that. A wallet holding none pays in burnt TRX at the chain's spot rate, which is the most expensive way there is to move a token on TRON. Energy can be delegated from one account to another, so we hold it and delegate it to your address for the moment of the transfer.

{% hint style="success" %}
**You do not have to know how much energy you need.** Send the recipient's address and leave the amount out — we read the chain and size the order. This is the part most integrations get wrong, and it is the difference between a transfer that lands and one that reverts having consumed the fee.
{% endhint %}

## Base URL

```
https://energy.crypto-chief.com
```

## Authentication

Two headers: the project the request comes from, and a signature proving it was made by someone holding that project's API key.

```
Merchant:  <your project UUID>
Signature: hex( md5( base64(canonical body) + api_key ) )
```

**The API key itself is never sent.** It is the secret the signature is computed with, and it stays on your server — the same key signs requests on every other Crypto Chief API, including ones that move funds, so putting it on the wire here would hand over that ability too.

Both values are in the Dashboard under **Project Settings**. There is no separate key for energy, and a project frozen on the platform cannot buy energy either.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const res = await fetch(BASE + "/v1/balance", {
  headers: { Merchant: MERCHANT, Signature: GET_SIG },
});
console.log(await res.json());
```

{% endtab %}

{% tab title="PHP" %}

```php
$ch = curl_init(BASE . '/v1/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Merchant: ' . MERCHANT,
        'Signature: ' . md5(API_KEY),
    ],
]);
print_r(json_decode(curl_exec($ch), true));
```

{% endtab %}

{% tab title="GO" %}

```go
req, _ := http.NewRequest("GET", base+"/v1/balance", nil)
req.Header.Set("Merchant", merchant)
req.Header.Set("Signature", getSig)   // md5(apiKey)

res, err := http.DefaultClient.Do(req)
```

{% endtab %}

{% tab title="Python" %}

```python
res = requests.get(
    BASE + "/v1/balance",
    headers={"Merchant": MERCHANT, "Signature": GET_SIG},
)
print(res.json())
```

{% endtab %}

{% tab title="curl" %}

```bash
curl "$BASE/v1/balance" \
  -H "Merchant: $MERCHANT" \
  -H "Signature: $GET_SIG"
```

{% endtab %}
{% endtabs %}

`$MERCHANT` is your project UUID and `$SIG` the signature over the body — [Authentication](/getting-started/authentication.md) has the algorithm, worked examples and test vectors.

`sign()`, `canonical()`, `GET_SIG`, `BASE`, `MERCHANT` and `API_KEY` are from [Authentication](/getting-started/authentication.md). That page also covers what is signed and why.

## Billing

Orders are charged to your **platform API credits** — the same balance the rest of the API spends. There is no separate energy balance to top up, and nothing is ever taken out of your wallets.

[`GET /v1/balance`](/api-reference/balance.md) reads it, free and unthrottled. It answers in the same shape the platform's own credits endpoint uses, so if you already parse that one, the code you have works here unchanged.

## The endpoints

| Method | Path                                              | What it does                                  |
| ------ | ------------------------------------------------- | --------------------------------------------- |
| `POST` | [`/v1/simulate`](/api-reference/simulate.md)      | Ask the chain what a transaction really needs |
| `POST` | [`/v1/activate`](/api-reference/activate.md)      | Bring a new address into existence            |
| `POST` | [`/v1/quotes`](/api-reference/quote.md)           | Price a purchase and hold that price briefly  |
| `POST` | [`/v1/orders`](/api-reference/create-order.md)    | Buy energy                                    |
| `GET`  | [`/v1/orders/{key}`](/api-reference/get-order.md) | What became of a request                      |
| `GET`  | [`/v1/balance`](/api-reference/balance.md)        | What you have left to spend                   |

## The shortest possible integration

One call. No quote, no polling — priced, charged and delivered before it answers:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const body = { receive_address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" };

const res = await fetch(BASE + "/v1/orders", {
  method: "POST",
  body: canonical(body),          // send exactly what you signed
  headers: {
    "Content-Type": "application/json",
    Merchant: MERCHANT,
    Signature: sign(body, API_KEY),
    "Idempotency-Key": "payout-8814",
  },
});
console.log(await res.json());
```

{% endtab %}

{% tab title="PHP" %}

```php
$body = ['receive_address' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'];

$ch = curl_init(BASE . '/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => canonical($body),  // what you signed
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Merchant: ' . MERCHANT,
        'Signature: ' . sign($body, API_KEY),
        'Idempotency-Key: payout-8814',
    ],
]);
print_r(json_decode(curl_exec($ch), true));
```

{% endtab %}

{% tab title="GO" %}

```go
body := map[string]any{"receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}
raw, _ := json.Marshal(body)      // Marshal sorts map keys for you

req, _ := http.NewRequest("POST", base+"/v1/orders", bytes.NewReader(raw))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Merchant", merchant)
req.Header.Set("Signature", sign(raw, apiKey))
req.Header.Set("Idempotency-Key", "payout-8814")

res, err := http.DefaultClient.Do(req)
```

{% endtab %}

{% tab title="Python" %}

```python
body = {"receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}

res = requests.post(
    BASE + "/v1/orders",
    data=canonical(body),          # send exactly what you signed
    headers={
        "Content-Type": "application/json",
        "Merchant": MERCHANT,
        "Signature": sign(body, API_KEY),
        "Idempotency-Key": "payout-8814",
    },
)
print(res.json())
```

{% endtab %}

{% tab title="curl" %}

```bash
BODY='{"receive_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}'

curl "$BASE/v1/orders" \
  -H "Content-Type: application/json" \
  -H "Merchant: $MERCHANT" \
  -H "Signature: $(sign "$BODY")" \
  -H "Idempotency-Key: payout-8814" \
  -d "$BODY"
```

{% endtab %}
{% endtabs %}

```json
{
  "id": 4471,
  "idempotency_key": "payout-8814",
  "status": "delivered",
  "receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "energy": 130285,
  "duration_sec": 3600,
  "price_sun": 5927968,
  "price_trx": "5.927968",
  "price_usd": "1.78",
  "credits": 17783904,
  "trx_usd": "0.30000000",
  "delivered_energy": 130285,
  "settled": true,
  "needs_attention": false,
  "created_at": "2026-08-30T11:42:07Z",
  "delivered_at": "2026-08-30T11:42:11Z"
}
```

Then send your USDT. It consumes the delegated energy instead of burning TRX.

{% hint style="warning" %}
**`Idempotency-Key` is required and has no default.** It is what makes a retry safe: the same key returns the original order rather than buying the energy a second time. We refuse the request rather than invent a key you could not repeat — see [Idempotency](/getting-started/idempotency.md).
{% endhint %}

## Before you build

Two short pages worth reading first, because they prevent the two mistakes that cost money:

* [**How energy works**](/getting-started/how-energy-works.md) — why the same transfer costs 64,285 energy to one address and 130,285 to another, what `OUT_OF_ENERGY` means, and why bandwidth is a separate problem.
* [**Idempotency and retries**](/getting-started/idempotency.md) — what to do when a request times out, and the one state where retrying is the wrong move.