> For the complete documentation index, see [llms.txt](https://tron-energy-doc.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tron-energy-doc.crypto-chief.com/api-reference/create-order.md). # Create an Order ## Create an Order Buys energy and delegates it to the address you name. This is the only charged endpoint. The call is synchronous: by the time it answers, the energy is on the address or you know why it is not. #### **Create an Order** `POST` `https://energy.crypto-chief.com/v1/orders` **Headers** | Name | Value | | --------------- | --------------------------------------------------------- | | Merchant | Your project UUID | | Signature | [Signed request body](/getting-started/authentication.md) | | Content-Type | `application/json` | | Idempotency-Key | **Required.** Your own id for this piece of work | **Body** Two ways to call it. Either redeem a quote, or describe the purchase and have it priced now. | Name | Type | Required | Description | | ----------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------- | | `quote_ref` | string | false | Buy at a price already quoted. When present, the quote's terms win and the fields below are ignored. | | `receive_address` | string | conditional | Required unless `quote_ref` is given. The wallet that will **send** the transfer. | | `energy` | integer | false | Leave out to have us size it from the recipient. | | `duration_sec` | integer | false | Default `3600`. | | `idempotency_key` | string | false | Alternative to the header. The header wins if both are sent. | {% tabs %} {% tab title="Priced now" %} ```json { "receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" } ``` {% endtab %} {% tab title="From a quote" %} ```json { "quote_ref": "q_7bxk4m2npqrs8tvw3yz5a6c9d1e4f7g2" } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "id": 4471, "idempotency_key": "payout-8814", "status": "delivered", "receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "energy": 130285, "duration_sec": 3600, "price_sun": 5927968, "price_trx": "5.927968", "price_usd": "1.78", "credits": 17783904, "trx_usd": "0.30000000", "delivered_energy": 130285, "settled": true, "needs_attention": false, "created_at": "2026-08-30T11:42:07Z", "delivered_at": "2026-08-30T11:42:11Z" } ``` {% endtab %} {% tab title="402" %} ```json { "ok": false, "error": "INSUFFICIENT_CREDITS", "msg": "your credit balance will not cover this order; nothing was bought and nothing was charged" } ``` {% endtab %} {% tab title="409" %} ```json { "id": 4472, "idempotency_key": "payout-8815", "status": "unresolved", "settled": false, "needs_attention": true, "error": "context deadline exceeded" } ``` {% endtab %} {% tab title="502" %} ```json { "id": 4473, "idempotency_key": "payout-8816", "status": "refused", "settled": true, "needs_attention": false, "error": "insufficient supplier balance" } ``` {% endtab %} {% endtabs %} **Fields** | Field | Description | | ------------------------- | ----------------------------------------------------------------------------- | | `status` | `delivered`, `refused` or `unresolved`. | | `settled` | The outcome is final, either way. | | `needs_attention` | We do not know the outcome. **Do not retry.** | | `delivered_energy` | What actually landed on the address. | | `price_sun` / `price_trx` | The price of the energy. The integer is authoritative. | | `credits` | **What was actually taken from your balance.** Absent if nothing was charged. | | `price_usd` | The same charge in dollars, from `credits`. Absent if nothing was charged. | | `trx_usd` | The TRX rate the charge was computed at. | | `error` | Why, when there is a why. | {% hint style="info" %} `credits` and `price_usd` are recorded at the moment of the charge, so they do not drift when you read the order later. `trx_usd` is the rate that was used. All three are absent on an order nobody was charged for: a refusal, or one that never got that far. They are omitted rather than sent as zero, because a zero `price_usd` reads as "this was free". {% endhint %} {% hint style="info" %} Branch on `settled` and `needs_attention` rather than parsing `status`. {% endhint %} ### Example `sign()`, `canonical()`, `BASE`, `MERCHANT` and `API_KEY` are from [Authentication](/getting-started/authentication.md). {% tabs %} {% tab title="JavaScript" %} ```javascript const body = { receive_address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }; const raw = canonical(body); // sorted keys, no whitespace const res = await fetch(BASE + "/v1/orders", { method: "POST", body: raw, // send exactly what you signed headers: { Merchant: MERCHANT, Signature: sign(body, API_KEY), "Idempotency-Key": "payout-8814", "Content-Type": "application/json", }, }); console.log(await res.json()); ``` {% endtab %} {% tab title="PHP" %} ```php $body = ['receive_address' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t']; $raw = canonical($body); // ksort + json_encode $ch = curl_init(BASE . "/v1/orders"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $raw, // send exactly what you signed CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Merchant: ' . MERCHANT, 'Signature: ' . sign($body, API_KEY), 'Idempotency-Key: payout-8814', ], ]); print_r(json_decode(curl_exec($ch), true)); ``` {% endtab %} {% tab title="GO" %} ```go body := map[string]any{"receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} raw, _ := json.Marshal(body) // Marshal sorts map keys for you req, _ := http.NewRequest("POST", base+"/v1/orders", bytes.NewReader(raw)) req.Header.Set("Content-Type", "application/json") req.Header.Set("Merchant", merchant) req.Header.Set("Signature", sign(raw, apiKey)) req.Header.Set("Idempotency-Key", "payout-8814") res, err := http.DefaultClient.Do(req) ``` {% endtab %} {% tab title="Python" %} ```python body = {"receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} raw = json.dumps(body, separators=(",", ":"), sort_keys=True) res = requests.post( BASE + "/v1/orders", data=raw, # send exactly what you signed headers={ "Content-Type": "application/json", "Merchant": MERCHANT, "Signature": sign(body, API_KEY), "Idempotency-Key": "payout-8814", }, ) print(res.json()) ``` {% endtab %} {% tab title="curl" %} ```bash BODY='{"receive_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}' curl "$BASE/v1/orders" \ -H "Content-Type: application/json" \ -H "Merchant: $MERCHANT" \ -H "Signature: $(sign "$BODY")" \ -H "Idempotency-Key: payout-8814" \ -d "$BODY" ``` {% endtab %} {% endtabs %} ### Read the HTTP status, not just the body | Status | Meaning | Retry? | | ------------------------- | ----------------------------------------------- | ---------------- | | `200` | Delivered | Done | | `402` | You cannot pay. Nothing bought, nothing charged | After topping up | | `409` `NEEDS_ATTENTION` | Unresolved — may have been delivered | **No** | | `409` `NOT_WORTH_RENTING` | Renting is not cheaper than burning today | Later | | `502` | A supplier declined. Nothing bought | Yes | The distinction between `409 NEEDS_ATTENTION` and `502` is the one worth coding against: one means *do not touch this*, the other means *nothing happened, go ahead*. ### Retrying Send the same `Idempotency-Key` and you get the same order back, charged once. See [Idempotency and Retries](/getting-started/idempotency.md) — particularly before writing an automatic retry. ### After it lands Send your transfer. It consumes the delegated energy instead of burning TRX. Anything unused returns to us when the window closes. If the transfer still fails, check bandwidth: it is a separate resource this API does not rent, and a wallet with none and no TRX fails even with energy delegated. [How Energy Works](/getting-started/how-energy-works.md) covers it.