TRON Energy API reference

v953d09feef0b · 2026-10-05

Buy TRON Energy from your own code, paid from your GetGas balance. Generated from the API itself, so it always matches what is deployed.

Get an API key Open as Markdown

GetGas Energy API

Buy TRON Energy and Bandwidth for any address from your GetGas balance — once, or automatically — so USDT transfers cost a fraction of the TRX they would burn. JSON in and out; amounts are integers in sun (1 TRX = 1,000,000 sun) with an exact TRX string beside each.

Base URLhttps://getgas.io/api/v1

AuthorizationBearer Token

Create an account, then a key on API & Keys in the dashboard. Send it as Authorization: Bearer <key>, and keep it on your server, never in browser code. Limits: 120 requests a minute per key, 30 new orders a minute per account.

Authorization

Authorization: Bearer <your API key>

Account

GET Get account

GEThttps://getgas.io/api/v1/account

Balance, the deposit address for topping it up, and this account's prices.

The deposit address is permanent and belongs to this account: send TRX or USDT (TRC-20) to it and the balance is credited after the payment confirms, usually within a few minutes. Poll this endpoint or GET /deposits to see it arrive.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Account}

Errors

401 unauthorized 403 ip_not_allowed 429 rate_limited

Example request

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

Example response · 200 OK

{
  "data": {
    "email": "you@example.com",
    "balanceSun": 1275000,
    "balanceTrx": "1.275",
    "depositAddress": "TDeposit...address...",
    "depositNetwork": "TRC20",
    "depositCurrencies": [
      "TRX",
      "USDT-TRC20"
    ],
    "rates": {}
  }
}

GET List deposits

GEThttps://getgas.io/api/v1/deposits

Payments received at the deposit address, newest first.

Includes payments that are still confirming (creditedAt is null).

AuthorizationBearer Token · your API key

Query params

`limit`	1–100, default 25.
`offset`	Items to skip, default 0.

Response

200 OK — {"data": [Deposit, ...]}

Errors

400 invalid_query 401 unauthorized 403 ip_not_allowed 429 rate_limited

Example request

curl "https://getgas.io/api/v1/deposits?limit=10" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": [
    {
      "id": 123,
      "transactionId": "a3f1…9c2e",
      "currency": "TRX",
      "amount": "25",
      "netAmount": "25",
      "creditedSun": 1275000,
      "status": "active",
      "receivedAt": "2026-10-05T12:00:00.000Z",
      "creditedAt": null
    }
  ]
}

Prices

GET Get prices

GEThttps://getgas.io/api/v1/prices

Current prices and order limits.

No API key needed. These follow the provider's price and are refreshed every few minutes, so read them before quoting a price to a user. Rates are sun per unit; an order costs volume × rate + orderFeeSun (a fixed fee per order). An account with its own rates sees them in GET /account.

AuthorizationNo auth

Response

200 OK —

{"data": {"currency": "TRX", "updatedAt", "energy": {"minVolume", "maxVolume", "terms": [{"term", "label", "sunPerUnit"}]}, "bandwidth": {"minVolume", "maxVolume", "sunPerUnit"}, "orderFeeSun", "smartDeliverySun", "activationSun", "usdtTransfer": {"energyToHolder", "energyToNewHolder"}}}

Example request

curl "https://getgas.io/api/v1/prices"

Example response · 200 OK

{"data": {"currency": "TRX", "updatedAt", "energy": {"minVolume", "maxVolume", "terms": [{"term", "label", "sunPerUnit"}]}, "bandwidth": {"minVolume", "maxVolume", "sunPerUnit"}, "orderFeeSun", "smartDeliverySun", "activationSun", "usdtTransfer": {"energyToHolder", "energyToNewHolder"}}}

Orders

POST Create order

POSThttps://getgas.io/api/v1/orders

Buy Energy or Bandwidth for any TRON address, paid from the balance.

The price is charged when the order is accepted. The response is the order: "submitted" means it is on its way, usually filled within a minute; poll GET /orders/{id} until the status is final. If the network refuses it, the order comes back "refunded" and the money is already back on the balance. Retrying with the same Idempotency-Key never buys twice: it returns the first order.

AuthorizationBearer Token · your API key

Headers

Idempotency-Key

Required. A unique string per purchase (8–64 of A–Z a–z 0–9 - _), e.g. a UUID. Reuse it when retrying the same purchase; use a new one for a new purchase.

Body · raw (json)

`resource` string	"energy" (default) or "bandwidth". Bandwidth: 1,000–100,000 per order; one plain transfer needs about 350.
`address` string · required	TRON address that receives the Energy (starts with T, 34 characters). It does not have to be yours.
`volume` integer · required	Amount of the resource. Energy: 65,000–5,000,000. One USDT transfer to an address that already holds USDT needs about 65,000; to an address that holds no USDT, about 131,000.
`term` string · required	How long the resource stays delegated: "15m" or "1h".

Response

201 Created — {"data": Order} for a new order. 200 OK — {"data": Order} when the Idempotency-Key was already used for the same order.

Errors

400 invalid_idempotency_key 400 invalid_json 401 unauthorized 402 insufficient_funds 409 idempotency_conflict 415 unsupported_media_type 422 validation_failed 422 volume_out_of_range 429 rate_limited 503 provider_unavailable

Example request

curl -X POST "https://getgas.io/api/v1/orders" \
  -H "Authorization: Bearer $GETGAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"address": "TXYZ...your-address...", "volume": 65000, "term": "1h"}'

Example response · 201 Created

{
  "data": {
    "id": 123,
    "status": "submitted",
    "resource": "energy",
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "term": "1h",
    "priceSun": 2730000,
    "priceTrx": "2.73",
    "txId": "5c1e...",
    "createdAt": "2026-09-29T10:00:00.000Z",
    "updatedAt": "2026-09-29T10:00:01.000Z"
  }
}

GET List orders

GEThttps://getgas.io/api/v1/orders

Orders on this account, newest first.

Includes orders placed on the website.

AuthorizationBearer Token · your API key

Query params

`limit`	1–100, default 25.
`offset`	Items to skip, default 0.

Response

200 OK — {"data": [Order, ...]}

Errors

400 invalid_query 401 unauthorized 403 ip_not_allowed 429 rate_limited

Example request

curl "https://getgas.io/api/v1/orders?limit=10" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": [
    {
      "id": 123,
      "status": "submitted",
      "resource": "energy",
      "address": "TXYZ...your-address...",
      "volume": 65000,
      "term": "1h",
      "priceSun": 2730000,
      "priceTrx": "2.73",
      "txId": "5c1e...",
      "createdAt": "2026-09-29T10:00:00.000Z",
      "updatedAt": "2026-09-29T10:00:01.000Z"
    }
  ]
}

GET Get order

GEThttps://getgas.io/api/v1/orders/{id}

One order, with its current status.

Checks delivery with the network while the order is "submitted", so polling this is how an order reaches "filled". Poll every few seconds, not faster.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Order}

Errors

401 unauthorized 403 ip_not_allowed 404 not_found 429 rate_limited

Example request

curl "https://getgas.io/api/v1/orders/123" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "id": 123,
    "status": "submitted",
    "resource": "energy",
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "term": "1h",
    "priceSun": 2730000,
    "priceTrx": "2.73",
    "txId": "5c1e...",
    "createdAt": "2026-09-29T10:00:00.000Z",
    "updatedAt": "2026-09-29T10:00:01.000Z"
  }
}

Addresses

GET Check address

GEThttps://getgas.io/api/v1/addresses/{address}

Whether an address exists on-chain, and what activating it costs.

A brand-new address that has never received anything does not exist on-chain yet, and resources cannot be delegated to it. Check before buying for an address you have not used before.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": AddressCheck}

Errors

401 unauthorized 403 ip_not_allowed 422 validation_failed 429 rate_limited 503 provider_unavailable

Example request

curl "https://getgas.io/api/v1/addresses/TXYZ...your-address..." \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "address": "TXYZ...your-address...",
    "isActivated": true,
    "activationSun": 1275000
  }
}

POST Activate address

POSThttps://getgas.io/api/v1/addresses/{address}/activate

Activate a new address, paid from the balance.

Safe to retry: an address that is already activated is never charged again, and the answer is then its AddressCheck (200). The price is the provider's activation fee.

AuthorizationBearer Token · your API key

Response

201 Created — {"data": Activation}. 200 OK — {"data": AddressCheck} when it was already activated.

Errors

401 unauthorized 403 ip_not_allowed 402 insufficient_funds 422 validation_failed 429 rate_limited 503 provider_unavailable

Example request

curl -X POST "https://getgas.io/api/v1/addresses/TXYZ...your-address.../activate" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 201 Created

{
  "data": {
    "id": 123,
    "address": "TXYZ...your-address...",
    "status": "active",
    "priceSun": 1275000,
    "priceTrx": "1.275",
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

Automations

GET List automations

GEThttps://getgas.io/api/v1/automations

This account's automations (not removed), newest first.

Includes automations created on the website.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": [Automation, ...]}

Errors

401 unauthorized 403 ip_not_allowed 429 rate_limited

Example request

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

Example response · 200 OK

{
  "data": [
    {
      "id": 123,
      "kind": "refill",
      "status": "active",
      "pauseReason": null,
      "autoResume": true,
      "address": "TXYZ...your-address...",
      "volume": 65000,
      "minimal": 65000,
      "term": "1h",
      "nextDeliverySun": 1275000,
      "deliveries": 3,
      "lastDeliveryAt": null,
      "createdAt": "2026-10-05T12:00:00.000Z"
    }
  ]
}

POST Create automation

POSThttps://getgas.io/api/v1/automations

Start auto-refill, auto-renewal or smart mode on an address.

The balance must cover at least one delivery to start. Each delivery is then charged from the balance as it happens — see "Automations".

AuthorizationBearer Token · your API key

Body · raw (json)

`kind` string · required	"refill", "renewal" or "smart". See "Automations".
`address` string · required	TRON address to keep supplied.
`volume` integer	refill: Energy added each time, 65,000–5,000,000. renewal: Energy kept on the address, 65,000–1,000,000. Not used by smart (always 131,000).
`minimal` integer	refill only: add Energy when the address has less than this, 0–5,000,000.
`term` string	refill only: how long each delivery lasts, "1h" (the default and the only value).

Response

201 Created — {"data": Automation}

Errors

400 invalid_json 401 unauthorized 402 insufficient_funds 409 automation_exists 415 unsupported_media_type 422 validation_failed 429 rate_limited 503 provider_unavailable

Example request

curl -X POST "https://getgas.io/api/v1/automations" \
  -H "Authorization: Bearer $GETGAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "refill", "address": "TXYZ...your-address...", "volume": 131000, "minimal": 65000, "term": "1h"}'

Example response · 201 Created

{
  "data": {
    "id": 123,
    "kind": "refill",
    "status": "active",
    "pauseReason": null,
    "autoResume": true,
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "minimal": 65000,
    "term": "1h",
    "nextDeliverySun": 1275000,
    "deliveries": 3,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

GET Get automation

GEThttps://getgas.io/api/v1/automations/{id}

One automation.

Removed automations are still returned here, with status "removed".

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Automation}

Errors

401 unauthorized 403 ip_not_allowed 404 not_found 429 rate_limited

Example request

curl "https://getgas.io/api/v1/automations/7" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "id": 123,
    "kind": "refill",
    "status": "active",
    "pauseReason": null,
    "autoResume": true,
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "minimal": 65000,
    "term": "1h",
    "nextDeliverySun": 1275000,
    "deliveries": 3,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

POST Pause automation

POSThttps://getgas.io/api/v1/automations/{id}/pause

Pause an automation.

No deliveries until it is resumed. A pause made here is never lifted automatically.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Automation}

Errors

401 unauthorized 403 ip_not_allowed 404 not_found 429 rate_limited 503 provider_unavailable

Example request

curl -X POST "https://getgas.io/api/v1/automations/7/pause" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "id": 123,
    "kind": "refill",
    "status": "active",
    "pauseReason": null,
    "autoResume": true,
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "minimal": 65000,
    "term": "1h",
    "nextDeliverySun": 1275000,
    "deliveries": 3,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

POST Resume automation

POSThttps://getgas.io/api/v1/automations/{id}/resume

Resume a paused automation.

The balance must cover the next delivery.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Automation}

Errors

401 unauthorized 403 ip_not_allowed 402 insufficient_funds 404 not_found 429 rate_limited 503 provider_unavailable

Example request

curl -X POST "https://getgas.io/api/v1/automations/7/resume" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "id": 123,
    "kind": "refill",
    "status": "active",
    "pauseReason": null,
    "autoResume": true,
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "minimal": 65000,
    "term": "1h",
    "nextDeliverySun": 1275000,
    "deliveries": 3,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

DELETE Remove automation

DELETEhttps://getgas.io/api/v1/automations/{id}

Remove an automation for good.

Deliveries already made stay billed and listed.

AuthorizationBearer Token · your API key

Response

200 OK — {"data": Automation} with status "removed".

Errors

401 unauthorized 403 ip_not_allowed 404 not_found 429 rate_limited 503 provider_unavailable

Example request

curl -X DELETE "https://getgas.io/api/v1/automations/7" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": {
    "id": 123,
    "kind": "refill",
    "status": "active",
    "pauseReason": null,
    "autoResume": true,
    "address": "TXYZ...your-address...",
    "volume": 65000,
    "minimal": 65000,
    "term": "1h",
    "nextDeliverySun": 1275000,
    "deliveries": 3,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-05T12:00:00.000Z"
  }
}

GET List deliveries

GEThttps://getgas.io/api/v1/deliveries

Deliveries made by automations, newest first, with what each cost.

One row per delivery, charged once.

AuthorizationBearer Token · your API key

Query params

`limit`	1–100, default 25.
`offset`	Items to skip, default 0.

Response

200 OK — {"data": [Delivery, ...]}

Errors

400 invalid_query 401 unauthorized 403 ip_not_allowed 429 rate_limited

Example request

curl "https://getgas.io/api/v1/deliveries?limit=10" \
  -H "Authorization: Bearer $GETGAS_API_KEY"

Example response · 200 OK

{
  "data": [
    {
      "id": 123,
      "automationId": 7,
      "kind": "refill",
      "address": "TXYZ...your-address...",
      "volume": 65000,
      "chargedSun": 1275000,
      "chargedTrx": "1.275",
      "txId": "b6e0…41d7",
      "deliveredAt": "2026-10-05T12:00:00.000Z"
    }
  ]
}

Docs

GET Get this reference

GEThttps://getgas.io/api/v1/docs

This reference as Markdown, always matching the deployed API.

No API key needed. Every response carries an X-Docs-Version header and an ETag, so a request with If-None-Match returns 304 while nothing has changed. The "Changelog" section lists what changed and when.

AuthorizationNo auth

Response

200 OK — Markdown (text/markdown). 304 Not Modified when If-None-Match matches.

Example request

curl "https://getgas.io/api/v1/docs"

Example response · 200 OK

text/markdown

Objects

Order

Field	Type	Description
`id`	integer	Order id.
`status`	string	See "Order statuses".
`resource`	string	"energy". Orders placed on the website may also be "bandwidth".
`address`	string	Address the resource is delegated to.
`volume`	integer	Amount of the resource.
`term`	string	"15m" or "1h". Orders placed before 2026-10-05 can also show "1d".
`priceSun`	integer	What the order cost, in sun (1 TRX = 1,000,000 sun), order fee included.
`priceTrx`	string	The same price as an exact decimal TRX string, e.g. "2.73".
`txId`	string \| null	TRON transaction that delegated the resource, once known.
`createdAt`	string	ISO 8601 timestamp.
`updatedAt`	string	ISO 8601 timestamp of the last status change.

Account

Field	Type	Description
`email`	string	The account the key belongs to.
`balanceSun`	integer	Balance in sun. Orders are paid from it.
`balanceTrx`	string	The same balance as an exact decimal TRX string.
`depositAddress`	string \| null	Your permanent TRC-20 address for topping up the balance. Null only if it could not be issued right now; try again later.
`depositNetwork`	string	"TRC20". Send only on the TRON network.
`depositCurrencies`	string[]	What the deposit address accepts: TRX and USDT (TRC-20). USDT is converted to TRX at the rate when it is credited.
`rates`	object	What this account pays now: `energySunPerUnit` by term, `bandwidthSunPerUnit`, `smartDeliverySun`, `activationSun`, and `orderFeeSun` — the fixed fee added to every one-time order. Accounts with their own rates see them here.

Deposit

Field	Type	Description
`id`	integer	Deposit id.
`transactionId`	string	TRON transaction hash of the payment.
`currency`	string	"TRX" or "USDT-TRC20".
`amount`	string	Amount sent, as a decimal string.
`netAmount`	string	Amount after the payment network fee, as a decimal string.
`creditedSun`	integer	What was added to the balance, in sun. 0 until credited.
`status`	string	"confirmed" once credited; other values mean it is still pending, or "ignored" when it needs a manual check (wrong network or currency).
`receivedAt`	string	ISO 8601 timestamp.
`creditedAt`	string \| null	When the balance was credited.

Automation

Field	Type	Description
`id`	integer	Automation id.
`kind`	string	"refill", "renewal" or "smart".
`status`	string	"active", "paused" or "removed".
`pauseReason`	string \| null	"system" when paused because the balance could not cover the next delivery, "user" when paused on request.
`autoResume`	boolean	Whether a "system" pause ends by itself once the balance covers the next delivery again.
`address`	string	Address kept supplied.
`volume`	integer	Energy per delivery.
`minimal`	integer \| null	refill: the threshold that triggers a delivery.
`term`	string \| null	refill: how long each delivery lasts.
`nextDeliverySun`	integer	What the next delivery is expected to cost: the balance the rule needs to keep running.
`deliveries`	integer	Deliveries made so far.
`lastDeliveryAt`	string \| null	ISO 8601 timestamp of the last delivery.
`createdAt`	string	ISO 8601 timestamp.

Delivery

Field	Type	Description
`id`	integer	Delivery id.
`automationId`	integer \| null	The automation that made it.
`kind`	string \| null	"refill", "renewal" or "smart".
`address`	string \| null	Address it was delivered to.
`volume`	integer	Energy delivered.
`chargedSun`	integer	What it cost the balance, in sun.
`chargedTrx`	string	The same as an exact decimal TRX string.
`txId`	string \| null	TRON transaction of the delegation.
`deliveredAt`	string	ISO 8601 timestamp.

Activation

Field	Type	Description
`id`	integer	Activation id.
`address`	string	The activated address.
`status`	string	"done", "refunded" (the network refused; nothing charged), or "unknown" (not confirmed; charged while support checks it).
`priceSun`	integer	What it cost, in sun.
`priceTrx`	string	The same as an exact decimal TRX string.
`createdAt`	string	ISO 8601 timestamp.

AddressCheck

Field	Type	Description
`address`	string	The address checked.
`isActivated`	boolean	Whether it exists on-chain. Resources cannot be delegated to an address that does not.
`activationSun`	integer	What activating it costs now, in sun.

Order statuses

Status	Final	Meaning
`pending`	—	Being placed with the network. Lasts seconds.
`submitted`	—	Accepted and being delegated. The price has been charged.
`filled`	yes	Delivered: the Energy is on the address. txId is the delegation.
`refunded`	yes	Could not be delivered; the full price is back on the balance.
`failed`	yes	Not delivered. If the balance was charged, support returns it.
`unknown`	—	Delivery was not confirmed. It stays charged while support checks it, then becomes filled or refunded.

Prices and final price

Prices follow the Energy provider's own price and are refreshed every few minutes. GET /prices shows the general prices; GET /account shows what your account pays (some accounts have their own rates).
An order costs volume × rate plus a fixed order fee (orderFeeSun, 0.3 TRX unless changed; read it from GET /prices), once per order. Automation deliveries and address activations have no order fee.
An order is charged at the current price when it is placed. Once it is delivered, it is settled at the provider's final price for that delivery: if that is lower, the difference goes back to the balance; if it is higher, the difference is charged. The order's priceSun then shows the final price. Accounts with their own rates are charged exactly their rate, with no settlement.
Bandwidth prices are an estimate until the order is settled.

How automations run

The provider runs the automation; each delivery is charged to the balance as it happens, at the provider's price for that delivery (or your own rate), with no order fee. Every delivery is listed in GET /deliveries and charged exactly once.

refill — adds volume Energy (for term) whenever the address holds less than minimal. Best for hot wallets. If the address keeps less than minimal, it refills again each time a delivery expires.
renewal — keeps volume Energy on the address, renewed every day.
smart — delivers 131,000 Energy and refills it after every transfer. For addresses that send one transfer at a time, no more than one every 6 seconds.

To start, the balance must cover one delivery (nextDeliverySun). Whenever it no longer does, the automation is paused (pauseReason: "system") and — unless autoResume is false — resumes by itself after a deposit brings the balance back. A delivery already made is always charged, even if that takes the balance below zero; the next deposit repays it.

Idempotency and retries

Send a new Idempotency-Key for every purchase and the same key when retrying it. If a request times out, you cannot know whether the order was placed; retrying with the same key returns the order if it was, and places it if it was not. It never charges twice.
Reusing a key with a different address, volume or term returns 409 idempotency_conflict.
402, 422 and 503 errors from POST /orders charge nothing. After 422 or 503 the same key can be retried; a key that got 402 keeps returning 402, so top up and send the purchase with a new key.
After 429, wait for the number of seconds in the Retry-After header.

Webhooks

Set a webhook URL in the dashboard (https://getgas.io/dashboard/api, the Webhook card) to be told when an order settles instead of polling GET /orders/{id}. The URL must be HTTPS and reachable from the internet.

When: an order that was accepted becomes filled, refunded or failed. Event types: order.filled, order.refunded, order.failed, and ping for the test button in the dashboard. Orders refused while being placed are not sent: the API already answered them with an error.
Request: POST with a JSON body {"id": "evt_...", "type", "createdAt", "data": Order} (for ping, data is {"message"}). Headers: X-GetGas-Event (the type) and X-GetGas-Signature: t=<unix seconds>,v1=<hex>.
Signature: v1 is HMAC-SHA256 of <t>.<raw body> with your webhook secret (whsec_..., shown in the dashboard). Compare it in constant time and reject requests whose t is more than 5 minutes old.
Answer with any 2xx within 5 seconds. Otherwise the delivery is tried twice more, after 5 seconds and after a minute. Redirects are not followed. Use the event id to ignore a repeat.
priceSun in order.filled can still change once when the order is settled at the final price (see "Prices and final price"); GET /orders/{id} always has the current value.

Verify a webhook

import {createHmac, timingSafeEqual} from 'node:crypto';

function verify(rawBody, header, secret) {
  const {t, v1} = Object.fromEntries(header.split(',').map(part => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Errors

Errors use HTTP status codes and a stable code to branch on.

Status	Code	Meaning
400	`invalid_json`	The request body is not valid JSON.
400	`invalid_query`	A query parameter has an invalid value.
400	`invalid_idempotency_key`	POST /orders needs an Idempotency-Key header: 8–64 letters, digits, "-" or "_".
401	`unauthorized`	Missing, invalid or revoked API key, or the account is disabled.
403	`ip_not_allowed`	The account has an IP allowlist and the request came from an address not on it. Add the address in the dashboard (API & Keys → IP allowlist).
402	`insufficient_funds`	The balance does not cover it (for an automation: one delivery). error.details has priceSun and balanceSun. Nothing was charged.
404	`not_found`	No such order or automation on this account.
409	`idempotency_conflict`	This Idempotency-Key was already used for an order with different parameters.
409	`automation_exists`	The address already has a live automation of this kind.
415	`unsupported_media_type`	Send "Content-Type: application/json".
422	`validation_failed`	See error.details: one message per invalid field. Unknown fields are rejected.
422	`volume_out_of_range`	The network accepts a narrower range right now. error.details has min and max. Nothing was charged.
429	`rate_limited`	More than 120 requests per minute for this key, or more than 30 new orders per minute for this account. Wait for the Retry-After header (seconds).
503	`provider_unavailable`	Temporarily unavailable. Nothing was charged; retry later (for an order, with the same Idempotency-Key).

Error response

{
  "error": {
    "code": "insufficient_funds",
    "message": "The balance does not cover this order.",
    "details": {"priceSun": 2730000, "balanceSun": 1000000}
  }
}

JavaScript example

A complete script: check the balance, place an order with an idempotency key, and wait until it is delivered. The code is on the right.

buy.mjs

const API = 'https://getgas.io/api/v1';
const headers = {Authorization: `Bearer ${process.env.GETGAS_API_KEY}`};

async function buyEnergy(address, volume, term = '1h') {
  // One key per purchase: a retry after a timeout returns the same order instead of buying twice.
  const idempotencyKey = crypto.randomUUID();
  let order;
  for (let attempt = 0; attempt < 3 && !order; attempt++) {
    const res = await fetch(`${API}/orders`, {
      method: 'POST',
      headers: {...headers, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey},
      body: JSON.stringify({address, volume, term}),
    }).catch(() => null);
    if (!res) continue; // network error: retry with the same key
    const body = await res.json();
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    order = body.data;
  }
  if (!order) throw new Error('Could not reach the API');

  // Wait until the order is final.
  while (['pending', 'submitted', 'unknown'].includes(order.status)) {
    await new Promise(resolve => setTimeout(resolve, 3000));
    order = (await (await fetch(`${API}/orders/${order.id}`, {headers})).json()).data;
  }
  return order; // "filled", "refunded" or "failed"
}

Changelog

2026-10-05

Energy is no longer sold by the day: POST /orders refuses term "1d" with validation_failed, and refill automations take term "1h" only. GET /prices and GET /account no longer list a "1d" rate. Orders and automations made earlier keep their term.
Wording only, no change in behaviour: prices, settlement, activations and automation deliveries are described as following the Energy provider's price (not "the network's"); the order fee is 0.3 TRX unless changed, so read orderFeeSun from GET /prices; the 131,000 Energy figure is for a recipient that holds no USDT; the web version of this reference is at https://getgas.io/developers/docs.

2026-10-03

API keys, usage, the webhook and the IP allowlist moved to their own dashboard page: API & Keys (/dashboard/api). Nothing changed in the API itself.

2026-10-01

Webhooks: set an HTTPS URL in the dashboard (API & Keys → Webhook) and receive a signed POST when an order becomes filled, refunded or failed. See "Webhooks".
IP allowlist: an account can limit its API keys to a list of IP addresses. Requests from any other address get 403 ip_not_allowed.

2026-09-30

The minimum Bandwidth order is now 1,000, the network's own minimum; smaller orders were refused.
Every one-time order now carries a fixed order fee (0.3 TRX), included in the order's priceSun. GET /prices and GET /account show it as orderFeeSun. Automation deliveries and activations have no fee.

2026-09-29

Orders can now be rented for one day: term "1d".
First version: account balance, deposit address and own rates; deposits; live prices; buying Energy or Bandwidth from the balance with order status and history; address activation; automations (auto-refill, auto-renewal, smart mode) and their deliveries.