> 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/guides/at-volume.md).

# Running at Volume

## Running at Volume

Notes for exchanges, payout desks and anyone calling this hundreds of times a day. Two things matter at that rate, and neither shows up in a first integration.

### Never buy the same energy twice

Use an idempotency key that identifies the **work**, not the attempt — your payout id, withdrawal id, transfer id. A fresh UUID per attempt defeats the mechanism entirely.

```
Idempotency-Key: payout-8814
```

On a timeout, ask rather than repeat:

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

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

{% endtab %}

{% tab title="PHP" %}

```php
$ch = curl_init(BASE . '/v1/orders/payout-8814');
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/orders/payout-8814", 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/orders/payout-8814",
    headers={"Merchant": MERCHANT, "Signature": GET_SIG},
)
print(res.json())
```

{% endtab %}

{% tab title="curl" %}

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

{% endtab %}
{% endtabs %}

`sign()`, `canonical()`, `GET_SIG`, `BASE`, `MERCHANT` and `API_KEY` are from [Authentication](/getting-started/authentication.md).

Repeating the POST with the same key is also safe — that is what the key is for. `GET` is cheaper and clearer in your logs.

### Handle `unresolved` deliberately

One state must not be retried. `needs_attention: true` means we called a supplier and never learned the outcome — the energy may have been delivered and may have been paid for.

```python
r = post_order(key, address)

if r.status_code == 409 and r.json().get("error") == "NEEDS_ATTENTION":
    # Do NOT retry. Fall back to burning TRX for this transfer,
    # flag the key for reconciliation, and move on.
    mark_for_support(key)
    return burn_trx_instead()
```

Retrying here is how one transfer gets bought twice.

### Let us size it

Leave `energy` out. At volume this is the difference between systematically over-buying on every warm address and systematically failing on every cold one — and the cold ones are the expensive mistake, because the transfer reverts having consumed the fee.

Supply an explicit `energy` only where you genuinely know better: contract calls, multi-sends, tokens whose contracts cost more than USDT's.

### Rent for the window you use

Energy returns at the end of the window. If you are draining a queue, one longer rental on a hot wallet is cheaper than one rental per transfer.

| Pattern                         | Sensible duration            |
| ------------------------------- | ---------------------------- |
| One transfer, occasionally      | `3600`                       |
| A batch drained within the hour | `3600` on the sending wallet |
| A queue running all day         | `86400`                      |

Do not over-buy time. A longer window costs more and buys nothing after the last transfer.

### Watch the balance, do not probe it

Alert on [`GET /v1/balance`](/api-reference/balance.md) before paid calls start failing. It is free and answers at zero or below. Never test affordability by attempting an order.

### Expect refusals, and mean it

`NOT_WORTH_RENTING` is us declining when renting would cost you more than burning. Treat it as a signal to fall back for that transfer, not as an outage — an alert that fires on it will cry wolf every time the energy market spikes.

### Timeouts

An order is synchronous and waits on a supplier. Allow **60 seconds** before giving up, and when you do give up, ask for the order rather than sending it again.