# NolGas API v1

TRON energy & bandwidth rentals over REST. Rent exactly the resources a transfer needs,
for exactly as long as you need them — no TRX burned, no stake managed on your side.

- **Base URL:** `https://api.nolgas.com/v1`
- **Format:** JSON over HTTPS. UTF-8. All timestamps are ISO 8601 UTC.
- **This document:** always current at `https://api.nolgas.com/v1/docs`.
- **Status:** v1 — live. Field names are stable; we will add fields but never rename or
  remove them within v1.

---

## Authentication

Your API token is issued when your account is set up — access is currently
**request-based**: apply at <https://nolgas.com>. Once onboarded, you can view or rotate
the token anytime from your NolGas bot account (🔌 API → 🔑 Generate token). Every
request carries it in the `X-API-KEY` header:

```
X-API-KEY: ng_live_9f83c…
```

A key is tied to one prepaid NolGas account. All rentals are paid from that account's TRX
balance. Keep the key secret; it can spend your balance. Compromised key → regenerate it
from your bot account (🔌 API → ♻️ Regenerate token); the old key stops working
immediately.

Missing or invalid key → `401 {"error":{"code":"unauthorized"}}`.

## Prepaid balance & funding

Your account holds a TRX balance. Rentals debit it at order time (pay-to-reserve).

Fund it by sending **TRX or USDT (TRC-20)** to your account's permanent deposit address
(`GET /v1/deposit`). Credits post automatically within a few minutes of on-chain
confirmation:

- **TRX** credits 1:1.
- **USDT** converts to TRX at the live market rate at the moment the deposit confirms.
  The rate shown by `GET /v1/deposit` is indicative; the confirm-time rate is applied.

## Async model

`POST /v1/rent` returns immediately with an `orderNo` and status `pending`. The delegation
is broadcast on-chain within seconds; poll `GET /v1/rentals/{orderNo}` until status
`active` (the `txid` field is then set). At the end of the rental window the stake is
reclaimed automatically and the order becomes `reclaimed`. No action needed on your side.

| Order status | Meaning |
|---|---|
| `pending` | accepted & charged; delegation not yet confirmed on-chain |
| `active` | delegated on-chain (`txid` set); resource is live on the target until `expiresAt` |
| `reclaimed` | window ended; stake reclaimed (terminal) |
| `failed` | could not fill (e.g. pool capacity); charge refunded (terminal) |

## Products, bounds & pricing

| | ENERGY | BANDWIDTH |
|---|---|---|
| Amount bounds per order | 65,000 – 4,000,000 | 1,000 – 30,000 |
| Durations | `1h`, `1d` | `1h`, `1d` |

A `1d` rental costs the same as `1h` — pricing is per use; duration is how long
the energy stays available. Longer durations (`3d`/`7d`) are temporarily unavailable.
price for any combination from `POST /v1/quote` — quotes are free and don't charge.

Reference prices at current defaults (subject to change; always quote first):

| Order | Price |
|---|---|
| 65,000 ENERGY / 1h (USDT transfer to a wallet that holds USDT) | 4.55 TRX |
| 131,000 ENERGY / 1h (USDT transfer to a fresh wallet) | 9.17 TRX |
| 65,000 ENERGY / 1d | 4.55 TRX |
| 1,000 BANDWIDTH / 1h | 0.70 TRX |

*(Burning without NolGas: 65K energy ≈ 6.5 TRX, 131K ≈ 13.1 TRX per transfer.)*

## Errors

Non-2xx responses carry:

```json
{ "error": { "code": "insufficient_balance", "message": "balance 2.10 TRX, need 4.55 TRX" } }
```

| HTTP | code | When |
|---|---|---|
| 400 | `invalid_request` | malformed body, unknown resource/duration |
| 400 | `amount_out_of_bounds` | outside the bounds table above |
| 400 | `target_not_activated` | target address has never received TRX/tokens |
| 401 | `unauthorized` | missing/invalid API key |
| 402 | `insufficient_balance` | balance below the order price |
| 404 | `not_found` | unknown `orderNo` (or not your order) |
| 429 | `rate_limited` | over the request budget (fair use: 120 req/min per key) |
| 503 | `pool_exhausted` | temporarily out of delegatable capacity — retry shortly |

---

## Endpoints

### GET /v1/balance

Current prepaid balance.

```
curl -H "X-API-KEY: $KEY" https://api.nolgas.com/v1/balance
```
```json
{ "balanceTrx": 4126.66 }
```

### GET /v1/deposit

Your permanent deposit address for topping up (same address every time; never expires).

```json
{
  "address": "TJ7YE9qDtcUULu…",
  "accepts": ["TRX", "USDT-TRC20"],
  "usdtRateIndicative": 2.958
}
```

`usdtRateIndicative` = TRX credited per 1 USDT if a deposit confirmed right now. The
actual rate is fixed at confirm time.

### POST /v1/quote

Firm price for a rental. Free, no charge, no reservation.

```json
{ "resource": "ENERGY", "amount": 131000, "duration": "1h" }
```
```json
{ "resource": "ENERGY", "amount": 131000, "duration": "1h", "priceTrx": 9.17 }
```

### POST /v1/cost

Batch on-chain check: how much energy a USDT transfer **to each target** actually needs
(65,000 if the target already holds USDT; 131,000 if it's fresh), plus whether the
address is activated. Use it to rent the exact amount instead of over-paying. Max 50
targets per call.

```json
{ "targets": ["TAi3T12CwHx…", "TEe1Mu4HMha…"] }
```
```json
{
  "results": [
    { "target": "TAi3T12CwHx…", "active": true,  "needEnergy": 65000 },
    { "target": "TEe1Mu4HMha…", "active": true,  "needEnergy": 131000 }
  ]
}
```

### POST /v1/rent

Create a rental. Charges your balance immediately and returns `pending`; poll the order
until `active`.

```json
{
  "resource": "ENERGY",
  "amount": 65000,
  "duration": "1h",
  "target": "TAi3T12CwHx…",
  "reference": "wd-20260722-0042"
}
```

`reference` (optional, ≤64 chars) is your idempotency key, unique per account: retrying
a rent with the same `reference` returns the original order instead of creating and
charging a second one. Strongly recommended for automated integrations.

```json
{
  "orderNo": 42,
  "status": "pending",
  "resource": "ENERGY",
  "amount": 65000,
  "duration": "1h",
  "target": "TAi3T12CwHx…",
  "priceTrx": 4.55,
  "balanceTrx": 4122.11,
  "expiresAt": "2026-07-22T15:04:05Z"
}
```

### GET /v1/rentals/{orderNo}

Order status. Poll (e.g. every 2 s) until `active` or `failed`.

```json
{
  "orderNo": 42,
  "status": "active",
  "txid": "b85bc8cb…",
  "resource": "ENERGY",
  "amount": 65000,
  "duration": "1h",
  "target": "TAi3T12CwHx…",
  "priceTrx": 4.55,
  "expiresAt": "2026-07-22T15:04:05Z"
}
```

---

## Which resource does a transfer need?

| Your outgoing transfer | Rent | Sizing |
|---|---|---|
| **USDT (or any TRC-20)** | `ENERGY` | Use `POST /v1/cost`: 65,000 if the recipient holds USDT, 131,000 if fresh. Bandwidth for the tx (~345) is usually covered by TRON's free 600/day per address. |
| **TRX (native)** | `BANDWIDTH` | ~270 bandwidth per TRX transfer. The minimum order (1,000) covers ~3 transfers; batch several sends from the same address under one rental. |

**Important:** the rental is delegated to the **sending** address — the address that will
broadcast the transfer (your deposit address when consolidating; your hot/withdrawal
wallet when paying out). `POST /v1/cost` targets are the **recipients** of a USDT
transfer, used only to size the energy need.

---

## Typical integration loop

Whatever you're automating (sweeps, payouts, batch sends), the loop is the same:

1. `POST /v1/cost` with the recipient(s) of your upcoming USDT transfer(s) → learn
   whether each needs 65K or 131K energy. (TRX transfers: skip this, rent BANDWIDTH.)
2. `POST /v1/rent` for the exact amount to the **sending** address, with your own
   operation id as `reference`.
3. Poll `GET /v1/rentals/{orderNo}` → `active` (typically a few seconds).
4. Broadcast your transfer — it consumes the delegated resource, burns 0 TRX.
5. Nothing to clean up: the stake auto-reclaims when the window ends.

Keep the account funded via the deposit address (`GET /v1/deposit`); watch
`GET /v1/balance` and top up below your working threshold. Use `reference` on every rent
so network retries can never double-charge you.

---

## Changelog

- **v1 (2026-07-22)** — initial release: balance, deposit, quote, cost, rent, order
  status; request-based onboarding.