指南：充值 → 购买 → 跟踪

从空账户到 Energy 到账，只需 4 个 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 秒轮询一次，直到你的充值出现且 credited_at 已设置。
• 有 credited_at 就可以继续——可立即购买。verified_at 是几分钟后跟进的防重组最终确认。

第 3 步——购买 Energy

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",        // 实际扣费
  "balance_after_sun": 96500000    // 扣费后剩余余额
}

• POST /buy 会扣余额，所以务必带 Idempotency-Key（任意唯一字符串，≤128 字符）。超时后用同一个 key 重发——返回原订单，绝不会重复扣费。
• 金额上下限见 GET /estimate 的 min_amount / max_amount。

第 4 步——跟踪到交付

GET https://tronagg.ai/api/v1/order/{order_id}

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": "COMPLETED",                    // PENDING → PROCESSING → 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"])

while not any(d["credited_at"] for d in client.get("/deposits").json()["deposits"]):
    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 事件。

下一步

• 错误与约定——错误信封、幂等性、分页、单位（SUN 与 TRX 字符串）。
• List transactions——你的余额账本，用于支出历史与审计。
• 指南：面向地址群的 AutoEnergy——让地址自动保持 Energy 就绪。