Orders — API reference

Buying and inspecting rentals. There is no single-order cancel in v1: POST /v1/orders charges synchronously, so an order is never left sitting unpaid in a queue and created is barely observable. 3002 order_not_cancellable belongs to POST /v1/batches/{id}/cancel, where receivers that have already been picked up cannot be pulled back.

Generated from openapi.yaml at build time. Base URL https://api.tenergy.me/v1, or https://api-nile.tenergy.me/v1 on Nile (Environments). Every request below is signed as in Authentication unless its Auth line says otherwise.

List orders

GET /v1/orders · listOrders

Auth: API key (HMAC).

Newest first. Filters combine with AND.

format=csv answers text/csv with every matching order rather than one page (limit and cursor are ignored), streamed, with the same fields as the JSON list: one column per Order field in contract order, activation.* and failure.* flattened, delegate_hashes space-separated. A text cell that begins with =, +, -, @, a tab or a carriage return is prefixed with ' so a spreadsheet does not run it as a formula.

Parameters

Responses

Response fields

Create an order

POST /v1/orders · createOrder

Auth: API key (HMAC).

Buys a rental for one receiver and charges the account balance. A tier whose GET /v1/prices row says available: false (energy 1d while switched off) is refused with 2003 tier_unavailable before anything is charged.

The response is not a delivery receipt. A 201 means the order was accepted, paid for and handed to the supply layer; status tells you how far it got by the time the response was written. In the common case delivery is synchronous and you get back a delivered order with delegate_hash populated within a few seconds — status: "confirmed" if the response is written in the same instant the delivery is verified, active thereafter, which is the value you will normally see. Treat confirmed and active alike: both mean the resource is on the receiver. When the supply layer needs longer, you get status: "allocating" and no hash yet — poll GET /v1/orders/{id} or, better, subscribe to the order.confirmed webhook.

Check partial. An order whose allocations only partly landed comes back confirmed/active with partial: true, delivered_amount below amount and the difference already refunded. It is not a separate state and it is not a failure.

Idempotency. Always send client_order_id. A repeat with the same id returns the original order with HTTP 200 and charges nothing. This is the correct response to a network timeout: retry verbatim rather than creating a second order.

Price protection. Either pass quote_id (charged exactly the quoted total) or max_price_sun (rejected with 3006 price_above_limit if the live price is higher). With neither, you are charged the live price whatever it is.

Activation. If receiver is not activated on chain, the platform activates it and adds activate_amount_sun to the charge. Set activate: false to refuse that: the order is then rejected with 3004 receiver_not_activated and nothing is charged.

Parameters

Request body

JSON (OrderRequest), required.

Example request body, from the contract (illustrative values):

{
  "client_order_id": "acme-2026-09-11-000418",
  "resource": "energy",
  "amount": 65000,
  "tier": "1h",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "activate": true
}

Responses

Response fields (Order)

Order detail

GET /v1/orders/{orderId} · getOrder

Auth: API key (HMAC).

The order plus two breakdowns only this endpoint carries. fills is the priced walk: how much came from each price class and at what unit price. delegations is what reached the receiver on chain: one row per delegation with its tx id. No supplier is named.

Parameters

Responses

Response fields

Return the resource before expiry

POST /v1/orders/{orderId}/reclaim · reclaimOrder

Auth: API key (HMAC).

Undelegates the resource early. Useful once the transaction you rented for has landed: the energy stops sitting idle and the inventory can serve someone else.

No refund. Renting and returning are separate operations; returning early does not undo the payment. Reclaim exists so that high-volume users free inventory, not to buy time back.

Idempotent. Calling it twice returns the same reclaim_hash and changes nothing. An order that already expired on its own also answers 200.

Per order, not per address. One address may hold resource from several orders, possibly belonging to other accounts. To free an address completely, reclaim each of its orders.

Orders filled from a third-party provider instead of our own stake cannot be reclaimed — those resources are not ours to return. Such an order answers 3008 reclaim_unavailable.

Parameters

Responses

Response fields (Order)

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "id": "ord_01J9Z5P8T3WQ",
  "client_order_id": "acme-2026-09-11-000418",
  "account_id": "acc_01J9Z4K2M7Q8",
  "resource": "energy",
  "amount": 65000,
  "delivered_amount": 65000,
  "partial": false,
  "tier": "1h",
  "duration_seconds": 3600,
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "source": "api",
  "status": "reclaimed",
  "confirm_status": "confirmed",
  "price_sun_per_unit": 20,
  "pay_amount_sun": 1300000,
  "activate_amount_sun": 0,
  "total_amount_sun": 1300000,
  "refunded_amount_sun": 0,
  "delegate_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "delegate_hashes": ["a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"],
  "delegated_at": "2026-09-11T18:04:07.900Z",
  "reclaim_hash": "51fa77da06e8fbebf504fbf088d1d9611059398d51fa77da06e8fbebf504fbf0",
  "reclaimed_at": "2026-09-11T18:12:31.000Z",
  "expires_at": "2026-09-11T19:04:07.900Z",
  "activation": {"performed":false,"hash":null,"amount_sun":0},
  "created_at": "2026-09-11T18:04:05.400Z",
  "updated_at": "2026-09-11T18:12:31.000Z",
  "failure": null
}