TRONAgg API
什么是 TRONAgg API？
TRONAgg API 让你以 TRONAgg 的价格租用 1 小时的波场（TRON）能量或带宽。你的应用可以通过一个简单的 REST API 获取报价、购买任一资源并跟踪订单。默认为能量；在报价和购买请求中设置 resource_type=BANDWIDTH 即可租用带宽。
基础 URL
https://tronagg.ai/api/v1
所有端点都以此基础 URL 为前缀。
认证
每个请求都需要在 X-API-Key 请求头中携带 API 密钥——标记为 public-api 的端点（价格与能量估算）除外，它们无需密钥。可在 TRONAgg 工作台 的 API 密钥 中创建。
curl -H "X-API-Key: ta_your_key_here" https://tronagg.ai/api/v1/account
关于密钥管理、安全最佳实践和错误处理，请参阅身份验证指南。
端点概览
核心购买流程及其历史记录：
| 端点 | 方法 | 说明 |
|---|---|---|
/account | GET | 查看你的余额、充值地址和绑定的钱包 |
/estimate | GET | 在购买前获取价格报价 |
/buy | POST | 为接收地址租用能量或带宽 |
/order/{id} | GET | 跟踪订单状态并获取委托交易 ID |
/orders | GET | 列出你的订单，最新的在前 |
/transactions | GET | 你的余额账本：购买、充值、退款、手续费 |
/deposits | GET | 你收到的 TRX 充值 |
该 API 还涵盖 Webhook（以推送代替轮询）、AutoEnergy 订阅、Energy Agent 以及 TRONAgg Radar 地址监控；所有端点请见侧边栏。
准备好发出第一个调用了吗？请按照快速开始逐步操作，或前往代码示例获取可直接复制的 Python 和 JavaScript 代码片段。
错误代码
| 代码 | 说明 |
|---|---|
400 | 请求错误——请检查你的参数。包括 insufficient_balance：请为你的账户充值 |
401 | 未授权——API 密钥无效或缺失 |
403 | 禁止访问——账户已被封禁，或请求的来源 IP 不在该密钥的白名单内（ip_not_allowed） |
404 | 资源不存在 |
409 | 冲突——例如 duplicate_request：具有相同 Idempotency-Key 的购买仍在处理中 |
422 | 校验错误——具体信息见 detail 字段 |
429 | 超出速率限制——请等待 Retry-After 响应头给出的秒数 |
500 | 服务器错误——请重试或联系客服 |
502 | 依赖的操作失败（例如能量估算模拟）——请稍后重试 |
503 | 暂时不可用——请稍后重试 |
所有 error 代码、响应结构和幂等性规则，请见错误与约定。
速率限制
每个账户每分钟最多可发出 1,000 个请求，由该账户的所有 API 密钥与已登录的工作台会话共用。超出后你会收到 429 Too Many Requests 以及 Retry-After 响应头——等待该秒数后再重试。公开端点则按 IP 限流；详见各端点说明。
用 AI 编程助手集成
与其手写客户端，不如把整个集成交给 AI 编程助手。把下面的提示词粘贴到 Claude、Cursor 或 ChatGPT——它包含了助手构建可用集成所需的一切（基础 URL、X-API-Key 认证、SUN 单位以及各端点）。
You are integrating the TRONAgg REST API to rent TRON Energy or Bandwidth for one hour.
- Base URL: https://tronagg.ai/api/v1
- Auth: send my API key in an `X-API-Key` header on every request (keep it in an env var, never hardcode).
- Units: integer amounts are in SUN (1 TRX = 1,000,000 SUN); `*_trx` amounts and `unit_price_sun` are JSON strings — parse with a decimal type.
Core flow:
- GET /account — my balance and deposit address.
- GET /estimate?resource_amount=<units>&receiver_address=<T...>[&resource_type=BANDWIDTH] — a 1-hour price quote (ENERGY by default) incl. any one-time activation fee for the receiver, plus that resource's min_amount/max_amount order limits (null = no limit).
- POST /buy — JSON body {"receiver_address": "T...", "resource_amount": <units>, "resource_type": "ENERGY" or "BANDWIDTH" (optional, default ENERGY)}. Always send a unique Idempotency-Key header; on timeout retry with the SAME key — it returns the original order instead of charging twice. If the same key keeps returning 409 duplicate_request, check GET /orders before retrying with a NEW key.
- GET /order/{id} — poll every 2-3s until status is "COMPLETED" or "FAILED" (statuses are UPPERCASE). FAILED orders are auto-refunded.
History & webhooks (optional):
- GET /orders, GET /transactions, GET /deposits — order history, balance ledger, deposit history (deposits: credited_at = spendable, verified_at = reorg-safe).
- POST /webhooks {"name", "url"} — push instead of polling; store the signing_secret from the response (shown once) and verify HMAC-SHA256 over "{timestamp}.{raw_body}" from the X-TronAgg-Signature header.
Errors arrive as {"detail": {"error": "<code>", ...}} — handle insufficient_balance and duplicate_request (409) gracefully. Exceptions: order-amount limits use detail.code (with min/max); 401, 429 and the order 404 have a plain-string detail; request-validation 422s have a detail array.
Build a small typed client that estimates the cost, rents the selected resource for a receiver, then polls the order until it reaches a terminal status.
完全不想写代码？同样的操作也以 MCP 服务器的形式提供——直接连接你的助手，让它把 TRONAgg 当作工具调用，无需编写集成。参见从 AI 智能体使用 TRONAgg（MCP）。
认证
- API Key: ApiKeyAuth
从你的 TRONAgg 工作台 的 API 密钥 中获取 API 密钥。密钥格式为 ta_...，每个请求都必须在 X-API-Key 请求头中携带。请妥善保管你的密钥——一旦泄露，请立即撤销并创建一个新密钥。
安全方案类型： | apiKey |
|---|---|
请求头参数名： | X-API-Key |