版本：0.1.0

TRONAgg API

什么是 TRONAgg API？

TRONAgg API 让您能够在多家供应商中以最优价格 自动化购买 TRON 能量。您的应用程序可以通过简单的 REST API 以编程方式获取报价、购买能量并跟踪订单。

基础 URL

https://tronagg.ai/api/v1

所有端点均以此基础 URL 为前缀。

认证

每个请求都需要在 X-API-Key 请求头中携带 API key。您可以在 TRONAgg 仪表盘 的 API Keys 下创建。

curl -H "X-API-Key: ta_your_key_here" https://tronagg.ai/api/v1/account

有关密钥管理、安全最佳实践和错误处理，请参阅 认证指南。

端点概览

该 API 提供四个端点，涵盖典型的购买工作流：

端点	方法	说明
/account	GET	查看您的余额、充值地址和钱包
/estimate	GET	在购买前获取价格报价
/buy	POST	为接收方地址购买能量
/order/{id}	GET	跟踪订单状态并获取委托交易 ID

准备好发出第一个调用了吗？请参阅 快速入门 了解分步演示，或前往 代码示例 获取可直接复制的 Python 和 JavaScript 代码片段。

用 AI 编程助手集成

与其手写客户端，不如把整个集成交给 AI 编程助手。将下面的提示词粘贴到 Claude、Cursor 或 ChatGPT——它已包含助手所需的一切（基础 URL、X-API-Key 认证、SUN 单位以及各端点），即可构建一个可用的集成。

You are integrating the TRONAgg REST API to buy TRON Energy programmatically.

- 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 are JSON strings — parse with a decimal type.

Core flow:
- GET /account — my balance and deposit address.
- GET /estimate?resource_amount=<energy> — a price quote, incl. min_amount/max_amount order limits.
- POST /buy — JSON body {"receiver_address": "T...", "resource_amount": <energy>}. Always send a unique Idempotency-Key header; on timeout retry with the SAME key — it returns the original order, never a double charge.
- 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.

Build a small typed client that estimates the cost, buys Energy for a receiver, then polls the order until it reaches a terminal status.

完全不想写代码？这些相同的操作也以 MCP 服务器 形式提供——直接连接你的助手，让它把 TRONAgg 作为工具调用，无需自己编写集成。参见 从 AI 智能体使用 TRONAgg（MCP）。

错误代码

代码	说明
400	请求错误 — 请检查您的参数
401	未授权 — API key 无效或缺失
402	余额不足 — 请为您的账户充值
404	资源未找到
422	验证错误 — 详情请参见 detail 字段
429	超出速率限制 — 请降低请求频率
500	服务器错误 — 请重试或联系支持

速率限制

为确保公平使用，API 受到速率限制。如果超过限制，您将收到 429 Too Many Requests 响应。请稍等几秒后再重试。

认证

API Key: ApiKeyAuth

从您的 TRONAgg 仪表盘 的 API Keys 下获取 API key。密钥格式为 ta_...，必须在每次请求的 X-API-Key 请求头中传递。请妥善保管您的密钥 — 一旦泄露，请立即重新生成。

安全方案类型：	apiKey
请求头参数名：	X-API-Key