对外接口文档

🔐 认证方式：API Key

所有对外接口仅支持 API Key 认证。推荐在 Header 中使用 X-API-Key: YOUR_API_KEY，若需兼容也可放在 apiKey 字段或查询参数。若同时传递 Header 与参数，将以 Header 为准。

⚡ 地址自动激活

对接方无需先给目标地址转账开户。下单时若 receiveAddress 尚未在波场激活，系统会先自动激活，再向其委托能量。

激活成功后该笔订单额外收取 1.1 TRX，已计入询价的 estimatedCost 与订单金额。响应里 activation_fee_paid 为 true 表示本单触发了激活。

询价接口可传 receiveAddress，返回 needActivation、activationFee，便于下单前展示费用。

GET/api/external/balance

返回关联账户的余额，单位 TRX，保留六位小数。

认证: 仅支持 API Key（推荐 Header）

curl -H "X-API-Key: YOUR_API_KEY" https://021.st/api/external/balance

{
  "balance": "105.230000"
}

GET/api/external/deposit-address

返回用户专属充值地址，若尚未生成会返回 404。

认证: 仅支持 API Key

curl -H "X-API-Key: YOUR_API_KEY" https://021.st/api/external/deposit-address

{
  "depositAddress": "TWoejh9VaC7RxUCHbReXGc9DHCQLYsJehi"
}

GET/api/external/orders

获取用户订单列表，按创建时间倒序排列，支持分页。

curl -H "X-API-Key: YOUR_API_KEY" "https://021.st/api/external/orders?page=1&limit=10"

{
  "orders": [
    {
      "receiveAddress": "TRX_ADDRESS",
      "payNums": "65000",
      "orderMoney": "5.140000",
      "orderNotes": "用户备注",
      "createdAt": "2025-04-26 10:12:45",
      "activationFeePaid": true,
      "remark": "该笔订单触发了地址激活（含1.1TRX激活费）",
      "state": "成功",
      "clientRef": "你方业务单号"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 87, "totalPages": 9 }
}

POST/api/orders/estimate

根据能量数量计算预估租用费用（TRX）。可选传入 receiveAddress，以便判断目标地址是否需要激活并计入 1.1 TRX 激活费。

认证: 需要 API Key（在 body 中）

{
  "apiKey": "YOUR_API_KEY",
  "payNums": 65000,
  "rentTime": 1,
  "receiveAddress": "TRX_ADDRESS"
}

{
  "estimatedCost": "4.040000",
  "needActivation": true,
  "activationFee": "1.100000"
}

POST/api/orders/rent

根据提供的参数创建能量租用订单。若目标地址未激活，系统会自动激活后再委托能量（加收 1.1 TRX）。

{
  "apiKey": "YOUR_API_KEY",
  "payNums": 65000,
  "rentTime": 1,
  "receiveAddress": "TRX_ADDRESS",
  "orderNotes": "订单备注 (可选)",
  "clientRef": "可选, 你方业务单号 (≤64字符)"
}

{
  "orderId": "ORDER_ID",
  "localOrderId": 123,
  "message": "订单创建成功",
  "activation_fee_paid": true
}

GET/api/orders

获取与该 API Key 关联用户的订单历史记录，支持分页。

PUT/api/external/callback-config

配置订单最终状态（成功/失败）的回调地址与验签密钥。配置后，订单终态确定时我们会主动推送通知，无需你轮询。callbackUrl 传空表示关闭回调。

{
  "callbackUrl": "https://your-domain.com/tron/callback",
  "callbackSecret": "用于校验回调签名(HMAC-SHA256)"
}

POST→ 你配置的 callbackUrl

订单最终状态确定时，由我方主动向你配置的回调地址发起 POST 推送。

{
  "event": "order.success",
  "eventId": "123:order.success",
  "orderRef": "123",
  "clientRef": "你方业务单号",
  "status": "success",
  "receiveAddress": "TRX_ADDRESS",
  "energy": "65000",
  "rentTime": 1,
  "money": "2.940000",
  "timestamp": "2026-07-13 16:05:00"
}