nodevera RPC API integration guide

1. Concepts, credentials and first request

Energy access, API keys and TRX balances are separate from RPC subscriptions. Open the Energy API access page to create or revoke keys and copy its full API Base URL. In these examples, ENERGY_BASE_URL already ends in /v1/resources; do not append that prefix again.

Register your calling server's public IPv4 or IPv6 address in Energy API access before calling this API. Both the Energy key and its account's allowed source IP are required. An empty IP allowlist denies direct API access; dashboard actions remain available.

Energy API access · Reconciliation and API activity

Send X-API-Key or Authorization: Bearer with your Energy API key. No API Secret, request signature, HMAC or timestamp header is required. Use HTTPS from your backend and keep keys out of browser code, logs and shared examples.

export ENERGY_BASE_URL="<energy_api_base_url_ending_in_/v1/resources>"
export ENERGY_API_KEY="<your_energy_api_key>"

curl -sS "$ENERGY_BASE_URL/account" \
  -H "X-API-Key: $ENERGY_API_KEY"

The receiver is the activated TRON wallet that will send the transaction, not the recipient of a USDT transfer. Contract accounts cannot receive this delegated Energy. Wait for CONFIRMED before signing and broadcasting your own transaction. Resources may be reclaimed after the rental period; bandwidth is separate, and Energy needs vary by transaction.

2. Account, catalog and usage summary

All *_sun monetary fields are integer SUN: 1 TRX = 1,000,000 SUN. Use integer arithmetic. Energy amounts are resource units, not SUN. Dates are RFC 3339 timestamps.

curl -sS "$ENERGY_BASE_URL/catalog" -H "X-API-Key: $ENERGY_API_KEY"
curl -sS "$ENERGY_BASE_URL/summary" -H "X-API-Key: $ENERGY_API_KEY"

{
  "account": {
    "id": "<account_id>",
    "balance_sun": 20000000,
    "held_sun": 0,
    "disabled": false
  }
}

Summary day and month boundaries use Asia/Shanghai. Order counts and known delivered amounts follow order creation time; confirmed counts follow confirmation time, and charges follow CAPTURE ledger time. delivered_energy is historical known delivery, not the wallet's remaining on-chain Energy. Use summary for account totals rather than summing the recent history lists.

3. Request an estimate

POST /quotes accepts one JSON object with all three fields below. A successful response is HTTP 200 with a quote object. Requesting a quote does not reserve funds or create an order. Quotes are valid for approximately 60 seconds; always check expires_at.

curl -sS -X POST "$ENERGY_BASE_URL/quotes" \
  -H "X-API-Key: $ENERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":65000,"receiver":"<activated_tron_sender_address>","duration":"1h"}'

{
  "quote": {
    "id": "<quote_id>",
    "amount": 65000,
    "receiver": "<activated_tron_sender_address>",
    "duration": "1h",
    "sell_price_sun": 3000000,
    "expires_at": "2026-01-01T00:01:00Z"
  }
}

All amounts, dates and IDs in these responses are illustrative, not live prices or payment instructions. quote.id identifies this estimate; sell_price_sun is its estimated total. The final charge is determined after delivery and cannot exceed the maximum you authorize when ordering.

4. Create an authorized order and poll its result

POST /orders creates an asynchronous order. Review the current quote and available balance before sending this request: it reserves the full max_total_sun immediately. The cap must cover the quote estimate and must not exceed 1,000,000,000 SUN (1,000 TRX). You may set it to the estimate if you do not authorize a higher final price.

curl -sS -X POST "$ENERGY_BASE_URL/orders" \
  -H "X-API-Key: $ENERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"<quote_id>","client_order_id":"merchant-order-001","max_total_sun":3500000}'

{
  "order": {
    "id": "<order_id>",
    "client_order_id": "merchant-order-001",
    "quote_id": "<quote_id>",
    "amount": 65000,
    "receiver": "<activated_tron_sender_address>",
    "status": "QUEUED",
    "sell_price_sun": 3000000,
    "charged_sun": 0,
    "held_sun": 3500000,
    "delivered_amount": 0,
    "created_at": "2026-01-01T00:00:20Z",
    "updated_at": "2026-01-01T00:00:20Z"
  }
}

A first successful creation normally returns HTTP 202. Replaying an existing client_order_id with exactly the same quote_id and max_total_sun returns the existing order, normally HTTP 200; changing either value returns HTTP 409. Concurrent identical requests may both return 202 for the same order. Treat either 200 or 202 as accepted and persist the returned order.id.

If the POST response is lost, retry the identical JSON with the same client_order_id, even if the quote has since expired. Do not generate a new business ID just because of a timeout: it can create another paid order. A quote can fund only one order.

curl -sS "$ENERGY_BASE_URL/orders/<order_id>" \
  -H "X-API-Key: $ENERGY_API_KEY"

GET /orders/{order_id} returns HTTP 200 with order. Poll at a modest interval, for example every 5 seconds with backoff. order.sell_price_sun is the original estimate; charged_sun is the settled charge. order.held_sun records the original authorization even after settlement, not the current wallet hold. Read account.held_sun for the current total. delivered_amount is known delivered Energy, and transaction_id is included when available.

Pay for one order on-chain

After requesting a quote, choose a single-order payment instead of using your existing balance. POST /checkouts accepts quote_id and client_order_id. Optional max_total_sun defaults to the quoted total and must satisfy the same authorization bounds as a balance order. Create the checkout before the quote expires.

curl -sS -X POST "$ENERGY_BASE_URL/checkouts" \
  -H "X-API-Key: $ENERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"<quote_id>","client_order_id":"merchant-payment-001"}'

A new checkout returns HTTP 201 with checkout; an identical replay returns HTTP 200. Reuse the same quote_id, client_order_id and authorization if the response is lost. A checkout reserves its quote and business ID, so they cannot also create a separate balance order.

The checkout contains id, quote_id, client_order_id, amount, receiver, duration, sell_price_sun, max_total_sun, status, deposit, created_at and expires_at. Pay exactly deposit.amount_sun to deposit.address before deposit.expires_at, normally within 30 minutes. The dashboard QR contains only this receiving address; enter the exact TRX amount separately.

curl -sS "$ENERGY_BASE_URL/checkouts/<checkout_id>" -H "X-API-Key: $ENERGY_API_KEY"
curl -sS "$ENERGY_BASE_URL/checkouts" -H "X-API-Key: $ENERGY_API_KEY"

GET /checkouts/{id} returns checkout; GET /checkouts returns checkouts with at most 100 recent records. PENDING means awaiting payment, EXPIRED means the payment window has closed, CANCELED means the payment was canceled, and PAID means funds were credited. Only an order_id identifies an Energy order; query that order for delivery. PAID without order_id must not be treated as an order or delivery confirmation.

For an eligible, uncanceled checkout, payment confirmation credits your account and creates the authorized Energy order atomically, even if your browser is closed. The original quote expiry does not cancel a valid payment. A canceled checkout never starts an automatic Energy order. If fulfillment cannot proceed, funds remain in your available balance; there is no automatic on-chain refund. Any payment reference tail above the authorization also remains in your balance.

5. Order states and next actions

Stop routine polling at CONFIRMED, FAILED or RESOLVED. Handle REVIEW through support and reconciliation. An HTTP 202, a timeout or a zero charged_sun on a pending order does not prove delivery or final failure.

6. Create TRX top-up instructions

POST /deposits accepts amount_sun between 1,000,000 and 1,000,000,000,000 (1 to 1,000,000 TRX), and returns HTTP 201 with deposit. This only creates payment instructions: it neither transfers funds nor buys Energy.

curl -sS -X POST "$ENERGY_BASE_URL/deposits" \
  -H "X-API-Key: $ENERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_sun":100000000}'

{
  "deposit": {
    "id": "<deposit_id>",
    "amount_sun": 100000001,
    "address": "<returned_tron_deposit_address>",
    "status": "PENDING",
    "created_at": "2026-01-01T00:00:00Z",
    "expires_at": "2026-01-01T00:30:00Z"
  }
}

Use only the address and exact amount_sun returned by the current deposit, including every decimal place. The amount may be slightly higher than requested to identify the payment. Send native TRX on TRON before expires_at; do not send USDT or another network's assets. New instructions are valid for 30 minutes. Do not reuse paid or expired instructions or round the amount.

curl -sS "$ENERGY_BASE_URL/deposits" \
  -H "X-API-Key: $ENERGY_API_KEY"

GET /deposits returns deposits with id, amount_sun, address, status, tx_id, created_at, expires_at and can_cancel. PENDING means awaiting confirmation, PAID means credited, EXPIRED means the payment window has closed, and CANCELED means canceled. A wallet broadcast alone is not confirmation. Contact support with the deposit ID and transaction ID if a payment needs investigation.

Each deposit list record includes checkout_id: null identifies a balance top-up, while a checkout ID identifies a single-order payment. Use this field to distinguish payment types even when the corresponding checkout is outside the recent checkout history.

Payment status and cancellation

RPC subscription payments, TRX balance top-ups and single-order Energy payments share one pending-payment slot per account. Before creating a payment, read GET /payment-status. Continue only when pending_payment is null and payment_creation_available is true. The server rechecks every write; another session or a temporary restriction can still prevent creation.

curl -sS "$ENERGY_BASE_URL/payment-status" \
  -H "X-API-Key: $ENERGY_API_KEY"

{
  "pending_payment": {
    "id": "<deposit_id>",
    "kind": "CHECKOUT",
    "expires_at": "2026-01-01T00:30:00Z",
    "can_cancel": true
  },
  "payment_creation_available": true
}

pending_payment is null or an object with id, kind, expires_at and can_cancel. kind is RPC, TOPUP or CHECKOUT. An existing object means you must handle that payment first, even if payment_creation_available is true. Manage RPC payments on the billing page; manage TOPUP and CHECKOUT payments in Energy payment history. can_cancel is a current capability hint, not permission to skip server validation.

Current payment · Energy payment history

curl -i -X POST "$ENERGY_BASE_URL/deposits/<deposit_id>/cancel" \
  -H "X-API-Key: $ENERGY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm_unpaid":true}'

POST /deposits/{id}/cancel accepts exactly confirm_unpaid: true and returns HTTP 200 with deposit. Only your own valid, unpaid TRX payment can be canceled. Repeating a completed cancellation returns its current deposit without consuming another cancellation. Cancellation has cooldowns and usage limits; HTTP 429 means wait for Retry-After rather than retrying in a loop.

Do not cancel if you have already transferred funds. Cancellation does not reverse an on-chain transfer or trigger a refund. Transfers made within the original payment window are still checked after cancellation; a matching confirmed TRX payment is credited to available balance. A canceled checkout will not automatically purchase Energy, including when its deposit later becomes PAID. Check order_id and the ledger before making another purchase.

7. Ledger, recent history and key metadata

curl -sS "$ENERGY_BASE_URL/ledger" -H "X-API-Key: $ENERGY_API_KEY"
curl -sS "$ENERGY_BASE_URL/orders" -H "X-API-Key: $ENERGY_API_KEY"
curl -sS "$ENERGY_BASE_URL/keys" -H "X-API-Key: $ENERGY_API_KEY"

GET /ledger returns entries with id, kind, amount_sun, reference_id, created_at, available_delta_sun and held_delta_sun. The delta fields show movement in available and held balances; amount_sun is not always spending. Match reference_id to the corresponding deposit or order.

GET /ledger returns entries and next_cursor; GET /deposits returns deposits and next_cursor. Both accept limit (default 20, maximum 100), cursor, and RFC3339 from/to filters. Keep filters unchanged and pass next_cursor as cursor until it is empty. GET /deposits/{deposit_id} returns one of your payment requests.

GET /orders returns up to 100 recent orders. GET /keys returns up to 100 key metadata records, never the original secret. Create and revoke keys in the customer dashboard; retain order IDs for individual queries or use paged Reconciliation for older orders.

Reconciliation and request history

Detailed history is available for 90 days. Unfinished and review orders are kept until resolved. Lifetime totals remain unchanged.

Open Reconciliation to compare requested and delivered Energy, the on-chain transaction, the final charge and released funds for each order. A hold reserves your spending limit; it is not a second charge. Balance movements show how available and held balances changed.

GET /reconciliation returns items with order and ledger. GET /reconciliation/{order_id} adds recent linked api_logs. GET /activity lists your Energy API requests with request_id, API key ID, source, method, path, HTTP status, duration and related order or deposit ID. Filter activity by deposit_id to trace a payment request. X-Request-ID identifies the recorded request for support.

curl -sS "$ENERGY_BASE_URL/reconciliation?limit=20&status=CONFIRMED" \
  -H "X-API-Key: $ENERGY_API_KEY"

curl -sS "$ENERGY_BASE_URL/reconciliation/<order_id>" \
  -H "X-API-Key: $ENERGY_API_KEY"

curl -sS "$ENERGY_BASE_URL/activity?limit=20&order_id=<order_id>" \
  -H "X-API-Key: $ENERGY_API_KEY"

Lists return items and next_cursor. Reuse next_cursor as cursor with the same filters until it is empty. limit accepts 1 to 100. Both lists accept order_id and RFC3339 from/to timestamps; reconciliation accepts an order status, while activity accepts request_id, key_id, source (api or portal) and an HTTP status. Filters use exact matches. All results belong to your account.

Reconciliation · API activity

8. HTTP errors and safe retries

Energy API errors use a JSON error string. Unknown JSON fields, extra JSON objects and malformed bodies are rejected. Use the documented method and exact field types; the request body limit is 32 KiB.

{"error":"insufficient TRX balance"}

9. Before production

1. Verify account and catalog with read-only requests first. Validate the actual sender address, current quote, available balance and approved maximum before creating an order.
2. Persist your client_order_id and the exact order request before sending it. Store the returned order.id, final state, charge and delivery evidence for reconciliation.
3. Test timeout recovery, idempotent retries, insufficient balance, expired quotes, rate limits and REVIEW handling. Do not treat a pending authorization as spending or a confirmed Energy order as a broadcast transaction.
4. This API supports individual one-hour Energy orders, polling and cancellation of eligible unpaid TRX payments. Energy delivery orders cannot be canceled through this endpoint. Batch ordering, automatic renewal, Webhooks and bandwidth rental are not available. Your application remains responsible for transaction signing and broadcasting.