GET Orders

/api/v1/orders

Parameters/Query:

/api/v1/orders?limit=20&offset=0&from_date=2025-01-01T00:00:00Z&to_date=2025-03-01T00:00:00Z

limit: maximum number of records per page (default: 20)
offset: pagination offset (default: 0)
from_date: start date filter in ISO 8601 format (e.g. 2025-01-01T00:00:00Z)
to_date: end date filter in ISO 8601 format (e.g. 2025-03-01T00:00:00Z)
search: a transaction hash (64-char hex) previously submitted by the caller — returns the single order that transaction belongs to, instead of a date-range page. See Searching by transaction hash below.

This call returns a paginated list of orders (resource charges) within the specified date range.

tip

This endpoint requires the ADMIN (spender) API key.

warning

The maximum allowed search period is 3 months. Requests with a wider date range will be rejected. This limit does not apply when search is used — see below, from_date/to_date/limit/offset are ignored on that branch.

Response contains the following data:

orders: array of order objects, each containing:
1. order_id: unique order identifier (UUID)
2. order_date: timestamp when the order was created (ISO 8601)
3. amount_trx: total amount charged (in sun)
4. cashback_amount_trx: cashback amount (in sun)
5. charge_token: currency charged (RTRX or RUSDT). See the charge_token relabeling release note for a historical-orders caveat.
6. details: human-readable order description (e.g. resource breakdown)
7. target_address: TRON address the order was delivered to
8. transactions: array of User transaction hashes processed within this order
9. resources: array of the confirmed on-chain resource-delivery transactions Transatron broadcast to fulfil this order, each containing:
  1. type: resource type delivered — ACTIVATE, ENERGY, BANDWIDTH, or TRX
  2. tx_id: a 64-char hex TRON transaction hash when the delivery has a standard on-chain hash; otherwise the resource operation's own internal UUID. Some confirmed deliveries — e.g. energy served from existing stake, or free bandwidth — carry no separate on-chain hash and are still reported this way, so the field is never empty for a confirmed delivery. The two forms are trivially distinguishable: hashes never contain hyphens, UUIDs always do.
  3. amount: the quantity delivered — energy units for ENERGY, bandwidth bytes for BANDWIDTH, sun for TRX, always 1 for ACTIVATE. Nullable.
  4. price: the amount billed for this line, in sun — the same unit and scale as amount_trx. Always present, nullable. See Per-resource price below.
  Only confirmed deliveries are included — reclaim operations and unconfirmed attempts never appear. resources is always present on every order and may be an empty array ([]).
10. trx_price: TRX/USDT price at the time of the order
11. order_transactions: per-transaction breakdown of amount_trx, or null. The key is always present — see Per-transaction breakdown below.
pagination: pagination metadata object containing:
1. limit: page size used
2. offset: current offset in the result set
3. total: total number of orders matching the query

Example of response:

{
    "orders": [
        {
            "amount_trx": 677350,
            "cashback_amount_trx": 0,
            "charge_token": "RTRX",
            "details": "Charge for: 64285 Energy, 345 Bandwidth.",
            "order_date": "2026-01-08T14:03:59Z",
            "order_id": "4d50c208-741d-41dd-bc86-f28a08f83f12",
            "order_transactions": [
                {"amount_trx": 377350, "tx_id": "6399cdf660486b5750de8ca94a4c318bb180c92e859a3c1ff42298afdfbd9432"},
                {"amount_trx": 100000, "tx_id": "2bbac13577d687e1ddc26ed2ef33a18107a7d5f0e7dc8f8f4f7fd218df3d9109"},
                {"amount_trx": 100000, "tx_id": "b4cbb64839a09bd41f3f9723397dff2b145eeedbe72d6b87feceb054ebb84ecf"},
                {"amount_trx": 100000, "tx_id": "907c5931a6b6f848ec71b85df9235e3f3076595d16995c30f21ed8348ce4ca50"}
            ],
            "target_address": "TYQxFB5F67xs1MQbeGcKCPgjTMHpKZxFbf",
            "transactions": [
                "6399cdf660486b5750de8ca94a4c318bb180c92e859a3c1ff42298afdfbd9432",
                "2bbac13577d687e1ddc26ed2ef33a18107a7d5f0e7dc8f8f4f7fd218df3d9109",
                "b4cbb64839a09bd41f3f9723397dff2b145eeedbe72d6b87feceb054ebb84ecf",
                "907c5931a6b6f848ec71b85df9235e3f3076595d16995c30f21ed8348ce4ca50"
            ],
            "resources": [
                {"type": "ENERGY", "tx_id": "a6c1a1353ea8be97f9e1d2b575f14f5990e499609dba4f8b89600837cc3eaec1", "amount": 64285, "price": 632350},
                {"type": "BANDWIDTH", "tx_id": "2cae500f96057e871d35793232fe5c189dfddc40622529a14ae1f113138a33f3", "amount": 345, "price": 45000}
            ],
            "trx_price": 0.2979386
        },
        {
            "amount_trx": 12500,
            "cashback_amount_trx": 0,
            "charge_token": "RUSDT",
            "details": "Charge for: 1500 Energy.",
            "order_date": "2026-01-09T09:12:31Z",
            "order_id": "5eb496d0-3a38-4956-a149-8a23a68c9822",
            "order_transactions": [
                {"amount_trx": 12500, "tx_id": "0c3a1a9c4d7e6f5b8a2d1c0e9f8b7a6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c"}
            ],
            "target_address": "TYQxFB5F67xs1MQbeGcKCPgjTMHpKZxFbf",
            "transactions": [
                "0c3a1a9c4d7e6f5b8a2d1c0e9f8b7a6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c"
            ],
            "resources": [
                {"type": "ENERGY", "tx_id": "841e900c-ef52-4405-928f-ab0f73aae2eb", "amount": 1500, "price": 10000},
                {"type": "TRX", "tx_id": "abb6ecb1ff323202e9c14c9aa970831a1e6cd611942a08cdab14aeb552d2a5c8", "amount": 2500, "price": 2500}
            ],
            "trx_price": 0.2979386
        }
    ],
    "pagination": {
        "limit": 20,
        "offset": 0,
        "total": 66
    }
}

tip

The second order above illustrates the tx_id fallback: its ENERGY delivery was served from existing stake and has no separate on-chain hash, so tx_id is the resource operation's own UUID instead of a 64-char hash.

Per-transaction breakdown

order_transactions is a new, additive array field on each order. The existing transactions array is unchanged — it stays byte-identical to its pre-existing behavior, so callers already parsing it require no changes.

Field: order_transactions is an array of per-transaction entries, each carrying a tx_id (the transaction hash) and that transaction's own amount_trx. Entries are in the same order as transactions[] and keyed by the same hashes.
Unit: each entry's amount_trx is in sun — the same unit and scale as the order-level amount_trx.
Sum invariant: the entries always sum exactly to the order's amount_trx. This holds for every order, without exception.
Sender activation and other order-level charges: any order-level lump — notably sender-account activation — is folded into the first transaction's entry. Transaction #1 carries order-level charges such as sender-account activation.
System-attributed transactions: an entry for a transaction whose fee was billed to the system rather than to the customer carries amount_trx: 0.
Absent vs. zero, no backfill: on endpoints where the feature has shipped, the key is always present; the value is null when absent. There is no backfill in either case below, and a genuinely free order instead shows a breakdown of zeros — null and a breakdown of zeros are not the same thing. order_transactions is null for two distinct reasons:
1. Orders created before this feature (v0.0.053): the column is nullable with no backfill, so all history predating that release returns null.
2. A small number of orders charged during that release's rolling deploy: while one app instance was already running the new build and another was still on the old one, orders written by the old-build instance were charged without ever populating order_transactions. That gap is permanent — there is no backfill for those rows either.
Amounts are gross: amounts are gross — cashback and referral amounts settle later and are never attributable per-transaction.
Key on order_id, never on tx hash: always key on order_id, never on tx hash. A duplicate-order redrive can produce two orders naming the same transaction hashes; summing per-transaction amounts across orders by hash double-bills.

Example: a merged, multi-leg order

The clearest illustration of the sum invariant is an order that settles as more than one on-chain transaction. This is a verbatim search-by-hash capture of a real order from a merged 2-leg charge:

{
    "amount_trx": 2095400,
    "cashback_amount_trx": 0,
    "charge_token": "RTRX",
    "details": "Charge for: 28148 Energy, 688 Bandwidth.",
    "order_date": "2026-08-24T04:27:38Z",
    "order_id": "1a13069a-ff96-4767-92f5-face33ab3308",
    "order_transactions": [
        {"amount_trx": 1047700, "tx_id": "dbd0dd1402bb98d114009890c5aa515d62c452cc1581ae38de0d051bcdcd0f03"},
        {"amount_trx": 1047700, "tx_id": "c4f7da835886a0313b924eb52c31b82ef190be190ecc09af14d169759b87087d"}
    ],
    "target_address": "TGK5JoLz6sLwLgJf2UAFY6bk8B2vKbKWpw",
    "transactions": [
        "dbd0dd1402bb98d114009890c5aa515d62c452cc1581ae38de0d051bcdcd0f03",
        "c4f7da835886a0313b924eb52c31b82ef190be190ecc09af14d169759b87087d"
    ],
    "resources": [
        {"type": "ENERGY", "tx_id": "e33b1b17de66b648a0e4285750e10a94edfde70f54403abbd2d1635fc0755d71"},
        {"type": "BANDWIDTH", "tx_id": "1fb1606753347b9ccd8a5404de28592de6591820acb445676e1016a73719ceb9"}
    ],
    "trx_price": 0.34524971
}

1,047,700 + 1,047,700 = 2,095,400 = the order's amount_trx — the sum invariant holds exactly, with no residual left over to assign to transaction #1 in this particular order.

Per-resource price

price is a new, additive field on each resources[] element, alongside amount. amount answers "what was delivered"; price answers "what was billed for it."

Unit: price is in sun — the same unit and scale as the order-level amount_trx.
The three meanings:
- a number — the amount billed for this line
- 0 — billed nothing for this line: either the order uses fixed-per-transaction pricing (see the exemption below), or the line is one of Transatron's own reclaim operations
- null — the order was charged before this field existed. There is no backfill, so null is permanent for those orders.
null ≠ 0: null means unknown — charged too early to carry this field. 0 is a real, present billed-nothing fact. The two are never interchangeable.
The guarantee: amount_trx is the authoritative billed total. resources[] is the breakdown of confirmed deliveries, each with the price you were billed for it. Σ resources[].price ≤ amount_trx, with equality once every delivery in the order has confirmed (normally within seconds).
Two exemptions, where the breakdown is zero/empty by design and the sum does not reach amount_trx:
1. Fixed-per-transaction pricing: the order is billed per transaction rather than per resource, so every price in resources[] is 0.
2. Resource-recharge orders: resources[] is empty — the charge is the recharge itself, not a resource delivery.
Don't derive a rate from price / amount: any pricing residual is folded into one line, so the ratio gives the effective rate paid for that line, not the contracted rate (e.g. it may read 34.98 where the contracted rate is 35). Compute a contracted rate from your own pricing agreement, not from this ratio.

See also Per-transaction breakdown above: order_transactions sums to amount_trx from the transaction axis, while resources[].price sums to it (per the guarantee above) from the resource axis.

Searching by transaction hash

Pass search=<tx_hash> to look up the single order a specific transaction belongs to, instead of listing orders by date range. This is useful because one order can bundle hundreds of submitted transactions, making it impractical to find which order a given hash belongs to by browsing date-range pages.

/api/v1/orders?search=6399cdf660486b5750de8ca94a4c318bb180c92e859a3c1ff42298afdfbd9432

search is matched only against your own orders — it can never return another customer's order.
When search is present, from_date, to_date, limit, and offset are ignored.
The response uses the same {orders, pagination} envelope as a normal listing, with 0 or 1 order returned.

Outcome	HTTP status	Response
Hash belongs to one of your orders	`200`	`{"orders": [ <the order> ], "pagination": {"limit": 1, "offset": 0, "total": 1}}`
Hash is mined on-chain but isn't part of any of your orders (e.g. it's another customer's)	`200`	`{"orders": [], "pagination": {"limit": 1, "offset": 0, "total": 0}}`
`search` is not a well-formed 64-char hex hash	`400`	—
Hash is well-formed but unknown / not yet mined on-chain	`404`	—
Upstream TRON node error	`502`	—

Example of response:

{
    "orders": [
        {
            "amount_trx": 677350,
            "cashback_amount_trx": 0,
            "charge_token": "RTRX",
            "details": "Charge for: 64285 Energy, 345 Bandwidth.",
            "order_date": "2026-01-08T14:03:59Z",
            "order_id": "4d50c208-741d-41dd-bc86-f28a08f83f12",
            "order_transactions": [
                {"amount_trx": 377350, "tx_id": "6399cdf660486b5750de8ca94a4c318bb180c92e859a3c1ff42298afdfbd9432"},
                {"amount_trx": 100000, "tx_id": "2bbac13577d687e1ddc26ed2ef33a18107a7d5f0e7dc8f8f4f7fd218df3d9109"},
                {"amount_trx": 100000, "tx_id": "b4cbb64839a09bd41f3f9723397dff2b145eeedbe72d6b87feceb054ebb84ecf"},
                {"amount_trx": 100000, "tx_id": "907c5931a6b6f848ec71b85df9235e3f3076595d16995c30f21ed8348ce4ca50"}
            ],
            "target_address": "TYQxFB5F67xs1MQbeGcKCPgjTMHpKZxFbf",
            "transactions": [
                "6399cdf660486b5750de8ca94a4c318bb180c92e859a3c1ff42298afdfbd9432",
                "2bbac13577d687e1ddc26ed2ef33a18107a7d5f0e7dc8f8f4f7fd218df3d9109",
                "b4cbb64839a09bd41f3f9723397dff2b145eeedbe72d6b87feceb054ebb84ecf",
                "907c5931a6b6f848ec71b85df9235e3f3076595d16995c30f21ed8348ce4ca50"
            ],
            "resources": [
                {"type": "ENERGY", "tx_id": "a6c1a1353ea8be97f9e1d2b575f14f5990e499609dba4f8b89600837cc3eaec1", "amount": 64285, "price": 632350},
                {"type": "BANDWIDTH", "tx_id": "2cae500f96057e871d35793232fe5c189dfddc40622529a14ae1f113138a33f3", "amount": 345, "price": 45000}
            ],
            "trx_price": 0.2979386
        }
    ],
    "pagination": {
        "limit": 1,
        "offset": 0,
        "total": 1
    }
}

Parameters/Query:​

Per-transaction breakdown​

Example: a merged, multi-leg order​

Per-resource price​

Searching by transaction hash​

Parameters/Query:

Per-transaction breakdown

Example: a merged, multi-leg order

Per-resource price

Searching by transaction hash