# Tronilend Energy API

How to buy TRON Energy at tronilend.com. No account, no key, no signature: a purchase is
a plain TRX transfer, and two open `GET` endpoints let you check an address and follow
the order. With an account, an API key lets your code buy from a wallet balance.
Base address `https://tronilend.com`, responses are JSON in UTF-8. The same reference as a page:
https://tronilend.com/developers

The service never asks for a seed phrase or a private key. Only a public address is used,
and Energy is handed over with the standard `DelegateResource` function.

## Buying: send TRX, receive Energy

Send **one of the exact amounts below** to the pool address. Energy is delegated back to
the address the payment came from, so pay from the wallet that needs the Energy — never
from an exchange account, because a withdrawal arrives from the exchange's own address
and the Energy would follow it there.

Pool address: `TXT5QsBD3pZYZaUVjiTtoimCaSppKKKKKK`

| Send | Energy | USDT transfers |
|---|---|---|
| 1.05 TRX | 65,000 | 1 |
| 2.1 TRX | 131,000 | 2 |
| 3.15 TRX | 196,000 | 3 |

The amount must match a row exactly; anything else is treated as an unrecognised payment.
Energy stays delegated for **60 minutes** and arrives 3–10 seconds after
the payment confirms. Unused Energy is not refunded when the term ends.

A brand-new address has to be activated on-chain first — that costs an extra
**1.2 TRX**, added on top of the package. `GET /api/check` reports whether it is needed.

## How much Energy a transfer needs

| Case | Energy |
|---|---|
| Recipient already holds USDT | ~65,000 |
| Recipient holds no USDT yet | ~131,000 |

The sum being sent makes no difference. Without Energy the network burns TRX instead:
about 6.85 TRX, or 13.35 TRX to a new address, at ~100 sun per Energy.
Burned TRX cannot be recovered.

## Open endpoints

### GET /api/check

What the address holds, how much Energy its next USDT transfer needs and which package covers the gap. Pass the recipient as well when you know it: the requirement doubles for a recipient with no USDT. No key.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `address` | query | yes | The address that will send the USDT and receive the Energy |
| `recipient` | query | no | The address that will receive the USDT |

```bash
curl "https://tronilend.com/api/check?address=TSender...&recipient=TRecipient..."
```

`200`:

```json
{
  "data": {
    "sender": { "address": "T...", "activated": true, "trx": 12.4, "usdt": 250, "energy": 0, "bandwidth": 600 },
    "recipient": { "address": "T...", "activated": true, "hasUsdt": true },
    "energyNeeded": 65000,
    "energyMissing": 65000,
    "bandwidthMissing": 0,
    "burnTrx": 6.85,
    "pack": { "trx": 1.05, "energy": 65000, "transfers": 1 },
    "needsActivation": false,
    "canPayInstant": true,
    "ready": false,
    "checkedAt": "2026-01-01T00:00:00.000Z"
  }
}
```

- `pack` is the cheapest package that covers `energyMissing`, or `null` when the need is larger than the grid.
- `ready` is true when nothing has to be bought at all.
- `canPayInstant` says whether the sender's TRX balance covers the package plus the transfer fee.

Limit: 30 requests per minute per IP.

### GET /api/order-status

Poll it after sending the TRX, passing the paying address and the moment you sent it. No key.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `from` | query | yes | The address the payment was sent from |
| `since` | query | yes | Unix time in milliseconds; only the last 2 hours are searched |

```bash
curl "https://tronilend.com/api/order-status?from=TSender...&since=1767225600000"
```

`200`:

```json
{
  "data": {
    "stage": "delegated",
    "paymentTx": "abc123…",
    "paidTrx": 1.05,
    "delegateTx": "def456…",
    "energy": 65000,
    "problem": false
  }
}
```

- `stage`: `waiting` — no matching payment yet; `received` — payment seen, Energy not delegated yet; `delegated` — Energy sent, `delegateTx` holds the transaction; `ready` — delegated and visible on the address.
- `problem: true` means the order needs a human — write to support@tronilend.com with `paymentTx`.
- `since` earlier than 2 hours ago is clamped.

Limit: 40 requests per minute per IP.

## With an account: the key API

Keys are issued in the cabinet under **API keys**; the key is shown once. Send it in a header:

```
Authorization: Bearer tle_<public>_<secret>
```

Scopes nest: `read` ⊆ `purchase` ⊆ `full`. A key may also carry a daily spending cap,
checked before the money moves; a refunded order gives its allowance back.
Machine-readable contract: [`/api/energy/v1/openapi.json`](https://tronilend.com/api/energy/v1/openapi.json).

### GET /api/energy/v1/me

The account behind the key, its wallet balance and the key's own daily limit. Key scope: `read`.

```bash
curl https://tronilend.com/api/energy/v1/me \
  -H "Authorization: Bearer tle_<public>_<secret>"
```

`200`:

```json
{
  "data": {
    "account": { "id": 2, "email": "you@example.com" },
    "key": { "name": "backend", "prefix": "a1b2c3d4", "scope": "purchase" },
    "balanceTrx": 25.4,
    "dailyLimitTrx": 50,
    "spentTodayTrx": 4.28
  }
}
```

- `dailyLimitTrx` is `null` for a key without a cap. `spentTodayTrx` counts since midnight UTC, net of refunds.

Limit: 120 requests per minute per key.

### GET /api/energy/v1/quote

What a purchase would cost right now, before making it. The price includes this account's own markup, if it has one. Key scope: `read`.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `energy` | query | yes | 65000, 131000 or 196000 |
| `term` | query | yes | 15m or 1h |

```bash
curl "https://tronilend.com/api/energy/v1/quote?energy=65000&term=1h" \
  -H "Authorization: Bearer tle_<public>_<secret>"
```

`200`:

```json
{ "data": { "energy": 65000, "term": "1h", "trx": 1.05 } }
```

Limit: 120 requests per minute per key.

### POST /api/energy/v1/orders

Delegates Energy to the address, paid from the wallet balance. The money moves only after the price, the balance and the key's daily limit are checked; a refused delivery puts it back on the balance. Key scope: `purchase`.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `address` | body | yes | TRON address the Energy is delegated to |
| `energy` | body | yes | 65000, 131000 or 196000 |
| `term` | body | yes | 15m or 1h |

```bash
curl -X POST https://tronilend.com/api/energy/v1/orders \
  -H "Authorization: Bearer tle_<public>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"address":"TQ2yVKnuHv2T9necU7Px3XuHuXXyZqHW3Y","energy":65000,"term":"1h"}'
```

`201`:

```json
{
  "data": {
    "id": 1042,
    "address": "TQ2yVKnuHv2T9necU7Px3XuHuXXyZqHW3Y",
    "energy": 65000,
    "term": "1h",
    "trx": 1.05,
    "status": "filled",
    "delegationTx": "cc823bbdf4397c6e9bed7379124367dcb616190dac730d2a2e1f2ef9f94dc0dc",
    "createdAt": "2026-10-29T17:27:08.728Z"
  }
}
```

- `202 under_review` — the delivery outcome is unclear and is being checked; the money is held until it resolves, do not retry the purchase.
- Unknown fields are refused with `422 validation_failed`, so a typo never buys the wrong thing.

Limit: 120 requests per minute per key.

### GET /api/energy/v1/orders

This account's orders, newest first. Key scope: `read`.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `limit` | query | no | 1–100, default 50 |
| `offset` | query | no | Rows to skip, default 0 |

```bash
curl "https://tronilend.com/api/energy/v1/orders?limit=20" \
  -H "Authorization: Bearer tle_<public>_<secret>"
```

`200`:

```json
{
  "data": [
  {
    "id": 1042,
    "address": "TQ2yVKnuHv2T9necU7Px3XuHuXXyZqHW3Y",
    "energy": 65000,
    "term": "1h",
    "trx": 1.05,
    "status": "filled",
    "delegationTx": "cc823bbdf4397c6e9bed7379124367dcb616190dac730d2a2e1f2ef9f94dc0dc",
    "createdAt": "2026-10-29T17:27:08.728Z"
  }
  ],
  "pagination": { "total": 1, "limit": 20, "offset": 0 }
}
```

- `status`: `pending` — being delivered; `filled` — Energy delegated; `failed` — refused, the money is back; `review` — needs a check by support.

Limit: 120 requests per minute per key.

### GET /api/energy/v1/orders/{id}

A single order of this account; another account's order answers 404, as if it did not exist. Key scope: `read`.

| Parameter | In | Required | Meaning |
|---|---|---|---|
| `id` | path | yes | The order id from the purchase or the list |

```bash
curl https://tronilend.com/api/energy/v1/orders/1042 \
  -H "Authorization: Bearer tle_<public>_<secret>"
```

`200`:

```json
{
  "data": {
    "id": 1042,
    "address": "TQ2yVKnuHv2T9necU7Px3XuHuXXyZqHW3Y",
    "energy": 65000,
    "term": "1h",
    "trx": 1.05,
    "status": "filled",
    "delegationTx": "cc823bbdf4397c6e9bed7379124367dcb616190dac730d2a2e1f2ef9f94dc0dc",
    "createdAt": "2026-10-29T17:27:08.728Z"
  }
}
```

Limit: 120 requests per minute per key.

## Errors

Every failure has the same shape; the key API adds a `message`, and `details` per field
when the request was invalid:

```json
{"error": {"code": "validation_failed", "message": "Some fields are invalid.", "details": {"energy": "One of 65000, 131000, 196000."}}}
```

| HTTP | code | When |
|---|---|---|
| 400 | `invalid_address` | `address` or `recipient` is not a TRON address |
| 400 | `invalid_query` | `from` is not an address, or `since` is not a number |
| 400 | `invalid_json` | The request body is not valid JSON |
| 401 | `unauthorized` | Missing, invalid or revoked API key |
| 402 | `insufficient_balance` | Not enough TRX on the wallet balance |
| 403 | `insufficient_scope` | The key's scope is too narrow for this call |
| 403 | `daily_limit_exceeded` | The key reached its daily spending cap |
| 404 | `not_found` | No such order, or it belongs to another account |
| 422 | `validation_failed` | A field is missing, unknown or out of range; `details` names it |
| 429 | `rate_limited` | Over the per-minute limit; wait for `Retry-After` seconds |
| 502 | `provider_upstream_error` | Delivery refused; the money is back on the balance |
| 502 | `network_unavailable` | The TRON node did not answer; retry |
| 503 | `provider_unavailable` | Pricing is temporarily unavailable |
| 503 | `pool_not_configured` | Instant purchases are temporarily off |

## Notes

- Every answer is sent with `cache-control: no-store`.
- Energy cannot be delegated to an exchange address; it will be lost.
- Support: support@tronilend.com