Changelog

Changes to the API contract (openapi.yaml), newest first. Everything below is additive unless the entry says otherwise; nothing was renumbered.

2026-10-09 — Address usage

New GET /v1/resources/{address}/usage?days=7|30, public: what an address used and burned on the transactions it sent over that many UTC days, today included — transactions, usdt_transfers, out_of_energy, energy_used, energy_burned_sun, bandwidth_burned_sun and the same per day (per_day). Up to 2,000 transactions are read; capped: true means there were more and the totals are a lower bound.
Answers are cached for 5 minutes per address and period. A burst of new addresses can answer 429 with retry_after; a bad address or period is 400.

New GET /v1/market/justlend, public: what renting energy on JustLend DAO costs — the rent rate at 65,000 energy, energy per staked TRX, the contract owner’s energy today and its share of each call, burn prices, and the energy and bandwidth of the rent and return calls. A recent read can come back with stale: true.

Order and the order.confirmed webhook carry savings: burn_alternative_sun (delivered energy × the network’s burn price), paid_sun, saved_sun, saved_pct. It is null before confirmation, for bandwidth and activation orders, and when the burn price cannot be read; saved_sun can be negative.
New GET /v1/market/summary?month=YYYY-MM, public: per provider, the month’s samples, share of good reads, 1-hour and 1-day {min, median, max}, and the median 1-hour price by UTC hour. GET /v1/market/history?slug=tenergy now returns our own recorded prices.

Every row of GET /v1/prices carries available. A tier that is not on sale right now answers orders, quotes and estimates with 2003.

POST /v1/api-keys works on an unfunded account: sign up, create a key, read the deposit address with GET /v1/deposit-addresses and top up automatically. Orders still need the balance (4001 insufficient_funds).
3016 account_unfunded is no longer returned by any route. The code stays reserved.

GET /v1/resources/{address} needs no credentials. An anonymous call runs on the per-IP budget and gets our_active_orders: []; a signed call is verified in full and lists that account’s orders.
The prices.read scope now guards POST /v1/estimate/transfer only.

PriceTable gains schedule[]: id, label, start_utc_minute, end_utc_minute, factor_bps and the 1h energy price_sun_per_unit (null when not on sale) for every period of the day, so a price map renders the whole day from one call.
period comes from the same table. Its ids and bounds changed: drop, off_peak, ramp_9, ramp_11, ramp_12, peak, peak_late. Iterate the schedule; never hardcode its ids or count.

GET /v1/prices and GET /v1/estimate need no credentials. Anonymous calls run on a per-IP budget; a signed call is verified in full (a bad signature is still 401) and runs on the key’s budget.
A signed GET /v1/estimate is priced for its own account, so a contract customer sees the contract price; an anonymous one gets the retail price.

API key format (changes what new key ids look like): ak_live_ + 24 random bytes (base64url) for the id and sk_live_ + 256 bits for the secret; ak_test_ / sk_test_ on the Nile host. The prefix names the environment. A key sent to the other environment’s host is refused with the new 1012 key_environment_mismatch before it is looked up. Keys issued earlier keep their ids and keep working.
label is optional on POST /v1/api-keys, defaulting to Key N. scopes is unchanged: required, with no default.
Active-key limit. GET /v1/api-keys returns limit and used; past the limit, creation answers the new 3017 api_key_limit_reached.
ApiKey.last_used_ip alongside last_used_at, both written at most once a minute per key.
Dashboard session: POST, GET and DELETE /v1/session and POST /v1/session/refresh, authenticated by an httpOnly cookie plus X-CSRF-Token on writes (1013 session_expired, 1014 csrf_token_invalid). A browser credential only; it carries no API-key scopes.
PATCH /v1/account sets display_name, published on Account next to label with the same value.

Order states: created → paid → allocating → delegated → confirmed → active → expired | reclaimed, with failed and refunded as terminal branches — ten names, the same in every enum, example and webhook.
Order gains partial and delivered_amount: partial delivery is a field on a confirmed/active order, not a state.
New webhook event order.refunded. order.confirmed carries partial, delivered_amount and refunded_amount_sun.
There is no single-order cancel in v1; 3002 order_not_cancellable belongs to POST /v1/batches/{id}/cancel.
Signup by address challenge: POST /v1/accounts/challenge, POST /v1/accounts/challenge/verify (returns a 15-minute bootstrap token), POST /v1/accounts, GET /v1/accounts/deposit-address. Account.status is unfunded | active | suspended | closed. New codes 1010 challenge_invalid, 1011 bootstrap_token_expired, 3016 account_unfunded.
Scopes: one area.action vocabulary (ApiKeyScope). scopes is required on key creation and has no default.
Nile differs from mainnet; see Environments.
Examples use illustrative placeholder prices; live prices come from GET /v1/prices.