Account — API reference

Who am I, what is my balance, where do I send money.

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.

Account information

GET /v1/account · getAccount

Auth: API key (HMAC) or bootstrap token.

Identity, balances, deposit addresses, the limits in force and lifetime counters.

Also readable with a bootstrap token (Authorization: Bearer abt_…), so the signup flow can poll for the first confirmed deposit without an API key.

Responses

Response fields (Account)

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "id": "acc_01J9Z4K2M7Q8",
  "brand": "tenergy.me",
  "network": "mainnet",
  "label": "Acme payments",
  "status": "active",
  "balance_sun": 1250400000,
  "balance_usdt": 0,
  "reserved_sun": 0,
  "deposit_addresses": [{"currency":"TRX","address":"TDepositAddressExample1111111111111"}],
  "limits": {"max_order_energy":3000000,"max_batch_receivers":100,"orders_per_second":30},
  "totals": {
    "deposited_sun": 5000000000,
    "spent_sun": 3749600000,
    "refunded_sun": 0,
    "orders_created": 1842,
    "energy_delegated": 119730000
  },
  "created_at": "2026-04-02T09:11:00.000Z"
}

Edit the account’s display name

PATCH /v1/account · updateAccount

Auth: Dashboard session cookie + X-CSRF-Token.

The account’s own title, shown wherever the account is named. null clears it and the display falls back to the shortened owner address — never to an internal id.

A dashboard session operation, and the account’s owner: the title is what every member sees and what support reads back in a ticket. It is a setting; nothing about who may reach what changes here.

Request body

JSON (AccountPatch), required.

Responses

Response fields (Account)

Balances only

GET /v1/balance · getBalance

Auth: API key (HMAC).

A deliberately small response for callers that poll before every order. Cheaper than /account and on the read rate-limit budget.

Responses

Response fields (Balance)

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "balance_sun": 1250400000,
  "balance_usdt": 0,
  "reserved_sun": 0,
  "available_sun": 1250400000,
  "as_of": "2026-09-11T18:04:05.123Z"
}

Deposit addresses for this account

GET /v1/deposit-addresses · listDepositAddresses

Auth: API key (HMAC).

The account’s own deposit address: a TRON address that belongs to this account alone, so no memo is needed (memo is always null). Two rows, same address: TRX, and USDT (TRC-20, contract), which the ledger credits as TRX at rate_now minus spread_bps, between min and max USDT. The address is issued on the first read if the account has none yet.

A TRX deposit is credited after block confirmations that depend on its amount (confirmation_tiers); the wait is counted from sending the payment: about 3 s for the transaction to get into a block, then 3 s per confirmation.

A USDT deposit waits 19 confirmations (~1 min). confirmations_required is the most a deposit waits. Every credit produces a balance.credited webhook.

Support can replace the address (never the customer; at most once per rotation.min_interval_days and rotation.max_per_window times per rotation.window_days). A replaced address is listed under retired and still credits until credited_until (rotation.retired_credit_days after it was retired).

Responses

Response fields

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "data": [
    {
      "currency": "TRX",
      "address": "TDepositAddressExample1111111111111",
      "memo": null,
      "confirmations_required": 19
    }
  ],
  "retired": [
    {
      "address": "TRetiredAddressExample111111111111",
      "retired_at": "2026-09-20T10:00:00.000Z",
      "credited_until": "2026-10-20T10:00:00.000Z"
    }
  ],
  "rotation": {
    "by": "support",
    "min_interval_days": 7,
    "max_per_window": 3,
    "window_days": 90,
    "retired_credit_days": 30
  }
}

The account’s withdrawals, newest first

GET /v1/withdrawals · listWithdrawals

Auth: Dashboard session cookie + X-CSRF-Token.

Responses

Response fields

Withdraw the balance to the owner wallet

POST /v1/withdrawals · createWithdrawal

Auth: Dashboard session cookie + X-CSRF-Token.

Sends amount_sun from the account’s balance back to a wallet that topped it up — to_address, one of GET /v1/withdrawals/sources — and at most what that wallet paid in, less what already went back to it. Money received from other wallets buys energy but is not withdrawn to a wallet that did not send it (3024 withdrawal_destination_not_allowed). Without to_address: the owner address, or the only source. A flat fee (1 TRX) is taken on top, and the balance is debited at once. One withdrawal at a time: a second one while the first is open answers 3023 withdrawal_in_progress.

Most withdrawals are paid out automatically within a minute. A large one, or one above what the account has paid in, waits for a manual check first (awaiting_approval). Signed-in owner only; not available with an API key. With 2-step on, needs a confirmation bound to this amount and destination (1020 step_up_required).

Parameters

Request body

JSON, required.

Responses

Response fields (Withdrawal)

The wallets a withdrawal can go to, and how much each can take

GET /v1/withdrawals/sources · listWithdrawalSources

Auth: Dashboard session cookie + X-CSRF-Token.

Every wallet that paid into the account. available_sun is what may go back to it now: what it paid in, less what already went back to it, never more than the free balance.

Responses

Response fields

The account’s ledger statement

GET /v1/ledger · listLedger

Auth: Dashboard session cookie + X-CSRF-Token.

Every journal that moved this account’s balance, newest first: deposits, order charges, refunds and the rest. amount_sun / amount_usdt are the net effect on the balance — positive when it went up. kind=deposit is the deposit history of the top-up screen.

A deposit appears here once it is credited, i.e. after its confirmations_required block confirmations (by its amount for TRX: 1 up to 200 TRX, 2 up to 1,000, 3 up to 5,000, 19 above; 19 for USDT); a transfer still confirming is not listed yet. sender and block_number are null on deposits credited before 2026-09-25.

Dashboard session only (member role viewer or above). No API-key scope opens it: the ledger shows senders and transaction ids that no key-readable endpoint shows today, and extending balance.read to it is an access decision that has not been taken.

Parameters

Responses

Response fields

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "data": [
    {
      "id": "jrn_01K5Y8Q2V9M3ZP4T7R1A2B3C4D",
      "kind": "order_charge",
      "amount_sun": -3900000,
      "amount_usdt": 0,
      "order_id": "ord_01K5Y8Q2V9M3ZP4T7R1A2B3C4E",
      "deposit": null,
      "created_at": "2026-09-25T10:12:04.000Z"
    },
    {
      "id": "jrn_01K5Y7A1B2C3D4E5F6G7H8J9K0",
      "kind": "deposit",
      "amount_sun": 50000000,
      "amount_usdt": 0,
      "order_id": null,
      "deposit": {
        "txid": "9f3c1e7a2b4d6f8091a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7",
        "sender": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
        "block_number": 61000123,
        "status": "credited",
        "confirmations_required": 19
      },
      "created_at": "2026-09-25T09:58:40.000Z"
    }
  ],
  "next_cursor": null
}

The service fee this account pays

GET /v1/account/fee · getAccountFee

Auth: ApiKey or session.

The rate the next order is charged, the 30-day spend that set it, the next tier and an active promo code. Tiers are by spend over the last 30 days, rolling; a promo code applies when its rate is lower.

Responses

Response fields (AccountFee)

Apply a promo code

POST /v1/account/promo · redeemPromoCode

Auth: Session.

Sets the account’s service fee to the code’s rate for the code’s term (30 days by default), unless the tier by volume is lower. One code is active at a time: a new code replaces the old one. Entering the active code again changes nothing. Refusals: 3027 promo_not_found (404) and 3028 promo_unavailable (409) with details.reason: inactive, not_started, ended or used_up. Dashboard sign-in only.

Request body

JSON, required.

Responses

Response fields (AccountFee)

The account’s address book

GET /v1/account/addresses · listAddressBook

Auth: Dashboard session cookie + X-CSRF-Token.

Receivers this account saved for reuse, newest first. At most limit (100) entries.

Dashboard session only (member role viewer or above). No API-key scope opens it yet; opening it to balance.read keys is an access decision that has not been taken.

Responses

Response fields

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "data": [
    {
      "id": "adr_01K5Y9B7C8D9E0F1G2H3J4K5M6",
      "label": "Payouts hot wallet",
      "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "created_at": "2026-09-25T10:20:00.000Z",
      "updated_at": "2026-09-25T10:20:00.000Z"
    }
  ],
  "limit": 100,
  "used": 1
}

Save an address

POST /v1/account/addresses · saveAddressBookEntry

Auth: Dashboard session cookie + X-CSRF-Token.

Adds address under label. The address is unique per account: saving one that is already in the book replaces its label, answers 200 with the existing entry and uses no slot. A new address on a full book is 3019 address_book_full.

Dashboard session, member role editor or above, with X-CSRF-Token.

Request body

JSON (AddressBookRequest), required.

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

{"label":"Payouts hot wallet","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"}

Responses

Response fields (AddressBookEntry)

Remove an address

DELETE /v1/account/addresses/{entryId} · deleteAddressBookEntry

Auth: Dashboard session cookie + X-CSRF-Token.

Frees the slot immediately. An id of another account answers 404, like an id that does not exist. Dashboard session, member role editor, with X-CSRF-Token.

Parameters

Responses

Order analytics, aggregated server-side

GET /v1/account/stats · getAccountStats

Auth: API key (HMAC) or dashboard session cookie + X-CSRF-Token.

What the Analytics screen draws, computed next to the data rather than by summing orders in the page. Covers orders created in [from, to):

Days and hours are UTC shifted by utc_offset_minutes, so the page can ask for its visitor’s calendar. series has one row per day of the range, zeros included. weekday_hour[d][h] counts orders on ISO weekday d + 1 (Monday first) at hour h.

Retention: 13 months. A from older than that is clamped to the retention start; clamped is true and requested_from echoes what was asked. Defaults: to = now, from = to − 30 days. to must be after from (2001 otherwise).

API key scope orders.read (the aggregates are sums over the orders that scope already lists), or a dashboard session with member role viewer.

Parameters

Responses

Response fields (AccountStats)

Example 200 response, from the contract (illustrative values — live numbers come from the API):

{
  "from": "2026-09-23T00:00:00.000Z",
  "to": "2026-09-25T00:00:00.000Z",
  "requested_from": "2026-09-23T00:00:00.000Z",
  "clamped": false,
  "retention_months": 13,
  "bucket": "day",
  "utc_offset_minutes": 0,
  "totals": {"orders":3,"energy":196000,"spent_sun":11760000,"avg_price_sun_per_65k":3900000},
  "series": [
    {"date":"2026-09-23","orders":1,"energy":65000,"spent_sun":3900000},
    {"date":"2026-09-24","orders":2,"energy":131000,"spent_sun":7860000}
  ],
  "weekday_hour": [[0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0]],
  "top_receivers": [
    {
      "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "orders": 2,
      "energy": 131000,
      "spent_sun": 7860000
    }
  ]
}