API reference
Each method below names its full path. Request and response bodies are JSON, Content-Type: application/json. Integers and booleans in a body are JSON numbers and booleans. A stringified number is rejected. Bandwidth rental uses the same key and the same TRX balance as energy. Its orders are separate: an energy id is not a bandwidth id.
Authenticate with the X-API-KEY header. A key is issued only in the cabinet. The cabinet lists every active key. The full key is shown once, when it is issued. Issuing a new key leaves the previous keys active. A key stops working only when it is disabled.
A new key has full access. It can call the methods an API key can call. Methods that require a cabinet session still refuse a key. Read only can call GET. Any other method from a read-only key returns 403 key_read_only. The mode is switched in the cabinet. A cabinet session is not limited by a key mode.
A failed call returns {"error_code":"..."} and an HTTP status other than 200. Status codes are listed with each error_code at the end of this page.
The IP whitelist is set in the cabinet. Add the public IPv4 address of each caller. A private, loopback, or link-local address is rejected, and the list holds at most 50 addresses. With no addresses on the list, a key works from anywhere. After the first address, a call from any other address is rejected with 403 ip_not_allowed. The list applies to calls made with an API key. Cabinet sign-in stays open from any address.
POST /api/v1/order, POST /api/v1/bandwidth, POST /api/v1/activation, POST /api/v1/topup, POST /api/v1/withdraw, and POST /api/v1/exchange with preview false accept an idempotency key. Send it in the JSON field idempotency_key or in the X-Idempotency-Key header. If both are set, they must be equal. The key is 8 to 128 characters. The same key and the same body return the original result, once that call has finished. The same key and a different body return conflict. If the first call has not finished, the repeat waits and can return 503 unavailable. Send the same key again. An energy key and a bandwidth key do not see each other: the same text may be used once on each.
The response of these calls, and the later reads of the same object, carry the key back in idempotency_key. It is the text you sent, whether in the body or in the header, or null when you sent none. The webhooks for orders, bandwidth orders, activations, and top-ups carry it too, so a delivery can be matched to the request that made it.
Checks that the API is ready to take calls. No key. A key sent with this call is ignored, so a wrong or expired key still returns 200 while the service is up. To check a key, call another method, such as GET /api/v1/balance.
| ok |
boolean
true when the service is ready to take calls. Otherwise the response is 503 unavailable.
example: true
|
|---|
Returns the spendable balances. Energy, bandwidth, and activation use TRX. A top-up can add TRX or USDT. USDT is a separate balance.
| balance |
string
The spendable TRX balance, six digits after the point. Same value as the trx entry in balances.
example: 12.500000
|
|---|---|
| balances |
array
Every currency, including TRX. Each element has currency (trx or usdt) and balance (six digits after the point).
example: [{"currency":"trx","balance":"12.500000"},{"currency":"usdt","balance":"0.000000"}]
|
| string The account email. example: ada@example.com | |
| saved_trx | string Six digits after the point. Sum over filled orders of the TRX the network would have burned for the energy sold, minus the price paid. The burn price is the chain energy fee in force when the order was created. The figure can be negative. example: 3.150000 |
Returns a price. Does not charge the balance and does not delegate energy. address is optional. When it is present and that account is not activated yet, price_trx includes the activation fee and activation is true. Set no_activation to true to refuse that case with 400 inactive_address instead of adding the fee. The activation check uses the stored result for an address already seen as active.
| volume | integer Required. Inclusive range 65000 to 4000000. example: 65000 |
|---|---|
| duration |
string
Required. One of 15m, 1h, 1d, 3d.
example: 1h
|
| exact_volume | boolean Optional. Omitted means false. example: false |
| exact_duration | boolean Optional. Omitted means false. example: false |
| no_activation |
boolean
Optional. Omitted means false. When true, an address that is not activated returns inactive_address instead of a price that includes activation.
example: false
|
| address |
string
Optional. Tron address that would receive the energy. When it is not activated, the price includes activation, unless no_activation is true.
example: YOUR_TRON_ADDRESS
|
Some suppliers sell only fixed amounts. With exact_volume true, a supplier that does not sell the requested amount is excluded. With exact_volume false, the response volume may be larger than the request when that fill costs less. It is never smaller. exact_duration follows the same rule for duration: a longer duration is eligible, a shorter one is not. A larger amount or a longer duration is skipped when its energy price, before activation, is above the TRX the network would burn for the requested energy.
| volume | integer The amount that would be delegated. example: 65000 |
|---|---|
| duration | string The duration that would be delegated. example: 1h |
| price_trx |
string
Order total in TRX, six decimal places. Includes activation when activation is true.
example: 1.911000
|
| price_sun | string Sun for one energy. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. When activation is included, the rate is taken from that combined total. example: 29.4 |
| activation |
boolean
true when the address was sent and is not activated, so the price includes activation. false when the address is omitted or already active.
example: false
|
Buys energy and charges the balance. The request does not include a price. The service tries the lowest offer first. price_trx is the full charge: the energy that was accepted, plus activation when this order activated the address. activation is then true. If that activation is later cancelled, the fee is removed from price_trx and activation becomes false. If the order later becomes Cancelled, the energy charge is returned. The response volume and duration follow the same exact-flag rules as a quote.
If the address is not activated, gasrent activates it first, charges the activation fee, waits until the account is visible on the network, and only then delegates energy. The activation fee is a separate balance row and is not returned when the energy order is cancelled. An address that is already active is delegated immediately. With no_activation true, an address that is not activated returns 400 inactive_address and is not activated.
| address |
string
Required. Tron address that receives the energy. An address that is not activated yet is activated as part of this call, then the energy is delegated. With no_activation true, that address returns inactive_address and nothing is charged.
example: YOUR_TRON_ADDRESS
|
|---|---|
| volume | integer Required. Inclusive range 65000 to 4000000. example: 65000 |
| duration |
string
Required. One of 15m, 1h, 1d, 3d.
example: 1h
|
| exact_volume | boolean Optional. Omitted means false. example: false |
| exact_duration | boolean Optional. Omitted means false. example: false |
| no_activation |
boolean
Optional. Omitted means false. When true, an address that is not activated returns inactive_address. The address is not activated and the balance is not charged. The same idempotency key with the other value returns conflict.
example: false
|
| idempotency_key | string Optional. See Idempotency. Recommended. A dropped connection can be repeated safely only when the key is reused with the same body. example: order-20261023-0001 |
| order_id | string UUID of the new order. This is the only order identifier. example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: order-20261023-0001
|
| status |
string
Pending, Filled, or Cancelled.
example: Pending
|
| address | string The address on the order. example: YOUR_TRON_ADDRESS |
| volume |
integer
The amount on the order. It may be larger than the request when exact_volume is false. It is never smaller.
example: 65000
|
| duration |
string
The duration on the order. It may be longer than the request when exact_duration is false. It is never shorter.
example: 1h
|
| price_trx |
string
Full charge in TRX, six decimal places. Includes activation when activation is true. A later cancelled activation is removed from this total. A cancelled order returns the energy part. The activation fee stays charged unless that activation itself was cancelled.
example: 1.911000
|
| price_sun | string Sun for one energy. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. When activation is included, the rate is taken from that combined total. example: 29.4 |
| activation |
boolean
true when this order activated the address and price_trx includes that fee.
example: false
|
| txid | string or null Present once the delegation transaction exists. example: null |
| created_at |
string
When the order was created, UTC, YYYY-MM-DDTHH:MM:SS.sssZ.
example: 2026-10-23T13:40:00.000Z
|
Returns the latest 50 orders for the account, newest first. A Cancelled order is included. A purchase that failed before an order id was issued is not included.
| before_id |
string
Optional query parameter. Set it to the order_id of the last element on this page. The response is the next older page. It must be a UUID.
example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e
|
|---|
A JSON array. Each element:
| order_id | string UUID of the order. example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: order-20261023-0001
|
| status |
string
Pending, Filled, or Cancelled.
example: Pending
|
| address | string The address on the order. example: YOUR_TRON_ADDRESS |
| volume |
integer
The amount on the order. It may be larger than the request when exact_volume is false. It is never smaller.
example: 65000
|
| duration |
string
The duration on the order. It may be longer than the request when exact_duration is false. It is never shorter.
example: 1h
|
| price_trx |
string
Full charge in TRX, six decimal places. Includes activation when activation is true. A later cancelled activation is removed from this total. A cancelled order returns the energy part. The activation fee stays charged unless that activation itself was cancelled.
example: 1.911000
|
| price_sun | string Sun for one energy. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. When activation is included, the rate is taken from that combined total. example: 29.4 |
| activation |
boolean
true when this order activated the address and price_trx includes that fee.
example: false
|
| txid | string or null Present once the delegation transaction exists. example: null |
| created_at |
string
When the order was created, UTC, YYYY-MM-DDTHH:MM:SS.sssZ.
example: 2026-10-23T13:40:00.000Z
|
Returns one order of this account, including an order whose status is Cancelled. While status is Pending, repeat this request. An id this account was never given is 404 not_found.
| order_id | string Required path parameter. A UUID. example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e |
|---|
| order_id | string UUID of the order. example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: order-20261023-0001
|
| status |
string
Pending, Filled, or Cancelled.
example: Pending
|
| address | string The address on the order. example: YOUR_TRON_ADDRESS |
| volume |
integer
The amount on the order. It may be larger than the request when exact_volume is false. It is never smaller.
example: 65000
|
| duration |
string
The duration on the order. It may be longer than the request when exact_duration is false. It is never shorter.
example: 1h
|
| price_trx |
string
Full charge in TRX, six decimal places. Includes activation when activation is true. A later cancelled activation is removed from this total. A cancelled order returns the energy part. The activation fee stays charged unless that activation itself was cancelled.
example: 1.911000
|
| price_sun | string Sun for one energy. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. When activation is included, the rate is taken from that combined total. example: 29.4 |
| activation |
boolean
true when this order activated the address and price_trx includes that fee.
example: false
|
| txid | string or null Present once the delegation transaction exists. example: null |
| created_at |
string
When the order was created, UTC, YYYY-MM-DDTHH:MM:SS.sssZ.
example: 2026-10-23T13:40:00.000Z
|
Returns a bandwidth price. Does not charge the balance and does not delegate bandwidth. address is optional and is not activated. The price never includes an activation fee. There is no no_activation field.
| volume | integer Required. Inclusive range 1 to 100000. A supplier may still refuse a size below its own minimum or outside its packages. example: 1000 |
|---|---|
| duration |
string
Required. One of 5m, 1h, 1d, 3d, 7d. There is no 15-minute bandwidth rental.
example: 1h
|
| exact_volume | boolean Optional. Omitted means false. When true, a supplier that does not sell this amount is excluded. example: false |
| exact_duration | boolean Optional. Omitted means false. When true, only this duration is eligible. A shorter duration is never used. example: false |
| address | string Optional. Tron address that would receive the bandwidth. It is checked when present. It does not change the price. example: YOUR_TRON_ADDRESS |
Some suppliers sell only fixed amounts. With exact_volume false, the response volume may be larger than the request when that fill costs less. It is never smaller. exact_duration follows the same rule for duration: a longer duration is eligible, a shorter one is not. A larger amount or a longer duration is skipped when its price is above the TRX the network would burn for the requested bandwidth. Burn is the cost of those points once. It is not multiplied by the rental duration. The response names the amount and duration that a later order would buy.
| resource |
string
Always bandwidth.
example: bandwidth
|
|---|---|
| volume |
integer
The amount that would be delegated. It may be larger than the request when exact_volume is false.
example: 1000
|
| duration |
string
The duration that would be delegated. It may be longer than the request when exact_duration is false.
example: 1h
|
| price_trx | string Price in TRX, six decimal places. Activation is not included. example: 0.801800 |
| price_sun | string Sun for one bandwidth point. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. example: 801.8 |
Buys bandwidth and charges the balance. The request does not include a price. The service tries the lowest offer first. The response volume and duration follow the same exact-flag rules as a bandwidth quote. The address is not activated. An address that is not activated is left unchanged; if no supplier accepts it, the call returns 503 unavailable and the balance is not charged.
Pending means the charge is held and the chain has not confirmed the bandwidth delegation yet. Repeat GET /api/v1/bandwidth/{order_id}. Filled means the chain shows a bandwidth delegation to this address for at least 98% of volume. Cancelled means the charge was returned. A call that cannot buy does not return an order id.
| address | string Required. Tron address that receives the bandwidth. This call does not activate it. example: YOUR_TRON_ADDRESS |
|---|---|
| volume | integer Required. Inclusive range 1 to 100000. example: 1000 |
| duration |
string
Required. One of 5m, 1h, 1d, 3d, 7d.
example: 1h
|
| exact_volume | boolean Optional. Omitted means false. Same rule as the bandwidth quote. example: false |
| exact_duration | boolean Optional. Omitted means false. Same rule as the bandwidth quote. example: false |
| idempotency_key | string Optional. 8 to 128 characters. See Idempotency. A bandwidth key is not an energy key. example: bandwidth-20261025-0001 |
| order_id | string UUID of this bandwidth order. It is not an energy order id. example: d5e6f708-1920-4a1b-8c2d-3e4f5a6b7c8d |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: bandwidth-20261025-0001
|
| resource |
string
Always bandwidth.
example: bandwidth
|
| status |
string
Pending, Filled, or Cancelled.
example: Pending
|
| address | string The address that receives the bandwidth. example: YOUR_TRON_ADDRESS |
| volume |
integer
The amount on the order. It may be larger than the request when exact_volume is false. It is never smaller.
example: 1000
|
| duration |
string
The duration on the order. It may be longer than the request when exact_duration is false. It is never shorter.
example: 1h
|
| price_trx | string Charge in TRX, six decimal places. A cancelled order returns this charge. Activation is not included. example: 0.801800 |
| price_sun | string Sun for one bandwidth point. A fraction is kept, so price_sun × volume ÷ 1,000,000 equals price_trx. example: 801.8 |
| txid | string or null Present once the bandwidth delegation transaction exists. example: null |
| created_at |
string
When the order was created, UTC, YYYY-MM-DDTHH:MM:SS.sssZ.
example: 2026-10-23T13:40:00.000Z
|
Returns this account's bandwidth orders, newest first, up to 50. Energy orders are not included. Pass before_id with the last order_id from the previous page. A blocked account can still read this list.
| before_id |
string
Optional query parameter. A bandwidth order UUID from this account. A value that is not a UUID, or an id this account was never given, is 400 bad_request.
example: d5e6f708-1920-4a1b-8c2d-3e4f5a6b7c8d
|
|---|
A JSON array. Each element has the same fields as POST /api/v1/bandwidth.
Returns one bandwidth order of this account, including an order whose status is Cancelled. While status is Pending, repeat this request. An energy order id, or an id this account was never given, is 404 not_found. A blocked account can still read the order.
| order_id | string Required path parameter. A UUID. example: d5e6f708-1920-4a1b-8c2d-3e4f5a6b7c8d |
|---|
The same fields as POST /api/v1/bandwidth.
Returns one page of balance movements for the account. A row that does not change the balance is omitted. Leave a query parameter out to skip that filter. A bad value is 400 bad_request.
| kind |
string
Optional. deposit, debit, refund, adjustment, exchange, or withdrawal.
example: deposit
|
|---|---|
| currency |
string
Optional. trx or usdt. Keeps rows in that currency.
example: trx
|
| q |
string
Optional. Up to 128 characters. A UUID matches an energy order, a bandwidth order, an activation, a top-up, or the public id of a ledger row. Any text also matches a txid that contains it.
example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e
|
| uuid | string Optional. Up to 36 characters, hexadecimal digits and hyphens. Keeps rows whose energy order, bandwidth order, or activation UUID contains this text. example: a3f2c8e1 |
| subject |
string
Optional. energy or bandwidth. Keeps rows charged for that kind of order, including a refund of one.
example: energy
|
| from |
string
Optional. A calendar day YYYY-MM-DD is the start of that UTC day. An instant YYYY-MM-DDTHH:MM:SSZ is inclusive.
example: 2026-10-01
|
| to |
string
Optional. A calendar day YYYY-MM-DD includes that whole UTC day. An instant YYYY-MM-DDTHH:MM:SSZ is exclusive.
example: 2026-10-23
|
| min |
string
Optional. Signed amount in the row currency, inclusive. A charge is negative, so min=0 leaves charges out. Compare TRX with TRX by also setting currency.
example: 0
|
| max | string Optional. Signed amount in the row currency, inclusive. example: 100 |
| sort |
string
Optional. created (default) or amount. Equal values keep the same order by row id.
example: created
|
| dir |
string
Optional. desc (default) or asc.
example: desc
|
| page | integer Optional. Starts at 1. example: 1 |
| limit | integer Optional. Defaults to 50. The range is 1 to 100. example: 50 |
| topup_id | string Optional. UUID of one top-up. Only rows for that top-up. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
| related_id | string Optional. Public id of a ledger row. Returns that row and the rows that point at it. example: e1f2a3b4-c5d6-4789-a012-3456789abcde |
| transactions | array The rows on this page. Each element is described below. example: [{ "kind": "deposit" }] |
|---|---|
| total | integer How many rows match before paging. example: 3 |
| page | integer The page that was returned. Starts at 1. example: 1 |
| limit | integer The page size that was used. example: 50 |
Each element of transactions:
| kind |
string
deposit is a top-up. debit is a charge for energy, bandwidth, or activating an address. refund returns part or all of a charge. adjustment is a manual change. exchange is one leg of a USDT/TRX exchange: the amount paid, the TRX fee, or the amount received. withdrawal is a payout of TRX or USDT. resource says whether a debit or refund belongs to energy or bandwidth.
example: deposit
|
|---|---|
| id | string Public id of this ledger row. The numeric id is not included. example: e1f2a3b4-c5d6-4789-a012-3456789abcde |
| currency |
string
trx or usdt. The currency of amount and currency_balance_after.
example: trx
|
| amount |
string
Signed amount in currency, six digits after the point. A charge is negative.
example: -25.030000
|
| amount_trx |
string
Signed TRX effect of this row. Equal to amount when currency is trx, and 0.000000 when the row is USDT.
example: -25.030000
|
| balance_after | string The TRX balance after this row, including a row that did not change TRX. example: 37.530000 |
| currency_balance_after |
string
The balance of currency after this row.
example: 37.530000
|
| uuid |
string or null
UUID of the energy or bandwidth order the client can open. Null when this row is not such an order, including a purchase that was refused before an order number was issued. resource says which. The numeric order id is not included.
example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e
|
| resource |
string or null
energy or bandwidth when uuid is an order. null for a top-up, an activation, or an adjustment.
example: energy
|
| topup_id | string or null UUID of the top-up, when this row belongs to one. The numeric top-up id is not included. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
| activation_id | string or null UUID of the activation, when this row belongs to one. The numeric activation id is not included. example: c4d8e2f1-1a22-4b33-8c44-7d5e6f708192 |
| energy |
integer or null
Energy of the rental this row pays for, on a supply row. null on every other row. The buyer and the order are not shown.
example: 65000
|
| duration |
string or null
Length of that rental, such as 1h or 1d, on a supply row. null on every other row.
example: 1h
|
| related_id |
string or null
Public id of the earlier ledger row this row continues, or null. Pass it as the related_id query to see both rows.
example: null
|
| txid | string or null The chain transaction for a deposit or an activation. example: null |
| comment | string or null A note on this row, usually on an adjustment. example: null |
| created_at |
string
UTC timestamp, YYYY-MM-DDTHH:MM:SS.sssZ.
example: 2026-10-23T13:40:00.000Z
|
Returns the price to activate a Tron address. Does not charge the balance and does not activate the address.
The price is the network account-creation fee, plus the bandwidth of the activation transaction at the network bandwidth price. The fee and the bandwidth price are read from the network at call time. price_trx is the amount a later activation would charge. If the address is already active, active is true and every amount is 0.000000.
| address | string Required. Tron address to price. example: YOUR_TRON_ADDRESS |
|---|
| address | string The address from the request. example: YOUR_TRON_ADDRESS |
|---|---|
| active |
boolean
true when the address is already activated. Nothing is charged in that case.
example: false
|
| price_trx | string What an activation would charge. Six decimal places. example: 1.397000 |
Activates the address and charges price_trx. The request does not include a price. The charge is calculated when the call runs, so it can differ from an earlier quote. The same formula as the quote is used: network account-creation fee, plus bandwidth.
A successful broadcast returns Pending until the network confirms it, then Filled. If the network rejects the transaction after it was broadcast, the status becomes Cancelled and the charge is returned. If the transaction is not broadcast, the response is 503 unavailable and no activation id is returned.
| address |
string
Required. Tron address to activate. An address that is already active returns already_active.
example: YOUR_TRON_ADDRESS
|
|---|---|
| idempotency_key |
string
Optional. See Idempotency. A different address with the same key returns conflict.
example: activation-20261023-0001
|
| activation_id | string UUID of this activation. example: c4d8e2f1-1a22-4b33-8c44-7d5e6f708192 |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent. Also null for an activation that an order or a withdrawal started by itself.
example: activation-20261023-0001
|
| status |
string
Pending, Filled, or Cancelled.
example: Pending
|
| address | string The activated address. example: YOUR_TRON_ADDRESS |
| price_trx |
string
Amount charged, six decimal places. Returned on Cancelled as well. The refund is a separate ledger row.
example: 1.397000
|
| txid | string or null The activation transaction. example: null |
Returns one activation. A Pending activation is checked against the network before the response. The body is the same as POST /api/v1/activation.
Returns how much energy and bandwidth one USDT transfer from from_address to to_address would use, and how much of each the sender already has. Does not buy anything and does not return a price. Price an energy fill with POST /api/v1/quote. Price a bandwidth fill with POST /api/v1/bandwidth/quote.
| from_address | string Required. Active Tron address that would send the USDT. It must hold at least 0.000001 USDT. example: YOUR_TRON_ADDRESS |
|---|---|
| to_address |
string
Tron address that would receive the USDT. Send this or to_addresses, not both.
example: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t
|
| to_addresses |
array of strings
A batch: Tron addresses that would each receive one USDT transfer from from_address. From 1 to 20 items. The same address may repeat, and each repeat is one more transfer. Send this or to_address, not both. A longer list returns too_many_addresses.
example: ["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"]
|
The simulated transfer is 0.000001 USDT. Energy does not depend on the amount. If the sender holds none, the simulation reverts before the real energy cost, and the response is insufficient_usdt. That short number is not returned. If the sender holds some USDT but the transfer still reverts, the response is transfer_reverted.
| available_energy |
integer
Energy available on from_address.
example: 12000
|
|---|---|
| required_energy |
integer
Energy the whole request would use: one successful USDT transfer for to_address, or the sum over all of to_addresses. The gap is this minus available_energy.
example: 64285
|
| free_bandwidth |
integer
Free daily bandwidth left on from_address. It pays for the transfer only when it covers the whole transfer by itself.
example: 300
|
| delegated_bandwidth |
integer
Delegated bandwidth left on from_address. A rental adds to this pool.
example: 100
|
| available_bandwidth |
integer
Bandwidth that already counts toward this transfer. When either pool covers the transfer, this is the larger pool. Otherwise it is only delegated_bandwidth, because the pools are not added together. The gap is required_bandwidth minus this number.
For a batch the transfers are taken one by one. The free pool covers as many whole transfers as fit in it (a leftover smaller than one transfer covers nothing). The remaining transfers need the delegated pool, so its leftover counts and a rental tops it up. Here this is the bandwidth already covered: whole transfers from the free pool plus delegated_bandwidth.
example: 100
|
| required_bandwidth |
integer
Bandwidth points the whole request would use: 345 for each USDT transfer without a note. The amount does not change it. The gap is this minus available_bandwidth.
example: 345
|
| transfers |
array of objects
Only when the request used to_addresses. One item per transfer, in request order, with to_address and required_energy. The items add up to the top-level required_energy.
example: [{"to_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "required_energy": 64285}]
|
Opens a top-up. Send one transfer of the returned amount_trx to the returned address before expires_at. The transfer currency is currency: trx is native TRX, usdt is TRC20 USDT on TRON. A different amount or the other currency is not matched to this top-up. An account may have at most 5 unfinished top-ups. Unfinished means pending, cooling, or seen. Above that, the response is too_many_topups.
| amount_trx |
integer
Required. Whole units of currency, minimum 1. The field name stays amount_trx for both TRX and USDT.
example: 25
|
|---|---|
| currency |
string
Optional. trx or usdt. Omitted means trx. usdt is TRC20 USDT sent to the same deposit address.
example: usdt
|
| idempotency_key |
string
Optional. See Idempotency. A different amount_trx or currency with the same key returns conflict.
example: topup-20261023-0001
|
| topup_id | string UUID of the new top-up. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: topup-20261023-0001
|
| address | string Deposit address. Send the exact amount here. example: YOUR_TRON_ADDRESS |
| amount_trx |
string
Exact sum to send, six decimal places, in currency. Equal to the requested whole amount, or that amount plus 0.01 steps, up to 1 more, when the lower sums of this currency are already reserved. Send this sum, not the requested whole number.
example: 25.030000
|
| currency |
string
trx or usdt. The asset to send and the balance that is credited.
example: trx
|
| expires_at |
string
UTC timestamp, YYYY-MM-DDTHH:MM:SSZ. The window is one hour.
example: 2026-10-23T14:40:00Z
|
| created_at |
string
When the top-up was created, UTC, YYYY-MM-DDTHH:MM:SSZ.
example: 2026-10-23T13:40:00Z
|
Returns every unfinished top-up on the account, newest first. Unfinished means pending, cooling, or seen. The call has no query parameters. An account has at most 5 unfinished top-ups, and the response is that whole set.
A credited or expired top-up is not in this list. GET /api/v1/topup/{topup_id} returns one top-up of any status when the id is known. A credited sum is also a deposit row on GET /api/v1/transaction.
A JSON array. Each element:
| topup_id | string UUID of the top-up. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: topup-20261023-0001
|
| amount_trx |
string
The exact sum, six decimal places, in currency.
example: 25.030000
|
| currency |
string
trx or usdt.
example: trx
|
| status |
string
pending is waiting for the transfer. seen means the transfer is on the network and is waiting for 19 confirmations. cooling means the window has closed and a transfer that arrived in time can still be matched.
example: pending
|
| expires_at |
string
UTC timestamp, YYYY-MM-DDTHH:MM:SSZ. The window is one hour.
example: 2026-10-23T14:40:00Z
|
| txid |
string or null
Set when status is seen. Cleared if that transfer disappears before it is credited.
example: null
|
| created_at |
string
When the top-up was created, UTC, YYYY-MM-DDTHH:MM:SSZ.
example: 2026-10-23T13:40:00Z
|
Returns the status of one top-up and the deposit address. Send the exact amount to that address.
| topup_id | string Required path parameter. A UUID. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
|---|
| topup_id | string UUID of the top-up. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
|---|---|
| idempotency_key |
string or null
The key sent with the request, unchanged. null when none was sent.
example: topup-20261023-0001
|
| address | string Deposit address. Omitted when the service has no deposit address configured. example: YOUR_TRON_ADDRESS |
| amount_trx |
string
The exact sum, six decimal places, in currency.
example: 25.030000
|
| currency |
string
trx or usdt.
example: usdt
|
| status |
string
pending is waiting for the transfer. seen means the transfer is on the network and is waiting for 19 confirmations. cooling means the window has closed and a transfer that arrived in time can still be matched. credited means the sum is on the balance. expired means it was not matched.
example: pending
|
| expires_at |
string
UTC timestamp, YYYY-MM-DDTHH:MM:SSZ.
example: 2026-10-23T14:40:00Z
|
| txid |
string or null
Set when status is seen or credited. Cleared if that transfer disappears before it is credited.
example: null
|
| confirmations |
integer
Present only when status is seen and the chain answered. How many blocks the transfer is behind the current head. 0 means the transfer is in the latest block. The top-up is credited when this reaches 19. Omitted when the chain did not answer.
example: 7
|
| created_at |
string
When the top-up was created, UTC, YYYY-MM-DDTHH:MM:SSZ.
example: 2026-10-23T13:40:00Z
|
Returns the callback address and secret stored for this account. Either value is null when callbacks are off.
| webhook_url | string or null The address gasrent posts to. example: https://example.com/gasrent |
|---|---|
| webhook_secret | string or null The HMAC key, at least 16 characters when a URL is set. example: replace-with-at-least-16-characters |
Saves the callback address and secret. An empty webhook_url turns callbacks off and clears the secret.
| webhook_url |
string
https only, at most 2048 characters. Empty turns callbacks off. Plain http, a loopback, a link-local, or a private address is rejected, and so is a name that does not resolve.
example: https://example.com/gasrent
|
|---|---|
| webhook_secret | string At least 16 characters, at most 255. Ignored when the URL is empty. example: replace-with-at-least-16-characters |
| webhook_url | string or null The address gasrent posts to. Null when callbacks are off. example: https://example.com/gasrent |
|---|---|
| webhook_secret | string or null The HMAC key, at least 16 characters when a URL is set. Null when callbacks are off. example: replace-with-at-least-16-characters |
The account stores a callback URL and a secret of at least 16 characters. Set them with POST /api/v1/webhook, or in the cabinet under API keys. When both are present, gasrent sends POST with Content-Type: application/json. The body bytes are the payload below. X-Signature is the hex HMAC-SHA256 of those bytes, keyed with the secret.
A response status from 200 to 299 completes the delivery. Any other result is retried. There are five attempts. The waits after a failed attempt are 60 seconds, 300 seconds, 900 seconds, and 3600 seconds. The fifth failure is not retried. Each event is queued once.
order.filled and order.cancelled:
| event |
string
order.filled or order.cancelled.
example: order.filled
|
|---|---|
| order_id | string UUID of the order that finished. example: a3f2c8e1-7b44-4d19-9c0e-6f1a2b3c4d5e |
| idempotency_key |
string or null
The key the client sent when this was created, unchanged. null when none was sent.
example: order-20261023-0001
|
| status |
string
Filled or Cancelled.
example: Filled
|
| price_trx | string Six decimal places. The same total as the order at send time. Includes activation when this order activated the address. A later cancelled activation is no longer in a new read of the order. example: 1.911000 |
| txid | string or null The delegation transaction, when one exists. example: null |
bandwidth.filled and bandwidth.cancelled:
| event |
string
bandwidth.filled or bandwidth.cancelled. These are not order.filled or order.cancelled.
example: bandwidth.filled
|
|---|---|
| resource |
string
Always bandwidth.
example: bandwidth
|
| order_id | string UUID of the bandwidth order that finished. example: d5e6f708-1920-4a1b-8c2d-3e4f5a6b7c8d |
| idempotency_key |
string or null
The key the client sent when this was created, unchanged. null when none was sent.
example: bandwidth-20261025-0001
|
| status |
string
Filled or Cancelled.
example: Filled
|
| volume | integer The bandwidth on the order. example: 1000 |
| duration | string The duration on the order. example: 1h |
| price_trx | string Six decimal places. The charge at send time. A cancelled order has already returned it. example: 0.801800 |
| txid | string or null The bandwidth delegation transaction, when one exists. example: null |
topup.credited:
| event |
string
topup.credited.
example: topup.credited
|
|---|---|
| topup_id | string UUID of the top-up that was credited. example: b7e1d4a2-6c33-4a18-8b0d-5e2f1a0b9c8d |
| idempotency_key |
string or null
The key the client sent when this was created, unchanged. null when none was sent.
example: topup-20261023-0001
|
| status |
string
credited.
example: credited
|
| amount_trx |
string
Six decimal places, in currency.
example: 25.030000
|
| currency |
string
trx or usdt. The balance that was credited.
example: usdt
|
| txid | string or null The deposit transaction. example: null |
activation.filled and activation.cancelled:
| event |
string
activation.filled or activation.cancelled.
example: activation.filled
|
|---|---|
| activation_id | string UUID of the activation. example: c4d8e2f1-1a22-4b33-8c44-7d5e6f708192 |
| idempotency_key |
string or null
The key the client sent when this was created, unchanged. null when none was sent. Also null for an activation that an order or a withdrawal started by itself.
example: activation-20261023-0001
|
| status |
string
Filled or Cancelled. Cancelled means the charge was returned.
example: Filled
|
| address | string The Tron address. example: YOUR_TRON_ADDRESS |
| price_trx | string Six decimal places. example: 1.397000 |
| txid | string or null The activation transaction. example: null |
pay_currency is trx or usdt. pay_amount is a positive decimal string with at most six digits after the point. preview is a boolean. Omitted means true. True prices the exchange and does not charge the balance. False performs it.
The quote reads the current market rate. receive_amount is what the exchange would deliver. It can move a little before the swap is sent. fee_trx is the energy rental for the swap, plus the bandwidth of the swap. The bandwidth is always included. The fee is not folded into the rate. debit_trx and debit_usdt are what would leave the balance. credit_trx and credit_usdt are what would be added. For TRX paid in, debit_trx is the amount plus the fee. For USDT paid in, debit_usdt is the amount and debit_trx is only the fee.
can_submit is true only when the balance covers the debit and the exchange can be filled. short is trx, usdt, both, wallet, or null. wallet means the exchange cannot be filled right now. The numbers are still returned.
A real exchange sends preview false, and may send fee_trx and receive_amount from the quote. If the fee has gone up, or the delivered amount is under 99 percent of receive_amount, the response is 409 price_changed and nothing is charged. Omit either field to accept the figure calculated on this call. The balance is charged first: the paid currency, then the TRX fee as its own ledger row. When the swap confirms, the received currency is credited with the amount the exchange actually delivered, which can differ a little from the quote. status is sending, sent, review, or failed. failed means the charge was refunded. The same idempotency key with the same currency and amount returns the original exchange. id is the exchange UUID. idempotency_key is the key sent with the request, unchanged, or null when none was sent. created_at is when it was created, UTC, YYYY-MM-DDTHH:MM:SSZ.
Returns one exchange on this account. id is the UUID from the exchange that was placed. The fields are the same as a completed POST. While status is sending, receive_amount is still the quote. After sent, it is the amount credited.
Prices a withdrawal without charging the balance. currency is trx or usdt. amount is a positive decimal string with at most six digits after the point. address is the TRON address that receives the payout.
For USDT, fee_trx is the energy rental for a transfer to address. The rental follows that address: a wallet that already holds USDT costs less energy than an empty one. For TRX, fee_trx is the TRX burned to buy bandwidth for a plain transfer when bandwidth is zero. When address is not activated yet, activation is true and activation_trx is the activation price. That price is charged as its own activation, with its own balance row and its own chain transaction, before the payout is sent. fee_trx does not include it. An address that is already active leaves activation false and activation_trx at zero. debit_trx is the TRX that would leave the balance: the fee and the activation for USDT, or the amount plus both for TRX. can_submit is true only when the balance covers that charge. short is trx, usdt, both, or null. If the balance of the chosen currency is already below amount, the quote does not ask the chain. fee_trx and debit_trx are null, can_submit is false, and short is that currency.
Withdraws amount of currency to address. Send fee_trx and activation_trx from the quote. If either has gone up, the response is 409 price_changed and nothing is charged. If either has gone down, the lower figure is charged. Omit either field to accept the figure calculated on this call. When activation_trx is above zero, the activation is charged and sent first. Its balance row is separate from the withdrawal. If the payout later fails, the withdrawal is returned and the activation is not. The withdrawal then has activation (true when that charge happened), activation_trx (that price, or zero), and activation_id (the public id of the activation, or null). debit_trx includes the activation. A 503 can arrive after the activation was already charged. The same idempotency key continues that activation and does not charge it again. If that activation was cancelled and the price was returned, the same key starts a new one.
USDT is debited from the USDT balance and the fee from the TRX balance. The service then rents the energy and sends the USDT. TRX debits the amount and the fee together, then sends the amount. A blocked account cannot quote or withdraw. The same idempotency key with the same currency, amount, and address returns the original withdrawal. A different currency, amount, or address returns conflict.
status is sent when txid exists, sending while the payout is still going out, review when the payout is being checked, and failed when nothing was sent and the balance was refunded. On sent, a notice with a link to the transaction is emailed to the account. idempotency_key is the key sent with the request, unchanged, or null when none was sent. created_at is when the withdrawal was created, UTC, YYYY-MM-DDTHH:MM:SS.sssZ.
A withdrawal goes only to an address from the account list. This call returns delay_hours and addresses. Each address has id, address, status (pending waits for the emailed code, active is confirmed), usable (true when a withdrawal to it is allowed now), and active_from (UTC, YYYY-MM-DDTHH:MM:SS.sssZ, or null while pending). A new address becomes usable delay_hours hours after it is confirmed, 24 by default. Addresses that already received a withdrawal before this rule were added as usable.
Adding and removing addresses is possible only from the cabinet, with a signed-in session. An API key can read the list, but POST /api/v1/withdraw/address, POST /api/v1/withdraw/address/confirm, and DELETE /api/v1/withdraw/address/{id} with a key return 401 unauthorized. A 6-digit code goes to the account email and is valid for 10 minutes. A wrong code is 400 bad_code. At most 20 addresses can be kept: more is 409 address_limit.
POST /api/v1/withdraw/quote and POST /api/v1/withdraw return 403 address_not_allowed when address is not on the list, and 403 address_locked when it was confirmed but its waiting time has not ended. A withdrawal that would take the sum of the last 24 hours over the daily limit returns 403 daily_limit. Failed and refunded withdrawals do not count. The limit is set per currency: 20000 TRX and 5000 USDT.
100 requests in the current UTC minute and 5000 requests in the current UTC hour, per account. Every method shares both counters. A minute starts at second 00 and an hour at minute 00. These are fixed clocks, not a sliding span: a request just before the mark and a request just after it fall into different windows, so two bursts can sit on either side of that second. GET /api/v1/health is not counted. The response is 429 rate_limited. A quote, an activation, an energy check, an energy order, or a bandwidth order that does not finish in time is 503 unavailable. The same code is returned when the health check finds the service is not ready, and when no supplier can sell the requested bandwidth.
400 too_many_addresses: POST /api/v1/energy to_addresses has more than 20 items.400 bad_request: the body is not JSON, POST /api/v1/energy has both to_address and to_addresses, an order before_id is not a UUID, a transaction query parameter is invalid, or top-up currency is not trx or usdt.400 bad_address: a Tron address failed validation, or to_addresses is empty or not a list of strings.400 bad_destination: a withdrawal address is a gasrent service address.400 inactive_address: POST /api/v1/energy sender is not activated. A quote or an order returns this when no_activation is true and the address is not activated. Otherwise a quote includes the activation fee and an order activates the address itself.400 already_active: POST /api/v1/activation was asked to activate an address that is already active.400 bad_duration: energy duration is not one of 15m, 1h, 1d, 3d. Bandwidth duration is not one of 5m, 1h, 1d, 3d, 7d.400 bad_volume: energy volume is outside 65000 to 4000000, or bandwidth volume is outside 1 to 100000.400 insufficient_usdt: POST /api/v1/energy sender holds no USDT. The reverted simulation is not reported as required_energy.400 transfer_reverted: the sender holds some USDT, but the USDT transfer still reverts.400 bad_flags: exact_volume, exact_duration, or no_activation is present and is not a JSON boolean. Omitted flags mean false. Bandwidth accepts exact_volume and exact_duration only. preview on an exchange must be a JSON boolean. Omitted means true.400 bad_amount: top-up amount_trx is not an integer of at least 1. A withdrawal amount, an exchange pay_amount, or fee_trx / receive_amount is not a decimal with at most six digits after the point. pay_amount and receive_amount must be greater than zero. fee_trx may be zero.400 bad_key: the idempotency key is shorter than 8 or longer than 128 characters, or the header and the body disagree.400 bad_webhook: the callback address is not a public https URL, the name does not resolve, the address is longer than 2048 characters, or the secret is shorter than 16 characters or longer than 255.400 volume_too_large: no single order can fill that volume.401 unauthorized: X-API-KEY is missing, empty, or does not match an active key. GET /api/v1/health does not use a key.402 insufficient_balance: the balance is below the charge. An order for an inactive address needs the energy price and the activation fee together.402 insufficient_funds: the TRX or USDT balance cannot cover this withdrawal or exchange.403 forbidden: the account is blocked. GET remains available, including bandwidth orders. Quote, activation, energy order, bandwidth quote, bandwidth order, energy, top-up creation, withdrawal, and exchange do not.403 ip_not_allowed: the account whitelist has at least one IPv4 address, and the caller is not on it.403 key_read_only: the key is read only. GET remains available. Any other method is refused.403 address_not_allowed: the withdrawal address is not on the account withdrawal list.403 address_locked: the withdrawal address was confirmed, but its waiting time has not ended.403 daily_limit: the withdrawal would take the last 24 hours over the daily limit for that currency.400 bad_code: the emailed code for a withdrawal address is wrong, expired, or already used.409 address_limit: the account already has 20 withdrawal addresses.404 not_found: no such energy order, bandwidth order, activation, or top-up, or no such path. An energy id is not found on a bandwidth path, and the reverse is also true.409 conflict: this idempotency key was already used with a different body.409 price_changed: a withdrawal fee_trx or activation_trx, or an exchange fee_trx, is higher than the figure sent with the request, or the exchange delivered amount is under 99 percent of receive_amount. Quote again. Nothing was charged.429 rate_limited: the account sent more than 100 requests in the current UTC minute or more than 5000 in the current UTC hour, or a top-up could not be opened because every sum from the requested amount through 1 more, in steps of 0.01, is already reserved in that currency.429 too_many_topups: the account already has 5 unfinished top-ups (pending, cooling, or seen).503 offers_rejected: no supplier accepted the energy order. A bandwidth order that no supplier can fill is 503 unavailable.503 unavailable: the market did not answer in time, the activation could not be sent, the health check finds the service is not ready, no supplier can sell the requested bandwidth, a withdrawal cannot be priced or paid right now, or an exchange cannot be priced or filled.500 internal: an error on the service side.