Refills — API reference

Restore a receiver’s USED energy or bandwidth now (it does not raise the limit). Bought from the cheapest venue whose size range covers the amount; you pay the venue price plus your routing fee (the same fee tiers as orders). Charged when created; once the venue reports, the part it did not restore is refunded at the charged unit price. Uses the orders.create / orders.read scopes. Answers 3033 refills_unavailable while no venue is enabled on the deployment.

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 refills

GET /v1/refills · listRefills

Auth: API key (HMAC).

Newest first. Filters combine with AND.

Parameters

Responses

Response fields (RefillList)

Create a refill

POST /v1/refills · createRefill

Auth: API key (HMAC).

Quotes every enabled venue for amount, picks the lowest TOTAL cost (unit price x amount + the venue’s fixed fee) among venues whose size range covers amount, charges the balance and places the order. One refill is one venue; it is never split.

Refused before any charge: 2008 amount_out_of_range when amount is outside the accepted range for the resource (details.min_amount, details.max_amount, also published in GET /v1/prices under refills) or above what the receiver has used now (details.restorable_max); 3036 nothing_to_refill when the receiver has used nothing (or less than the smallest refill); 3035 no_base_resource when it has no limit at all; 3033 refills_unavailable when no venue is enabled or none answered.

status: paid (charged) -> submitted (venue order placed) -> completed (venue reported; restored_amount set, the unrestored part refunded in refunded_sun) | failed (fully refunded). Webhooks refill.completed, refill.failed. Idempotent on client_order_id / Idempotency-Key like orders: the same body returns 200 and the original.

Parameters

Request body

JSON (RefillRequest), required.

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

{
  "client_order_id": "acme-refill-000001",
  "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "resource": "energy",
  "amount": 300000
}

Responses

Response fields (Refill)

Refill detail

GET /v1/refills/{refillId} · getRefill

Auth: API key (HMAC).

A submitted refill is brought up to date with its venue on every read.

Parameters

Responses

Response fields (Refill)