Orders

Every API order is charged to your account balance at the moment it is created — the price is locked, the balance is debited and the order is Paid in one step. Delegation starts immediately; there is no undo for API orders. Follow the order by webhook or by polling.

Create an order#

POST /v1/orders (Order)

{"external_id": "inv-1001",
 "energy_address": "TXYZ…",
 "usdt_to_address": "TABC…",
 "energy": 65000,
 "term": "1h",
 "charge_asset": "TRX",
 "max_price_trx": "2.5",
 "callback_url": "https://shop.example/hooks/energy"}

The answer is the Order with "replayed": false and status Paid (in test mode: Completed).

Typical refusals: not enough balance ⇒ 45009; invalid address ⇒ 45003; energy out of range ⇒ 45004 / 45005; term unavailable ⇒ 45006; ordering paused ⇒ 45001; charge_asset: "USDT" without a USDT rate ⇒ 45017.

Idempotency#

external_id is unique per key:

• The same external_id with the same request returns the original order with "replayed": true — you are never charged twice.
• The same external_id with a different request ⇒ 45010 (HTTP 409). "Different" means a different energy_address, usdt_to_address, energy, term, charge_asset or test mode; max_price_trx and callback_url are not compared.

Always retry a timed-out create with the same external_id. If the first call did go through, the retry tells you so; if it did not, the retry creates the order.

Price ceiling#

Prices follow the market. Pass max_price_trx to make sure an order never costs more than you expect: when the price we would lock is higher, the order is refused with 45014 (HTTP 409) and nothing is created. The current price comes back in data:

{"code": 45014, "message": "the current price is above max_price_trx", "data": {"price_trx": "2.6"}}

Batch#

POST /v1/orders/batch (Order) — {"orders": [ …1 to 50 order bodies… ]}

1. Every item is validated and priced first.

2. Then one balance check: the total of the new items (not replays, not test orders) per asset must fit your available balance. If it does not, nothing is created — 45009 (HTTP 400) with what was needed and what you have:

   JSONCopy

   {"code": 45009, "message": "insufficient balance",
    "data": {"needed": {"TRX": "20.8", "USDT": "0"}, "available": {"TRX": "12.5", "USDT": "0"}}}

3. Otherwise each item is created on its own: a failing item (bad address, external_id conflict, price above its max_price_trx, …) is reported in its result and does not affect the others. The call answers HTTP 200:

{"created": 2, "replayed": 0, "failed": 1,
 "results": [
   {"index": 0, "external_id": "a", "ok": true, "replayed": false, "order": {"…": "…"}, "error": null},
   {"index": 1, "external_id": "b", "ok": false, "replayed": false, "order": null,
    "error": {"code": 45003, "message": "invalid TRON address"}},
   {"index": 2, "external_id": "c", "ok": true, "replayed": false, "order": {"…": "…"}, "error": null}]}

Fewer than 1 or more than 50 items ⇒ 42200.

Test mode#

Add the header X-Test-Mode: 1 to POST /v1/orders or POST /v1/orders/batch:

• nothing is charged and nothing is delegated; no balance is needed;
• the order is stored with "test_mode": true and "charge_amount": "0";
• it goes Paid → Fulfilling → Completed within the same request, with delegation_tx_id: "TEST-<32 hex>";
• your webhooks fire (order.paid, order.fulfilling, order.completed) exactly as for real orders;
• the price is quoted from our price rules even when a term is not orderable right now.

Test orders share the external_id space of your key and show up in reads and exports with test_mode: true. Quick rent does not support test mode (45216).

Read orders#

The list covers all your orders — API, website and quick rent. Filters are optional; start_time / end_time are ISO-8601, test_mode is true or false.

Export#

GET /v1/orders/export?status=&start_time=&end_time= (Read) answers text/csv (not an envelope), at most 10,000 rows. When the export was cut, the response carries X-Truncated: true — narrow the time range and export again. Columns:

order_no,external_id,test_mode,created_at,status,energy_address,usdt_to_address,energy,term,charge_asset,charge_amount,price_trx,delegation_tx_id,delegation_expires_at,failure_reason

The order object#

{"order_no": "EN-7KQ2M4X9WB", "external_id": "inv-1001", "status": "Completed",
 "test_mode": false, "fulfil_unknown": false,
 "energy_address": "TXYZ…", "usdt_to_address": null, "resource": "ENERGY",
 "energy": 65000, "term": "1h",
 "charge_asset": "TRX", "charge_amount": "2.08", "price_trx": "2.08", "price_usdt": "0.62",
 "usdt_trx_rate": "3.39",
 "delegation_tx_id": "9c1f…", "delegation_expires_at": "2026-10-13T09:00:03Z",
 "failure_reason": "",
 "created_at": "…Z", "paid_at": "…Z", "completed_at": "…Z", "closed_at": "…Z"}

Create answers also carry replayed (see Idempotency).