> 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/quote.md). # Quote a Purchase ## Quote a Purchase Prices a rental and holds that price for a short window. Free, and never charged. Quoting is optional — [`POST /v1/orders`](/api-reference/create-order.md) prices and buys in one call. Quote first when you want to see the number before committing, show it to somebody, or fix it while the rest of your flow runs. Rate limit: **120 quotes per minute** per project. Quoting is free to you and costs us a supplier call to price, which is the only reason there is a ceiling at all. Orders are not throttled. #### **Quote a Purchase** `POST` `https://energy.crypto-chief.com/v1/quotes` **Headers** | Name | Value | | ------------ | --------------------------------------------------------- | | Merchant | Your project UUID | | Signature | [Signed request body](/getting-started/authentication.md) | | Content-Type | `application/json` | **Body** | Name | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `receive_address` | string | true | The TRON address the energy is delegated to — the **sender** of the upcoming transfer, not the recipient of the tokens. | | `energy` | integer | false | Leave it out and we read the recipient and size the order. Supply it only when you know better; see [How Energy Works](/getting-started/how-energy-works.md). | | `duration_sec` | integer | false | How long you need it. Default `3600` (one hour). | {% hint style="warning" %} `receive_address` is the wallet that will **send** the USDT. Energy is delegated to the account that spends it. Sending your customer's address here buys energy for them, not for you. {% endhint %} ```json { "receive_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" } ``` **Response** {% tabs %} {% tab title="200" %} ```json { "ref": "q_7bxk4m2npqrs8tvw3yz5a6c9d1e4f7g2", "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", "recipient_state": "cold", "burn_price_sun": 13028500, "burn_price_trx": "13.028500", "burn_price_usd": "3.91", "burn_price_credits": 39085500, "saving_trx": "7.100532", "saving_usd": "2.13", "saving_credits": 21301596, "expires_at": "2026-08-30T11:43:37Z", "expires_in_sec": 90 } ``` {% endtab %} {% tab title="409" %} ```json { "ok": false, "error": "NOT_WORTH_RENTING", "msg": "renting is not cheaper than burning TRX right now, so we are not selling it to you" } ``` {% endtab %} {% tab title="401" %} ```json { "ok": false, "error": "INVALID_SIGNATURE", "msg": "signature mismatch" } ``` {% endtab %} {% endtabs %} **Fields** | Field | Description | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `ref` | Pass to [`POST /v1/orders`](/api-reference/create-order.md) as `quote_ref` to buy at this price. | | `energy` | What we will buy. Ours if you left `energy` out, yours if you supplied it. | | `recipient_state` | `warm`, `cold` or `unknown` — why the energy figure is what it is. | | `price_sun` / `price_trx` | What you pay. The integer is authoritative. | | `price_usd` | The same price in dollars, at `trx_usd`. | | `credits` | **What this will cost your balance.** Computed exactly the way the charge is, so it is the number to compare against `credits_balance`. | | `trx_usd` | The TRX rate the dollar and credit figures were converted at. | | `burn_price_sun` / `burn_price_trx` / `burn_price_usd` / `burn_price_credits` | What the same energy would cost burnt at the chain's current rate. | | `saving_trx` / `saving_usd` / `saving_credits` | The difference, so it is checkable rather than claimed. | | `expires_at` / `expires_in_sec` | How long we stand behind this price. | ### 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/quotes", { method: "POST", body: raw, // send exactly what you signed headers: { Merchant: MERCHANT, Signature: sign(body, API_KEY), "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/quotes"); 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), ], ]); 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/quotes", bytes.NewReader(raw)) req.Header.Set("Content-Type", "application/json") req.Header.Set("Merchant", merchant) req.Header.Set("Signature", sign(raw, apiKey)) 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/quotes", data=raw, # send exactly what you signed headers={ "Content-Type": "application/json", "Merchant": MERCHANT, "Signature": sign(body, API_KEY), }, ) print(res.json()) ``` {% endtab %} {% tab title="curl" %} ```bash BODY='{"receive_address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"}' curl "$BASE/v1/quotes" \ -H "Content-Type: application/json" \ -H "Merchant: $MERCHANT" \ -H "Signature: $(sign "$BODY")" \ -d "$BODY" ``` {% endtab %} {% endtabs %} ### The dollar figures are an estimate, the order's are a record A quote has not been charged, so its `price_usd` is a conversion at the rate shown in `trx_usd`. The `price_usd` on an [order](/api-reference/create-order.md) is different in kind: it is read back from what was actually taken, at the rate that was actually used. If no rate is available, the dollar fields and `trx_usd` are **omitted** rather than filled with a guess. `price_sun` is always there. ### The quote is spent once A quote becomes exactly one order. Redeeming it a second time returns `409 QUOTE_ALREADY_USED` — a committed price cannot become several purchases. The one exception is a retry of the **same** order: if your request timed out after the quote was consumed, resending with the same `Idempotency-Key` succeeds, because it was your order that spent it. ### If it expires `409 QUOTE_EXPIRED`. Ask for a new one — the price moves with the energy market, so a lapsed quote is a number we can no longer honour. Quotes live about 90 seconds.