TRX For Gas API · Web2 / Web3

快速开始

推荐流程

# 在 WebApp 或 Telegram Bot 的 API User 中配置 noticeUrl 和 IP 白名单
GET  /v1/swap/info  # TRX/USDT 参考汇率、报价时间、限额、手续费和兑换地址
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}  # 查询地址激活进度

# 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 请求需要 x-api-key，并且调用服务器 IP 必须命中该 API User 的 IP 白名单。金额字段统一使用 SUN，1 TRX = 1,000,000 SUN。配置 noticeUrl 后，充值到账、订单成功和订单失败会异步推送到该回调地址；接入方仍应保留主动查询订单接口作为补偿查询。

认证与限制

除 GET /v1 版本检查外，所有 V1 接口都需要在请求头传入 x-api-key，并且调用源 IP 必须在该 API User 的 IP 白名单内。API Key 不要放在 query string 或请求体中。

回调通知

API User 可以在 WebApp 或 Telegram Bot 的 API User 设置中配置 noticeUrl。系统只接受以 http:// 或 https:// 开头、能解析到公网地址的回调 URL；为空时不会创建 HTTP 回调通知。请填写直接返回 2xx 的最终接收地址，系统不跟随 HTTP 重定向。

订单回调使用统一对外格式，并额外包含 callbackStatus、hash、hashes 和 activation。只有订单由自动激活流程创建，且该回调对应最终能量订单时，activation 才会有值；其他场景为 null。建议接入方按 type 分流处理。充值和订单回调使用对应记录/订单标识幂等；自动充能按 eventType + chargeId 幂等，无收费记录时按 eventType + subscriptionId 幂等。

充值回调示例

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

充值回调字段

订单回调示例

{
  "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
}

自动充能回调示例

{
  "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 可为 AUTO_ENERGY_STARTED、AUTO_ENERGY_REPLENISHED、AUTO_ENERGY_OVERNIGHT_CHARGED、AUTO_ENERGY_OVERNIGHT_REFUNDED、AUTO_ENERGY_CLOSING、AUTO_ENERGY_FAILED 或 AUTO_ENERGY_CLOSED。AUTO_ENERGY_OVERNIGHT_REFUNDED 表示系统在过夜费结算后发现此前仍有用能记录，已退回该笔过夜费。收费事件按 eventType + chargeId 幂等；chargeId 为空时按 eventType + subscriptionId 幂等。targetEnergy 是托管目标值，实际可用能量允许 ±0.3% 偏差。

接口列表

API_BASE_URL="<在 WebApp 或 Telegram Bot 的 API User 中复制>"
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 · 链上直存

无需注册、登录、API Key、预存余额或自建中转。获取付款指令 → 钱包链上转账 → 查询业务结果。接口复用现有链上直存业务。

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

使用本部署 options 返回的资产 ID 和合约地址，不要混用网络或向生产地址发送测试资产。以上公开地址随本接口版本部署后提供服务。

沿用原有业务规则

• 能量：仅提供现有链上直存的 1 小时套餐；询价不建单、不锁价，最终按原有到账规则识别套餐。替其他地址租赁时，必须将 payment.memo 作为 TRX 转账备注发送。
• Swap：TRON 上 TRX ↔ USDT。报价为预估，不承诺锁定输出；出款固定返回实际付款钱包，不支持另指定收款人。用户普通转账不需要 approve。
• 跨链：quote 内部完成原有报价与确认下单；按返回的准确金额和必要备注，在 expiresAt 前付款。沿用现有路由开关、付款地址活跃单限制、到账重新询价和异常处理，不增加新的目标链 memo/tag 支持。
• 收费、交付、退款及人工处理沿用现有产品规则，不新增锁价或自动退款承诺。钱包网络费另付，能量不包含带宽。

GET /web3/v1/options

返回 assets、energy、swap、bridge。包括资产精度与合约、服务开关、能量套餐、Swap 方向和可用跨链路由。资产 ID 为本部署范围内的 chain:asset；金额统一使用最小单位整数字符串。

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

POST /web3/v1/quote

Content-Type: application/json. 仅传所选业务的字段；额外字段会被拒绝，包括 durationHours、durationSeconds 等租期参数。

{"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"}

响应含 payment（chain、asset、address、amount、可选 memo）、receive、已包含的 fee、priceLocked=false 和 rules。能量/Swap 返回 queryBy=paymentTxHash，不返回订单 id；跨链返回 queryBy=id、完整查询 id 和带时区 ISO 8601 的 expiresAt，请保存完整 id。

能量 receive 含 energyAmount、durationSeconds；Swap/跨链含 asset、estimatedAmount。Swap 预估到账金额已扣除响应中的服务费。询价失败不返回付款地址。

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

哈希仅作为查询条件，不用于提交或确认付款。后台扫链独立于浏览器运行；历史能量直存也可查询，账户余额订单不会公开。同一 Swap 交易有多个入账事件时返回 payments[]，逐项读取状态。

响应提供 message、nextPollSeconds、paymentTxHash、带链标识的 resultTxHashes、receive 及已有的 refund/refunds 记录。按 nextPollSeconds 轮询，0 表示停止；关闭页面前保存钱包付款哈希。

限速与浏览器访问

无需 Cookie 或域名白名单，fetch 使用 credentials: omit。CORS 支持 GET/POST/OPTIONS。按品牌和真实 IP 限速：POST quote 每 60 秒 20 次，其余请求（含预检）每 60 秒共 120 次；跨链另沿用原有付款地址限流。HTTP 429 返回 Retry-After: 60。请求 IP、接口、HTTP 状态和耗时纳入现有 API 请求统计。

错误统一为 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）。既有访问封禁可返回 HTTP 403 与 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
}));

下载能量、Swap、跨链三个完整最小接入示例. 钱包签名由接入方钱包完成；示例不会自动发起付款。

错误码

LLM 契约摘要

下面的 JSON 是为 LLM / 自动化集成准备的精简契约摘要；完整机器可读规范请使用 OpenAPI JSON。

{
  "apiVersion": "v1",
  "apiRuntimeVersionUrl": "https://api.trxforgas.com/v1",
  "baseUrl": "从 WebApp 或 Telegram Bot 的 API User 中读取。不要拼接旧版 /api 前缀。",
  "auth": "x-api-key 请求头 + API User IP 白名单",
  "limits": "读接口默认 10 秒 30 次，写接口默认 10 秒 10 次，按 API Key + 接口路径统计。一般处罚：近 7 日可修正错误超过系统阈值时返回 API_USER_BLOCKED；错误数回落至阈值以内后，下次 API 请求自动恢复，也可由管理员解封。安全封禁：10 分钟内跨账户访问达到 3 次，必须由管理员解封。服务端或平台侧错误不计入封禁。",
  "callback": "配置 noticeUrl 后接收充值和普通订单状态回调；自动充能托管订单不进入普通订单回调，自动充能通过独立事件通知。",
  "pricing": "使用 GET /v1/auto-energy/subscription-quote 获取首次、两档补能和独立隔夜费报价；创建时使用 maxInitialFeeSun 与 maxOvernightFeeSun 控制费用上限。",
  "autoEnergy": "以 131000 Energy 为托管目标并允许 ±0.3% 链上换算偏差；64805 至 130999 按 65000 档计费，低于 64805 按 131000 档计费并按目标重新计算委托；空闲每 24 小时只收独立隔夜费。",
  "paths": [
    {
      "method": "GET",
      "path": "/v1",
      "auth": false,
      "purpose": "部署版本"
    },
    {
      "method": "GET",
      "path": "/v1/myInfo",
      "auth": true,
      "purpose": "API User 账户和充值地址"
    },
    {
      "method": "GET",
      "path": "/v1/swap/info",
      "auth": true,
      "purpose": "TRX/USDT 兑换参考汇率、报价时间、限额、手续费和兑换地址"
    },
    {
      "method": "POST",
      "path": "/v1/quote/precount",
      "auth": true,
      "purpose": "当前报价和接收地址激活状态检查"
    },
    {
      "method": "POST",
      "path": "/v1/energy-rental/orders",
      "auth": true,
      "purpose": "创建能量租赁订单"
    },
    {
      "method": "GET",
      "path": "/v1/orders/{id}",
      "auth": true,
      "purpose": "按平台订单 ID 查询"
    },
    {
      "method": "GET",
      "path": "/v1/orders/getByOrderNo",
      "auth": true,
      "purpose": "按外部 orderNo 查询"
    },
    {
      "method": "GET",
      "path": "/v1/tasks/{taskId}",
      "auth": true,
      "purpose": "查询自动激活 task 状态"
    },
    {
      "method": "GET",
      "path": "/v1/auto-energy/subscription-quote",
      "auth": true,
      "purpose": "查询自动充能订阅费"
    },
    {
      "method": "POST",
      "path": "/v1/auto-energy/subscriptions",
      "auth": true,
      "purpose": "创建自动充能订阅"
    },
    {
      "method": "GET",
      "path": "/v1/auto-energy/subscriptions",
      "auth": true,
      "purpose": "查询自动充能订阅列表"
    },
    {
      "method": "GET/POST",
      "path": "/v1/auto-energy/subscriptions/{id}",
      "auth": true,
      "purpose": "查询或中止订阅"
    }
  ],
  "moneyUnit": "SUN。1 TRX = 1,000,000 SUN。",
  "status": {
    "0": "待处理",
    "1": "已委托",
    "2": "已完成",
    "3": "委托中",
    "-1": "失败",
    "-2": "已退款"
  }
}