TET TRON ENERGY TERMINAL

API quickstart · buyer flow

Place your first buyer order through the API

This path uses the current public market endpoints and the buyer order contract. You create the credential in a signed-in browser, keep its one-time secret outside source control, inspect the live book, verify platform credit, and then submit one idempotent order.

Open API key dashboard API reference

  1. Create a Read + Buy key in the dashboard

    Connect and sign in with your TRON wallet, open the API key dashboard, and create a key with Read and Buy enabled. Key creation is a browser-session action; an API key cannot mint another key or grant itself more scope.

    The full secret is shown exactly once. Copy it to a secret manager or a temporary shell environment, never a URL, log, screenshot, repository, or client-side bundle. If it is lost, revoke the key and create another.

  2. Read the live public price and one depth ladder

    These GET endpoints need no credential. Price is scoped by resource; depth is also scoped by rental duration and minimum lot. The returned asks are the live limits to inspect before choosing price_sun.

    curl --silent --show-error --fail-with-body \
  'https://tet.energy/v1/price?resource=energy'

curl --silent --show-error --fail-with-body \
  'https://tet.energy/v1/market/depth?resource=energy&duration=86400&min_lot=65000'

  3. Confirm spendable platform credit

    Use the same key's Read scope to inspect available_trx. The sample order reserves 4.225 TRX from the internal available balance: 65 sun × 65,000 energy × one billable day.

    curl --silent --show-error --fail-with-body \
  'https://tet.energy/v1/balance' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
    The internal balance is not the TRX balance shown by the connected wallet. GET /v1/balance conditionally returns a personal deposit_address and the exact deposit_minimum_trx. Fund only when both are present: send at least that minimum as real TRX to deposit_address, then wait for confirmations before spending. Never send funds to the sign-in wallet; withdrawals are not available.

  4. Submit the order with a unique idempotency key

    Replace all three placeholders. The JSON contains only the five required OrderCreate fields. The sample uses the one-day energy floor of 65 sun; it can remain open when no ask is available at or below that limit, so inspect depth rather than treating the example as a fill quote.

    curl --silent --show-error --fail-with-body \
  -X POST 'https://tet.energy/v1/orders' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "resource": "energy",
    "amount": 65000,
    "duration_sec": 86400,
    "price_sun": 65,
    "receiver_address": "<VALID_TRON_RECEIVER_ADDRESS>"
  }'

    A first creation returns HTTP 201. An exact replay with the same Idempotency-Key and body returns the existing order with HTTP 200.

    Required request fields

    resource
    energy or bandwidth.
    amount
    A positive integer number of resource units.
    duration_sec
    One currently offered duration in seconds; 86400 is one day.
    price_sun
    Your limit in sun per resource unit per billable day, at or above the current floor.
    receiver_address
    A valid base58 TRON address that receives the delegated resource. It may differ from the wallet used to sign in.
    Retry rule. Reuse the same key only when retrying the exact same body after an uncertain response. Use a new key for a new logical order; reusing one key with a different body returns a conflict.

Troubleshooting the current error contract

Every failure uses the same error envelope. Keep request_id and the X-Request-ID response header when asking for support; neither contains your secret.

{
  "error": {
    "code": "<ERROR_CODE>",
    "message": "<MESSAGE>",
    "request_id": "<REQUEST_ID>"
  }
}
401 · unauthorized
The Bearer header is missing or the credential failed authentication. All malformed, unknown, wrong-body, and revoked keys intentionally look identical. Never send api_key in the query string.
403 · forbidden
The key authenticated but lacks the required scope. Create a new Read + Buy key in the signed-in dashboard; a key cannot upgrade itself.
402 · insufficient_balance
available_trx cannot cover the escrow reservation. Wallet TRX does not satisfy this internal-ledger check.
422 · invalid_request
The request failed validation. When error.details is present it names field paths; service-level validation may return only the message. Check the offered duration, price floor, positive integers, and receiver address.
409 · conflict
The same idempotency key was used with a different order body. Do not mutate a retry; start a new logical order with a new key.
429 · rate_limited
Stop sending requests, honor the Retry-After header, and retry with backoff.
503 · unavailable
The service or required live network ratio is temporarily unavailable. Retry later; do not substitute a guessed price or ratio.