跳到主要内容

指南：充值 → 购买 → 跟踪

从空账户到能量到账，只需四个 API 调用——充值、确认、购买、跟踪。纯请求/响应，任何语言都可以，无需 Webhook。

下面每个调用都用同样的方式鉴权：

Headers: { "X-API-Key": "ta_your_key_here" }

第 1 步——获取充值地址​

GET https://tronagg.ai/api/v1/account
{
  "balance_trx": "0",
  "deposit_address": "TKVSa...",   // 向这里转 TRX 充值
  "wallet_address": ""             // 你绑定的登录钱包，未绑定时为 ""——不是充值地址
}

从任意钱包或交易所向 deposit_address 转入 TRX。

第 2 步——确认充值到账​

GET https://tronagg.ai/api/v1/deposits?limit=10
{
  "deposits": [
    {
      "tx_hash": "a1b2c3...",
      "amount_sun": 100000000,
      "amount_trx": "100",
      "status": "confirmed",
      "credited_at": "2026-07-24T10:30:05Z",  // 几秒内即被设置——此刻起资金即可使用
      "verified_at": null,                    // 区块固化后填入（防重组）
      "created_at": "2026-07-24T10:30:05Z"
    }
  ],
  "has_more": false
}
  • 每隔约 5 秒轮询一次，直到出现一条与你交易的 tx_hash 对应（或任何你之前没见过）的充值，且 status: "confirmed"。
  • 有 credited_at 就可以继续——你可以立即购买。verified_at 是几分钟后到来的、防重组的最终确认。
  • 在极少数情况下，交易在入账后被链上丢弃，该充值会变为 failed，金额会被扣回（GET /transactions 中的一条 deposit_reversal 记录）。

第 3 步——购买能量​

POST https://tronagg.ai/api/v1/buy
Headers: { "Idempotency-Key": "any-unique-string" }
{
  "receiver_address": "TYourReceiverAddress...",
  "resource_amount": 131000
}
{
  "order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "PENDING",
  "total_price_sun": 3500000,
  "total_price_trx": "3.5",        // 实际扣费金额
  "activation_fee_sun": 0,         // 接收地址需要激活时，已计入总价
  "balance_after_sun": 96500000    // 扣费后的剩余余额
}
  • POST /buy 会从你的余额扣款，所以务必发送 Idempotency-Key（任意唯一字符串，不超过 128 个字符）。超时后用同一个密钥重发——你会拿回原订单，而不会被扣第二次。关于 409 duplicate_request 的情况，见幂等性。
  • 数量上下限由 GET /estimate 以 min_amount / max_amount 返回。请把 receiver_address 也传给报价接口：如果该地址从未在 TRON 上激活，购买会包含一笔一次性激活费。
  • 无效的 receiver_address 会在任何扣款之前返回 400 invalid_address。

第 4 步——跟踪到交付​

GET https://tronagg.ai/api/v1/order/{order_id}
{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "COMPLETED",                    // PENDING → COMPLETED | FAILED
  "resource_amount": 131000,
  "receiver_address": "TYourReceiverAddress...",
  "total_price_trx": "3.5",
  "delegation_txids": ["7f00e1..."],        // COMPLETED 后的链上委托交易（部分交付方式下可能为空）
  "error_message": null                     // 仅在 FAILED 时有值
}
  • 每 2–3 秒轮询一次——订单通常在几秒内完结。
  • FAILED 的订单会自动退款到你的余额；error_message 会说明原因。

整个集成就是这些。

完整示例（Python）​

first_integration.py
import time, uuid
import httpx

client = httpx.Client(
    base_url="https://tronagg.ai/api/v1",
    headers={"X-API-Key": "ta_your_key_here"},
)

print("充值到：", client.get("/account").json()["deposit_address"])
seen = {d["tx_hash"] for d in client.get("/deposits").json()["deposits"]}

def new_confirmed_deposit():
    deposits = client.get("/deposits").json()["deposits"]
    return any(d["tx_hash"] not in seen and d["status"] == "confirmed" for d in deposits)

while not new_confirmed_deposit():
    time.sleep(5)                                        # 等待充值到账

order_id = client.post(
    "/buy",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={"receiver_address": "TYourReceiverAddress...", "resource_amount": 131_000},
).json()["order_id"]

while (order := client.get(f"/order/{order_id}").json())["status"] not in ("COMPLETED", "FAILED"):
    time.sleep(3)                                        # 跟踪到终态

print(order["status"], order.get("delegation_txids"))

可选：用推送代替轮询​

只需注册一次 Webhook，订单完结时 TRONAgg 就会推送一条带签名的 order.status_changed 事件——不再需要轮询循环：

POST https://tronagg.ai/api/v1/webhooks
{ "name": "orders", "url": "https://your-service.example.com/tronagg/webhook" }

请保存响应中的 signing_secret——它只显示这一次。投递信封、签名验证与完整的事件目录：Webhook 事件。

下一步​