5 分钟完成你的第一次 API 调用
四个调用——查账户、询价、购买、确认交付。纯请求/响应，任何语言都可以。
你需要一个 API 密钥才能跟着操作。如果还没有，请先在工作台中创建。
下面每个调用都用同样的方式鉴权：
Headers: { "X-API-Key": "ta_your_key_here" }
第 1 步——查看账户
GET https://tronagg.ai/api/v1/account
{
"balance_trx": "120.5",
"deposit_address": "TKVSa...", // 向这里转 TRX 充值
"wallet_address": "" // 你绑定的登录钱包，未绑定时为 ""——不是充值地址
}
如果余额为零，请从任意钱包或交易所向 deposit_address 转入 TRX，或通过工作台充值。
第 2 步——获取报价
GET https://tronagg.ai/api/v1/estimate?resource_amount=100000&receiver_address=TYourReceiverAddress...
{
"duration": "1h",
"unit_price_sun": "27.000000", // 十进制字符串——请用 decimal 类型解析
"total_price_sun": 2700000,
"total_price_trx": "2.7", // 10 万能量的价格
"activation_fee_sun": 0, // 接收地址尚未在 TRON 上激活时收取的一次性费用（已计入总价）
"activation_fee_trx": "0",
"min_amount": 64000, // 订单数量上下限（null = 无限制）——超出时 POST /buy 返回 400
"max_amount": 1000000 // （示意数值——请以你收到的响应为准）
}
receiver_address 是可选的，但建议传入：如果该地址从未在 TRON 上激活，POST /buy 会加收一次性激活费，而只有带上接收地址的报价才会包含这笔费用。
第 3 步——购买能量
POST https://tronagg.ai/api/v1/buy
Headers: { "Idempotency-Key": "any-unique-string" }
{
"receiver_address": "TYourReceiverAddress...", // 需要能量的地址
"resource_amount": 100000
}
{
"order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"status": "PENDING",
"total_price_sun": 2700000,
"total_price_trx": "2.7", // 立即从你的余额扣除
"activation_fee_sun": 0, // 接收地址需要激活时，已计入总价
"balance_after_sun": 117800000
}
- 务必发送
Idempotency-Key（任意唯一字符串，不超过 128 个字符）。POST /buy会从你的余额扣款——超时后用同一个密钥重发，你会拿回原订单，而不会被扣第二次。并发的重复请求返回409 duplicate_request；如果一直如此，请先查看GET /orders，再用新密钥重试。密钥 24 小时后过期。完整规则：幂等性。 - 无效的
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": 100000,
"receiver_address": "TYourReceiverAddress...",
"total_price_trx": "2.7",
"delegation_txids": ["7f00e1..."], // COMPLETED 后的链上委托交易（部分交付方式下可能为空）
"error_message": null // 仅在 FAILED 时有值
}
- 订单通常在几秒内完成——每 2–3 秒轮询一次。
FAILED的订单会自动退款到你的余额。
只需配置一次 Webhook，订单进入 COMPLETED 或 FAILED 的那一刻，TRONAgg 就会向你推送 order.status_changed 事件。
完整示例（Python）
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()["balance_trx"], "TRX")
estimate = client.get(
"/estimate",
params={"resource_amount": 100_000, "receiver_address": "TYourReceiverAddress..."},
).json()
print("10 万能量价格：", estimate["total_price_trx"], "TRX")
order_id = client.post(
"/buy",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={"receiver_address": "TYourReceiverAddress...", "resource_amount": 100_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"))
租赁 1 小时带宽
同样的端点也可以租用 1 小时带宽。省略 resource_type 时，默认仍为能量。租用带宽时，请在报价和购买中都设置该参数。resource_amount 计的是带宽单位数，不是 TRX。
在环境变量中设置好 TRONAGG_API_KEY 和 RECEIVER_ADDRESS 后，先请求报价：
curl --fail-with-body \
-H "X-API-Key: $TRONAGG_API_KEY" \
"https://tronagg.ai/api/v1/estimate?resource_type=BANDWIDTH&resource_amount=1000&receiver_address=$RECEIVER_ADDRESS"
购买前请检查返回的 min_amount/max_amount 和总价：1,000 单位只是示例，不一定满足最低数量要求。传入接收地址的报价会在需要时包含激活费。如果带宽价格不可用，不要改用能量报价继续下单。
下单时，只生成一次幂等密钥，并在这笔购买的所有重试中沿用它：
IDEMPOTENCY_KEY="$(uuidgen)"
curl --fail-with-body -X POST \
-H "X-API-Key: $TRONAGG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d "{\"receiver_address\":\"$RECEIVER_ADDRESS\",\"resource_amount\":1000,\"resource_type\":\"BANDWIDTH\"}" \
"https://tronagg.ai/api/v1/buy"
这笔购买会从你的 TRONAgg 余额扣款。按第 4 步跟踪返回的 order_id。分销商的终端用户账户无法购买带宽。
每小时价格表是公开的：GET https://tronagg.ai/api/v1/pricing/schedule?resource_type=BANDWIDTH 无需 API 密钥。其 weekday 和 weekend 数组各包含 24 个以 SUN 计的每单位带宽价格，以返回的 timezone 时区中的小时为索引；未公布时两个数组均为空。当前的订单数量上下限和针对该接收地址的总价，请通过 /estimate 获取。