Endpoints

tronbase API documentation

Rent TRON Energy and Bandwidth from an account balance. Amounts are whole SUN (1 TRX = 1,000,000 SUN).

Base URL · version 1.0.0

https://tronbase.io/api/v1

Authentication

Send the key as a bearer token on every request. An energy key from the dashboard, tbc_…. Its scope decides which endpoints it opens.

Amounts are whole SUN: 1 TRX = 1,000,000 SUN. Keys with the purchase scope can place orders; full keys can also manage standing orders.

Header

Authorization: Bearer tbc_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Errors

Failures use an ordinary HTTP status and one JSON envelope. code is stable and safe to branch on; message is for people. Field errors, and amounts such as needed, are in details.

Error response · 402

{
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough balance for this order.",
    "details": {
      "needed": "3.2"
    }
  }
}

Account

Who the key belongs to and what it can spend.

The account behind the key

GET/account

Who owns the key, the balance in SUN, the deposit address, and the webhooks registered on the account.

Response 200

dataobjectrequired
data.idinteger
data.emailstring · email
data.balanceSuninteger
data.depositAddressstring | null
data.webhooksobject[]
data.webhooks[].idinteger
data.webhooks[].urlstring
data.webhooks[].activeboolean

Status codes

200The account.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/account/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": {
    "id": 41,
    "email": "dev@example.com",
    "balanceSun": 0,
    "depositAddress": "string",
    "webhooks": [
      {
        "id": 41,
        "url": "string",
        "active": true
      }
    ]
  }
}

Orders

Buying energy and bandwidth.

Recent orders

GET/orders

Newest first. A recent-activity feed rather than a full history, so there is no pagination.

Parameters

limitinteger · query
default 20 · 1 – 100

Response 200

dataobject[]required
data[].idintegerrequired
data[].statusstringrequired
one of "pending", "sent", "filled", "failed"
data[].resourcestringrequired
one of "energy", "bandwidth"
data[].addressstringrequired
The address the resource was delegated to.
data[].volumeintegerrequired
Units of the resource.
data[].durationstringrequired
one of "15m"
data[].priceSunintegerrequired
The resource itself, in SUN.
data[].feeSunintegerrequired
Flat fee, one per order.
data[].activationSunintegerrequired
Charged once per address, ever. Zero when the address already existed.
data[].totalSunintegerrequired
What was charged to the balance.
data[].txIdstring | null
data[].errorstring | null
The provider's reason, on a failed order.
data[].createdAtstring · date-time
data[].updatedAtstring · date-time

Status codes

200The orders.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/orders/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": [
    {
      "id": 41,
      "status": "pending",
      "resource": "energy",
      "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
      "volume": 65000,
      "duration": "15m",
      "priceSun": 0,
      "feeSun": 0,
      "activationSun": 0,
      "totalSun": 0,
      "txId": "9f2c1a7e5b3d48c0a6e1f4d2b8c7a3e5d1f0b9c8a7e6d5c4b3a291807f6e5d4c",
      "error": "string",
      "createdAt": "2026-11-04T09:30:00Z",
      "updatedAt": "2026-11-04T09:30:00Z"
    }
  ]
}

Buy energy or bandwidth

POST/orders

Charges the balance immediately, then delegates. Energy is rented for fifteen minutes, so place the order right before the transfer it is for. Send Idempotency-Key to make a retry safe. Needs a purchase key.

Parameters

Idempotency-Keystring · header
A retry with the same key returns the first attempt's answer instead of buying twice. Kept 24 hours.
max 255 chars

Request body · application/json

addressstringrequired
The address that SENDS the USDT — energy is spent by the sender.
volumeintegerrequired
65,000 covers one USDT transfer to a recipient that already holds USDT; 131,000 one to a recipient whose USDT balance is zero.
resourcestring
one of "energy", "bandwidth" · default "energy"
durationstring
one of "15m" · default "15m"

Response 201

dataobjectrequired
data.idintegerrequired
data.statusstringrequired
one of "pending", "sent", "filled", "failed"
data.resourcestringrequired
one of "energy", "bandwidth"
data.addressstringrequired
The address the resource was delegated to.
data.volumeintegerrequired
Units of the resource.
data.durationstringrequired
one of "15m"
data.priceSunintegerrequired
The resource itself, in SUN.
data.feeSunintegerrequired
Flat fee, one per order.
data.activationSunintegerrequired
Charged once per address, ever. Zero when the address already existed.
data.totalSunintegerrequired
What was charged to the balance.
data.txIdstring | null
data.errorstring | null
The provider's reason, on a failed order.
data.createdAtstring · date-time
data.updatedAtstring · date-time

Status codes

201The order, charged and placed.
401Missing, invalid or revoked key, or a blocked owner.
402The balance does not cover the order; details.needed is the amount in TRX.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
409The order is in doubt and must not be retried, or an idempotent request is still in flight.
422Field errors, an idempotency key reused for a different body, or a refusal by the provider.
429Too many requests. Retry-After says when to come back.
503Orders are not being taken right now.

curl -X POST https://tronbase.io/api/v1/orders/ \
  -H "Authorization: Bearer $TRONBASE_KEY" \
  -H "Idempotency-Key: 7f3a9c52-order-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "resource": "energy",
    "duration": "15m"
  }'

Response

{
  "data": {
    "id": 41,
    "status": "pending",
    "resource": "energy",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "duration": "15m",
    "priceSun": 0,
    "feeSun": 0,
    "activationSun": 0,
    "totalSun": 0,
    "txId": "9f2c1a7e5b3d48c0a6e1f4d2b8c7a3e5d1f0b9c8a7e6d5c4b3a291807f6e5d4c",
    "error": "string",
    "createdAt": "2026-11-04T09:30:00Z",
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

One order

GET/orders/{id}

Parameters

idinteger · pathrequired

Response 200

dataobjectrequired
data.idintegerrequired
data.statusstringrequired
one of "pending", "sent", "filled", "failed"
data.resourcestringrequired
one of "energy", "bandwidth"
data.addressstringrequired
The address the resource was delegated to.
data.volumeintegerrequired
Units of the resource.
data.durationstringrequired
one of "15m"
data.priceSunintegerrequired
The resource itself, in SUN.
data.feeSunintegerrequired
Flat fee, one per order.
data.activationSunintegerrequired
Charged once per address, ever. Zero when the address already existed.
data.totalSunintegerrequired
What was charged to the balance.
data.txIdstring | null
data.errorstring | null
The provider's reason, on a failed order.
data.createdAtstring · date-time
data.updatedAtstring · date-time

Status codes

200The order.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
404No such order, or it belongs to someone else.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/orders/41/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": {
    "id": 41,
    "status": "pending",
    "resource": "energy",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "duration": "15m",
    "priceSun": 0,
    "feeSun": 0,
    "activationSun": 0,
    "totalSun": 0,
    "txId": "9f2c1a7e5b3d48c0a6e1f4d2b8c7a3e5d1f0b9c8a7e6d5c4b3a291807f6e5d4c",
    "error": "string",
    "createdAt": "2026-11-04T09:30:00Z",
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

Automations

Standing orders that buy without being asked.

Standing orders

GET/automations

Response 200

dataobject[]required
data[].idintegerrequired
data[].kindstringrequired
one of "refill", "renewal"
data[].addressstringrequired
data[].volumeintegerrequired
Energy bought each time the rule fires.
data[].thresholdEnergyinteger | null
refill only: buy when the address falls below this.
data[].runAtMinuteinteger | null
renewal only: minutes past midnight UTC, 0–1439.
data[].statusstringrequired
one of "active", "paused", "suspended", "canceled"
data[].pausedBystring | null
one of "user", "system"
data[].autoResumebooleanrequired
Whether a rule the system suspended restarts after a top-up.
data[].lastFiredAtstring · date-time | null
data[].silentSincestring · date-time | null
Set when a daily rule has missed its slot.
data[].errorstring | null
data[].createdAtstring · date-time
data[].updatedAtstring · date-time

Status codes

200The rules.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/automations/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": [
    {
      "id": 41,
      "kind": "refill",
      "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
      "volume": 65000,
      "thresholdEnergy": 0,
      "runAtMinute": 0,
      "status": "active",
      "pausedBy": "user",
      "autoResume": true,
      "lastFiredAt": "2026-11-04T09:30:00Z",
      "silentSince": "2026-11-04T09:30:00Z",
      "error": "string",
      "createdAt": "2026-11-04T09:30:00Z",
      "updatedAt": "2026-11-04T09:30:00Z"
    }
  ]
}

Create a standing order

POST/automations

Commits future spending: the rule buys again tomorrow with nobody watching. Needs a full key.

Request body · application/json

kindstringrequired
one of "refill", "renewal"
addressstringrequired
volumeintegerrequired
thresholdEnergyinteger
refill only.
runAtMinuteinteger
renewal only.
0 – 1439

Response 201

dataobjectrequired
data.idintegerrequired
data.kindstringrequired
one of "refill", "renewal"
data.addressstringrequired
data.volumeintegerrequired
Energy bought each time the rule fires.
data.thresholdEnergyinteger | null
refill only: buy when the address falls below this.
data.runAtMinuteinteger | null
renewal only: minutes past midnight UTC, 0–1439.
data.statusstringrequired
one of "active", "paused", "suspended", "canceled"
data.pausedBystring | null
one of "user", "system"
data.autoResumebooleanrequired
Whether a rule the system suspended restarts after a top-up.
data.lastFiredAtstring · date-time | null
data.silentSincestring · date-time | null
Set when a daily rule has missed its slot.
data.errorstring | null
data.createdAtstring · date-time
data.updatedAtstring · date-time

Status codes

201The rule, already running.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
422Field errors, or the rule was refused — the message says why.
429Too many requests. Retry-After says when to come back.

curl -X POST https://tronbase.io/api/v1/automations/ \
  -H "Authorization: Bearer $TRONBASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "refill",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000
  }'

Response

{
  "data": {
    "id": 41,
    "kind": "refill",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "thresholdEnergy": 0,
    "runAtMinute": 0,
    "status": "active",
    "pausedBy": "user",
    "autoResume": true,
    "lastFiredAt": "2026-11-04T09:30:00Z",
    "silentSince": "2026-11-04T09:30:00Z",
    "error": "string",
    "createdAt": "2026-11-04T09:30:00Z",
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

One standing order

GET/automations/{id}

Parameters

idinteger · pathrequired

Response 200

dataobjectrequired
data.idintegerrequired
data.kindstringrequired
one of "refill", "renewal"
data.addressstringrequired
data.volumeintegerrequired
Energy bought each time the rule fires.
data.thresholdEnergyinteger | null
refill only: buy when the address falls below this.
data.runAtMinuteinteger | null
renewal only: minutes past midnight UTC, 0–1439.
data.statusstringrequired
one of "active", "paused", "suspended", "canceled"
data.pausedBystring | null
one of "user", "system"
data.autoResumebooleanrequired
Whether a rule the system suspended restarts after a top-up.
data.lastFiredAtstring · date-time | null
data.silentSincestring · date-time | null
Set when a daily rule has missed its slot.
data.errorstring | null
data.createdAtstring · date-time
data.updatedAtstring · date-time

Status codes

200The rule.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
404No such rule, or it belongs to someone else.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/automations/41/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": {
    "id": 41,
    "kind": "refill",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "thresholdEnergy": 0,
    "runAtMinute": 0,
    "status": "active",
    "pausedBy": "user",
    "autoResume": true,
    "lastFiredAt": "2026-11-04T09:30:00Z",
    "silentSince": "2026-11-04T09:30:00Z",
    "error": "string",
    "createdAt": "2026-11-04T09:30:00Z",
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

Pause, resume, or change what happens after a top-up

PATCH/automations/{id}

Resuming is refused while the balance cannot cover one firing. Needs a full key.

Parameters

idinteger · pathrequired

Request body · application/json

statusstring
one of "active", "paused"
autoResumeboolean

Response 200

dataobjectrequired
data.idintegerrequired
data.kindstringrequired
one of "refill", "renewal"
data.addressstringrequired
data.volumeintegerrequired
Energy bought each time the rule fires.
data.thresholdEnergyinteger | null
refill only: buy when the address falls below this.
data.runAtMinuteinteger | null
renewal only: minutes past midnight UTC, 0–1439.
data.statusstringrequired
one of "active", "paused", "suspended", "canceled"
data.pausedBystring | null
one of "user", "system"
data.autoResumebooleanrequired
Whether a rule the system suspended restarts after a top-up.
data.lastFiredAtstring · date-time | null
data.silentSincestring · date-time | null
Set when a daily rule has missed its slot.
data.errorstring | null
data.createdAtstring · date-time
data.updatedAtstring · date-time

Status codes

200The rule as it now stands.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
404No such rule.
422The change was refused — the message says why.
429Too many requests. Retry-After says when to come back.

curl -X PATCH https://tronbase.io/api/v1/automations/41/ \
  -H "Authorization: Bearer $TRONBASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "autoResume": true
  }'

Response

{
  "data": {
    "id": 41,
    "kind": "refill",
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "volume": 65000,
    "thresholdEnergy": 0,
    "runAtMinute": 0,
    "status": "active",
    "pausedBy": "user",
    "autoResume": true,
    "lastFiredAt": "2026-11-04T09:30:00Z",
    "silentSince": "2026-11-04T09:30:00Z",
    "error": "string",
    "createdAt": "2026-11-04T09:30:00Z",
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

Stop a standing order for good

DELETE/automations/{id}

It cannot be started again; create a new one instead. Needs a full key.

Parameters

idinteger · pathrequired

Status codes

204Stopped.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
404No such rule.
429Too many requests. Retry-After says when to come back.

curl -X DELETE https://tronbase.io/api/v1/automations/41/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

No body.

Reference

Prices, addresses and the documentation itself.

Current prices

GET/prices

Response 200

dataobjectrequired
data.durationstring
one of "15m"
data.energyobject
data.energy.sunPerUnitnumber
SUN per unit of energy.
data.energy.mininteger
Smallest order, in energy.
data.energy.maxinteger
Largest order, in energy.
data.energy.perTransferinteger
Energy one USDT transfer to a funded recipient burns.
data.energy.transferSuninteger
What one transfer's worth of energy costs, fee included.
data.bandwidthobject
data.bandwidth.sunPer1knumber
SUN per 1,000 units of bandwidth.
data.bandwidth.mininteger
data.bandwidth.maxinteger
data.feeSuninteger
Flat fee, one per order.
data.activationSuninteger
Charged once per address that does not exist on-chain yet.
data.updatedAtstring · date-time

Status codes

200Prices, order sizes and the activation fee.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/prices/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": {
    "duration": "15m",
    "energy": {
      "sunPerUnit": 0,
      "min": 0,
      "max": 0,
      "perTransfer": 0,
      "transferSun": 0
    },
    "bandwidth": {
      "sunPer1k": 0,
      "min": 0,
      "max": 0
    },
    "feeSun": 0,
    "activationSun": 0,
    "updatedAt": "2026-11-04T09:30:00Z"
  }
}

What an address holds on-chain

GET/address/{address}

Parameters

addressstring · pathrequired
A TRON address.

Response 200

dataobjectrequired
data.addressstring
data.activatedboolean
data.activationSuninteger
Zero when the address already exists.
data.trxBalanceSuninteger
data.energyobject
data.energy.availableinteger
data.energy.limitinteger
data.bandwidthobject
data.bandwidth.availableinteger
data.bandwidth.limitinteger
data.transfersCoveredinteger
USDT transfers the energy on hand pays for.
data.energyForNextTransferinteger
Energy still missing for the next transfer; zero when covered.
data.durationstring
one of "15m"

Status codes

200What the address has, and whether activation is due.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.
503The address could not be read from the network.

curl https://tronbase.io/api/v1/address/TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

{
  "data": {
    "address": "TJ8bLmQ4vXFyRkC2nDp7WsEhG6aUz9YtKn",
    "activated": true,
    "activationSun": 0,
    "trxBalanceSun": 0,
    "energy": {
      "available": 0,
      "limit": 0
    },
    "bandwidth": {
      "available": 0,
      "limit": 0
    },
    "transfersCovered": 0,
    "energyForNextTransfer": 0,
    "duration": "15m"
  }
}

These docs as Markdown

GET/docs

Send If-None-Match with the last ETag to get a 304 when nothing has changed.

Status codes

200The documentation.
304Unchanged since the ETag you sent.
401Missing, invalid or revoked key, or a blocked owner.
403The key's scope does not reach this endpoint, or it has spent its allowance for the day.
429Too many requests. Retry-After says when to come back.

curl https://tronbase.io/api/v1/docs/ \
  -H "Authorization: Bearer $TRONBASE_KEY"

Response

# Markdown document