TRX For Gas API · Web2 / Web3

Quick Start

Recommended Workflow

# Configure noticeUrl and IP whitelist in API User settings first
GET  /v1/swap/info  # TRX/USDT reference rate, quote time, limits, fees, and swap address
GET  /v1/myInfo
POST /v1/quote/precount
POST /v1/energy-rental/orders
GET  /v1/orders/{id}
# or
GET  /v1/orders/getByOrderNo?orderNo=EXT-20260516001
GET  /v1/tasks/{taskId}  # query address activation progress

# Auto Energy
GET   /v1/auto-energy/subscription-quote
POST  /v1/auto-energy/subscriptions
GET   /v1/auto-energy/subscriptions
GET   /v1/auto-energy/subscriptions/{id}
POST  /v1/auto-energy/subscriptions/{id}/close

API User requests require x-api-key, and the caller server IP must match the API User IP whitelist. Money fields use SUN. 1 TRX = 1,000,000 SUN. After noticeUrl is configured, deposit credits, order success, and order failure are pushed asynchronously to that callback URL. Keep order query endpoints as compensation checks.

Auth and Limits

Except for the GET /v1 version check, every V1 endpoint requires the x-api-key request header and the caller IP must be in the API User IP whitelist. Do not put the API Key in the query string or request body.

Callback Notifications

Configure noticeUrl from API User settings in the WebApp or Telegram Bot. The URL must start with http:// or https:// and resolve to public addresses. If it is empty, no HTTP callback notification is created. Use the final receiving URL that returns 2xx; HTTP redirects are not followed.

Order callbacks use one public payload format and include callbackStatus, hash, hashes, and activation. activation has a value only when the order was created after automatic address activation and this callback is for the final energy order; otherwise it is null. Use type to distinguish callback types. Deposit and order callbacks use their record/order identity; Auto Energy uses eventType + chargeId, or eventType + subscriptionId when no charge exists.

Deposit Callback Example

{
  "type": "deposit",
  "id": 456,
  "userId": 1,
  "address": "T9z6yrJXuiJpfWhis3Ae9nHK7k65yM5AHP",
  "fromAddress": "TQ8r...",
  "amount": 10000000,
  "txHash": "9c4f...",
  "createdAt": "2026-05-16T12:00:00"
}

Deposit Callback Fields

Order Callback Example

{
  "type": "order",
  "id": 123,
  "orderNo": "EXT-20260516001",
  "orderTime": 3600,
  "orderType": 0,
  "paidAmount": 1500000,
  "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
  "resourceAmount": 65000,
  "resourceType": 1,
  "status": 1,
  "callbackStatus": "SUCCESS",
  "failReason": null,
  "activation": null,
  "hash": "ab12...",
  "hashes": [
    "ab12..."
  ],
  "timeStamp": 1778918400000,
  "times": 1,
  "totalFee": 1500000,
  "updatedAt": "2026-05-16 12:00:00",
  "subscription": null
}

Auto Energy Callback Example

{
  "type": "autoEnergy",
  "eventType": "AUTO_ENERGY_REPLENISHED",
  "subscriptionId": 18,
  "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
  "status": "ACTIVE",
  "targetEnergy": 131000,
  "smallTierMinimumAvailableEnergy": 64805,
  "chargedTierEnergy": 65000,
  "feeSun": 14000000,
  "chargeId": 72,
  "chargeType": "USAGE_TOPUP",
  "chargeStatus": "SETTLED",
  "coverageEndsAt": "2026-08-28T12:00:00",
  "failReason": null,
  "hashes": ["ab12..."],
  "timeStamp": 1787918400000
}

eventType is one of AUTO_ENERGY_STARTED, AUTO_ENERGY_REPLENISHED, AUTO_ENERGY_OVERNIGHT_CHARGED, AUTO_ENERGY_OVERNIGHT_REFUNDED, AUTO_ENERGY_CLOSING, AUTO_ENERGY_FAILED, or AUTO_ENERGY_CLOSED. AUTO_ENERGY_OVERNIGHT_REFUNDED means earlier Energy usage was detected after overnight settlement and that overnight fee was returned. Deduplicate charge events by eventType + chargeId; when chargeId is null, use eventType + subscriptionId. targetEnergy is the managed target, and actual available Energy may vary within ±0.3%.

Endpoints

API_BASE_URL="<copy from API User in the WebApp or Telegram Bot>"
curl "$API_BASE_URL/v1"

{
  "version": "x.y.z"
}

curl --request GET \
  --url "$API_BASE_URL/v1/swap/info" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "quote": {
    "available": true,
    "quoteTime": "2026-06-13T12:00:00Z",
    "quoteAt": "2026-06-13T12:00:00Z",
    "nextRefreshAt": "2026-06-13T12:01:00Z",
    "refreshIntervalSeconds": 60,
    "oneUsdtToTrx": "3.2",
    "usdtToTrxInput": "5",
    "usdtToTrxReferenceOutput": "16",
    "hundredTrxToUsdt": "31.25",
    "trxToUsdt": {
      "enabled": true,
      "direction": "TRX_TO_USDT",
      "inputToken": "TRX",
      "outputToken": "USDT",
      "minInput": "10",
      "maxInput": "5000",
      "feeBps": 30,
      "feePercent": "0.3",
      "feeDeductionMode": "BEFORE_SWAP",
      "feeToken": "TRX",
      "minFee": "1"
    },
    "usdtToTrx": {
      "enabled": true,
      "direction": "USDT_TO_TRX",
      "inputToken": "USDT",
      "outputToken": "TRX",
      "minInput": "5",
      "maxInput": "3000",
      "feeBps": 30,
      "feePercent": "0.3",
      "feeDeductionMode": "BEFORE_SWAP",
      "feeToken": "USDT",
      "minFee": "0.5"
    },
    "address": "TSwapAddress",
    "addresses": [
      "TSwapAddress"
    ]
  },
  "reason": null,
  "message": null
}

curl --request GET \
  --url "$API_BASE_URL/v1/myInfo" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "account": {
    "id": 1,
    "name": "Demo API User",
    "avaliableBalance": 10000000,
    "addressForDeposit": "T9z6yrJXuiJpfWhis3Ae9nHK7k65yM5AHP",
    "apiKeyMasked": "abcd...wxyz",
    "noticeUrl": "",
    "createdAt": "2026-05-16T12:00:00",
    "updatedAt": "2026-05-16T12:00:00"
  },
  "reason": null,
  "message": null
}

curl --request POST \
  --url "$API_BASE_URL/v1/quote/precount" \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "times": 1,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "energyType": "activated",
    "durationHours": 1,
    "autoActivate": true
  }'

{
  "result": "SUCCESS",
  "quote": {
    "valid": true,
    "reason": null,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "addressValid": true,
    "addressActivated": true,
    "energyType": "activated",
    "times": 1,
    "durationSeconds": 3600,
    "durationHours": 1,
    "energyAmount": 65000,
    "finalFeeSun": 1500000,
    "finalFeeTrx": "1.5",
    "autoActivate": true,
    "needActivation": false,
    "activationFeeSun": 0,
    "activationFeeTrx": "0",
    "estimatedTotalFeeSun": 1500000,
    "estimatedTotalFeeTrx": "1.5"
  },
  "reason": null,
  "message": null
}

curl --request POST \
  --url "$API_BASE_URL/v1/energy-rental/orders" \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "times": 1,
    "orderNo": "EXT-20260516001",
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "energyType": "activated",
    "durationHours": 1,
    "autoActivate": true
  }'

{
  "result": "ACCEPTED",
  "order": {
    "id": 123,
    "orderNo": "EXT-20260516001",
    "orderTime": 3600,
    "orderType": 0,
    "paidAmount": 1500000,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "resourceAmount": 65000,
    "resourceType": 1,
    "status": 0,
    "failReason": null,
    "timeStamp": 1778918400000,
    "times": 1,
    "totalFee": 1500000,
    "updatedAt": "2026-05-16 12:00:00",
    "activation": null,
    "subscription": null
  },
  "reason": null,
  "message": null
}

curl --request GET \
  --url "$API_BASE_URL/v1/orders/123" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "order": {
    "id": 123,
    "orderNo": "EXT-20260516001",
    "orderTime": 3600,
    "orderType": 0,
    "paidAmount": 1500000,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "resourceAmount": 65000,
    "resourceType": 1,
    "status": 1,
    "failReason": null,
    "timeStamp": 1778918400000,
    "times": 1,
    "totalFee": 1500000,
    "updatedAt": "2026-05-16 12:00:00",
    "activation": null,
    "subscription": null
  },
  "reason": null,
  "message": null
}

curl --request GET \
  --url "$API_BASE_URL/v1/orders/getByOrderNo?orderNo=EXT-20260516001" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "order": {
    "id": 123,
    "orderNo": "EXT-20260516001",
    "orderTime": 3600,
    "orderType": 0,
    "paidAmount": 1500000,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "resourceAmount": 65000,
    "resourceType": 1,
    "status": 1,
    "failReason": null,
    "timeStamp": 1778918400000,
    "times": 1,
    "totalFee": 1500000,
    "updatedAt": "2026-05-16 12:00:00",
    "activation": null,
    "subscription": null
  },
  "reason": null,
  "message": null
}

curl --request GET \
  --url "$API_BASE_URL/v1/tasks/1001" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "activation": {
    "taskId": 1001,
    "status": "PROCESSING",
    "failReason": null,
    "currentStep": "EXECUTE_ACTIVATION",
    "activationStatus": "PROCESSING",
    "feeSun": 1200000,
    "feeTrx": "1.2",
    "paidAmountSun": 0,
    "paidAmountTrx": "0",
    "txHash": null,
    "energyOrderId": null,
    "autoEnergySubscriptionId": null
  },
  "reason": null,
  "message": null
}

curl --request GET \
  --url "$API_BASE_URL/v1/auto-energy/subscription-quote" \
  --header 'x-api-key: <YOUR_API_KEY>'

{
  "result": "SUCCESS",
  "quote": {
    "targetEnergy": 131000,
    "smallTierMinimumAvailableEnergy": 64805,
    "initialFeeSun": 28000000,
    "smallRefillFeeSun": 14000000,
    "fullRefillFeeSun": 28000000,
    "overnightFeeSun": 2000000
  },
  "reason": null,
  "message": null
}

curl --request POST \
  --url "$API_BASE_URL/v1/auto-energy/subscriptions" \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "maxInitialFeeSun": 30000000,
    "maxOvernightFeeSun": 5000000,
    "autoActivate": true,
    "maxActivationFeeSun": 2000000
  }'

{
  "result": "SUCCESS",
  "subscription": {
    "id": 18,
    "receiverAddress": "TJqiMSSmRtm4LvXrYBWysz9DnNrFQDaBv9",
    "status": "PENDING_ORDER",
    "displayStatus": "PENDING_ORDER",
    "targetEnergy": 131000,
    "maxOvernightFeeSun": 5000000,
    "currentDelegateHash": null,
    "delegateHashes": [],
    "lastChargeType": "INITIAL",
    "lastChargeFeeSun": 28000000,
    "currentOvernightFeeSun": 2000000,
    "nextOvernightAt": null,
    "activation": null
  },
  "reason": null,
  "message": null
}

Web3 API · Direct on-chain payment

No account, login, API key, balance deposit or backend proxy is required. Get payment instructions, transfer from your wallet, then query the existing business result. These endpoints reuse the existing direct-transfer products.

Base URL: https://api.trxforgas.com · /web3/v1

Use this deployment’s asset IDs and contract addresses from options. Do not mix networks or send test assets to a production address. The public URL is available after this API version is deployed.

Existing business rules

• Energy: only the existing 1-hour direct-transfer packages. Quote does not create an order or lock a price. The existing incoming-payment rules determine the purchased package. A different beneficiary must be sent as payment.memo in the TRX transfer.
• Swap: TRX ↔ USDT on TRON. The quote is an estimate, not a guaranteed output. Output always returns to the actual payment wallet; a different receiver is rejected. No approval is required for the user’s ordinary transfer.
• Bridge: quote internally obtains a quote and confirms the existing order. Pay the exact returned amount and any required memo before expiresAt. Existing route availability, payer active-order limits, re-quoting and exception handling still apply. Unsupported memo/tag destination formats are not added by this API.
• Fees, delivery, refunds and manual support follow the current products. This API does not add guaranteed prices or automatic refunds. Wallet network fees are paid separately. Energy does not include Bandwidth.

GET /web3/v1/options

Returns assets, enabled services, energy packages, Swap pairs and available bridge routes. IDs are deployment-scoped chain:asset strings. Amounts use smallest-unit integer strings.

energy.packages[].packageId: activated-1h, noActivated-1h; durationSeconds = 3600.

POST /web3/v1/quote

Content-Type: application/json. Only supply fields belonging to the selected type. Other fields, including durationHours/durationSeconds, are rejected.

{"type":"energy","payerAddress":"YOUR_TRON_ADDRESS","packageId":"activated-1h"}
{"type":"swap","payerAddress":"YOUR_TRON_ADDRESS","fromAsset":"tron:trx","toAsset":"tron:usdt","amount":"100000000"}
{"type":"bridge","payerAddress":"SOURCE_WALLET","fromAsset":"FROM_OPTIONS","toAsset":"FROM_OPTIONS","amount":"RAW_INTEGER","receiverAddress":"DESTINATION_WALLET"}

Response: payment (chain, asset, address, amount, optional memo), receive, included fee, priceLocked=false and rules. Energy/Swap return queryBy=paymentTxHash and no order id. Bridge returns queryBy=id, an opaque id and expiresAt (ISO 8601 with timezone); save the complete id.

Energy receive contains energyAmount and durationSeconds; Swap/bridge receive contains asset and estimatedAmount. Swap fee is already deducted in estimatedAmount. An unsuccessful quote does not return a payable address.

GET /web3/v1/status

/web3/v1/status?type=energy&paymentChain=tron&paymentTxHash=HASH
/web3/v1/status?type=swap&paymentChain=tron&paymentTxHash=HASH
/web3/v1/status?type=bridge&id=COMPLETE_ID_FROM_QUOTE

Querying a hash only reads an existing record; it does not submit or confirm payment. The scanner runs independently of the browser. Existing energy direct payments can also be queried; account-funded orders stay private. Multiple Swap events in one transaction return payments[], and each item has its own status.

Response includes message, nextPollSeconds, paymentTxHash, chain-qualified resultTxHashes, receive and available refund/refunds records. Follow nextPollSeconds; 0 means stop polling. Save the wallet payment hash before closing the page.

Rate limits and browser access

No cookies or domain whitelist. Use fetch with credentials: omit. CORS supports GET/POST/OPTIONS. Per brand and real IP: 20 POST quote requests per 60 seconds; 120 other requests per 60 seconds (including preflight). Existing bridge payer limits also apply. HTTP 429 returns Retry-After: 60. Requests record IP, endpoint, HTTP status and elapsed time in the existing API statistics.

Errors use code/message: INVALID_REQUEST, UNSUPPORTED_FIELD, INVALID_PACKAGE, INVALID_AMOUNT, UNSUPPORTED_ASSET, RECEIVER_MUST_BE_PAYER, INVALID_QUERY (400); NOT_FOUND (404); SOURCE_ADDRESS_IN_USE / QUOTE_NEEDS_REFRESH (409); RATE_LIMITED (429); UNAVAILABLE (503). Do not retry payments to recover API errors. Existing access blocks may return HTTP 403 with error=request_blocked.

JavaScript

const base = 'https://api.trxforgas.com';
async function web3(path, body) {
  const response = await fetch(base + '/web3/v1/' + path, {
    method: body ? 'POST' : 'GET', credentials: 'omit',
    headers: body ? { 'Content-Type': 'application/json' } : {},
    body: body ? JSON.stringify(body) : undefined
  });
  const data = await response.json();
  if (!response.ok) throw new Error(data.code + ': ' + data.message);
  return data;
}
const options = await web3('options');
const energy = await web3('quote', { type: 'energy', payerAddress,
  packageId: 'activated-1h' });
// Display energy.payment, then let the wallet send the transfer.
const result = await web3('status?' + new URLSearchParams({
  type: 'energy', paymentChain: 'tron', paymentTxHash
}));

Download energy, Swap and bridge examples. Wallet signing is supplied by the integrating wallet; examples never send a payment automatically.

Error Codes

LLM Contract Summary

The JSON below is a compact contract summary for LLM / automation integrations. Use OpenAPI JSON for the full machine-readable specification.

{
  "apiVersion": "v1",
  "apiRuntimeVersionUrl": "https://api.trxforgas.com/v1",
  "baseUrl": "Read from API User in the WebApp or Telegram Bot. Do not prepend the legacy /api prefix.",
  "auth": "x-api-key header plus API User IP whitelist",
  "limits": "Read endpoints default to 30 requests per 10 seconds; write endpoints default to 10 requests per 10 seconds, counted by API Key + endpoint path. General penalties return API_USER_BLOCKED above the configured 7-day error threshold and clear on the next API request once the count is at or below it. Three cross-account access violations within 10 minutes trigger a security block requiring administrator unblocking. Service-side or platform-side errors do not count toward blocking.",
  "callback": "Configure noticeUrl for deposit and ordinary-order status callbacks. Managed Auto Energy orders are excluded; Auto Energy uses dedicated events.",
  "pricing": "Use GET /v1/auto-energy/subscription-quote for initial, refill-tier, and independent overnight fees; use maxInitialFeeSun and maxOvernightFeeSun as create-time caps.",
  "autoEnergy": "Manages toward a 131000-Energy target with ±0.3% on-chain conversion tolerance; 64805-130999 is billed at the 65000 tier, below 64805 at the 131000 tier, then recalculated toward the target; each idle 24h only incurs the independent overnight fee.",
  "paths": [
    {
      "method": "GET",
      "path": "/v1",
      "auth": false,
      "purpose": "deployed version"
    },
    {
      "method": "GET",
      "path": "/v1/myInfo",
      "auth": true,
      "purpose": "API User account and deposit address"
    },
    {
      "method": "GET",
      "path": "/v1/swap/info",
      "auth": true,
      "purpose": "TRX/USDT reference rate, quote time, limits, fees, and swap address"
    },
    {
      "method": "POST",
      "path": "/v1/quote/precount",
      "auth": true,
      "purpose": "current quote and receiver activation check"
    },
    {
      "method": "POST",
      "path": "/v1/energy-rental/orders",
      "auth": true,
      "purpose": "create energy rental order"
    },
    {
      "method": "GET",
      "path": "/v1/orders/{id}",
      "auth": true,
      "purpose": "query by platform order id"
    },
    {
      "method": "GET",
      "path": "/v1/orders/getByOrderNo",
      "auth": true,
      "purpose": "query by external orderNo"
    },
    {
      "method": "GET",
      "path": "/v1/tasks/{taskId}",
      "auth": true,
      "purpose": "look up auto-activation task status"
    },
    {
      "method": "GET",
      "path": "/v1/auto-energy/subscription-quote",
      "auth": true,
      "purpose": "quote Auto Energy subscription fee"
    },
    {
      "method": "POST",
      "path": "/v1/auto-energy/subscriptions",
      "auth": true,
      "purpose": "create Auto Energy subscription"
    },
    {
      "method": "GET",
      "path": "/v1/auto-energy/subscriptions",
      "auth": true,
      "purpose": "list Auto Energy subscriptions"
    },
    {
      "method": "GET/POST",
      "path": "/v1/auto-energy/subscriptions/{id}",
      "auth": true,
      "purpose": "query or stop subscription"
    }
  ],
  "moneyUnit": "SUN. 1 TRX = 1,000,000 SUN.",
  "status": {
    "0": "pending",
    "1": "delegated",
    "2": "completed",
    "3": "delegating",
    "-1": "failed",
    "-2": "refunded"
  }
}