TRONENS API

响应格式

真实 API 响应始终包含 success，成功时包含 data。错误使用机器可读的 error 代码。诊断测试文件还会显示 method、url、http_code、duration_ms、request、response 和 curl_error；这些不是公开 API 的字段。真正的 TRONENS 响应位于测试器的 response 字段中。

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": "ERROR_CODE"
}

认证

Authorization: Bearer te_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

在 Authorization 请求头中发送 Bearer token。密钥在账户中创建，并且完整值只显示一次。

每个密钥都可以设置 IP 白名单、每分钟请求限制和过期时间。响应包含 X-RateLimit-Limit 和 X-RateLimit-Remaining；HTTP 429 还包含 Retry-After。

报价

返回该客户价格，并应用账户折扣。

GET /api/v1/quote/?package_id=1&duration_minutes=15
GET /api/v1/quote/?energy_amount=65000&duration_minutes=60

响应示例

{
  "success": true,
  "data": {
    "type": "custom",
    "energy_amount": 65000,
    "duration_minutes": 60,
    "base_price_trx": 1.961,
    "discount_percent": 0,
    "discount_trx": 0,
    "price_trx": 2.05
  }
}

Energy 估算

根据指定 TRON 地址估算所需的 Energy。

{
  "recipient_address": "T...",
  "has_usdt": true
}

响应示例

{
  "success": true,
  "data": {
    "estimated_energy": 65000,
    "recommended_package": {
      "id": 1,
      "name": "65 000 Energy",
      "energy_amount": 65000,
      "duration_minutes": 15
    }
  }
}

创建订单

创建真实订单并从账户 TRX 余额扣款。收款 TRON 地址必须先在网络中激活。新 API 订单异步受理并返回 HTTP 202。建议始终传 external_id；重复相同值会返回已有订单，不会再次扣款。

{
  "external_id": "merchant_93481",
  "package_id": 1,
  "duration_minutes": 15,
  "address": "T..."
}

响应示例

HTTP 202
{
  "success": true,
  "data": {
    "order_id": 123,
    "external_id": "merchant_93481",
    "status": "processing",
    "idempotent": false
  }
}

订单状态

返回订单当前数据和状态。

GET /api/v1/status/?id=123
GET /api/v1/status/?external_id=merchant_93481

时间字段格式为 YYYY-MM-DD HH:MM:SS，使用 TRONENS 服务器时区。

响应示例

{
  "success": true,
  "data": {
    "id": 123,
    "external_id": "merchant_93481",
    "address": "T...",
    "energy_amount": 65000,
    "duration_minutes": 15,
    "price_trx": 1.14,
    "status": "delegated",
    "txid": "...",
    "refunded": false,
    "error_code": null,
    "created_at": "2026-10-03 18:01:00",
    "delivered_at": "2026-10-03 18:01:12",
    "completed_at": null,
    "updated_at": "2026-10-03 18:01:12"
  }
}

状态

余额

账户当前可用的 TRX 余额。

{"success":true,"data":{"balance_trx":125.5}}

Webhook

Webhook 会在订单状态变化时发送订单数据。请使用原始 JSON body 和 webhook secret 验证签名。

X-Webhook-Event: order.delegated
X-Webhook-Id: order-123-order.delegated-...
X-Webhook-Signature: sha256=<hex_hmac>

expected = HMAC_SHA256(raw_json_body, webhook_secret)

{
  "event": "order.delegated",
  "event_id": "order-123-order.delegated-...",
  "created_at": "2026-10-03T15:01:12Z",
  "data": {
    "order_id": 123,
    "external_id": "merchant_93481",
    "address": "T...",
    "energy_amount": 65000,
    "duration_minutes": 15,
    "price_trx": 1.14,
    "status": "delegated",
    "txid": "...",
    "refunded": false,
    "error_code": null,
    "created_at": "2026-10-03 18:01:00",
    "delivered_at": "2026-10-03 18:01:12",
    "completed_at": null,
    "updated_at": "2026-10-03 18:01:12"
  }
}

事件：order.processing、order.delegating、order.delegated、order.undelegating、order.completed、order.review、order.failed。HTTP 2xx 表示投递成功；临时错误最多重试 8 次并逐步延迟。请按 event_id 去重。

错误

error 代码用于程序处理。请使用 HTTP 状态码和 error 字段。