5 分钟内完成您的首次 API 调用
四个调用——查账户、询价、购买、确认交付。纯请求/响应，任何语言都行。
前置条件
您需要一个 API key 才能跟随本教程操作。如果尚未创建，请在仪表盘中创建。
下面每个调用的鉴权方式相同：
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
{
"total_price_sun": 2700000,
"total_price_trx": "2.7", // 10 万 Energy 的价格
"min_amount": 20000, // 订单金额上下限——超出时 POST /buy 返回 400
"max_amount": 100000000
}
第 3 步——购买 Energy
POST https://tronagg.ai/api/v1/buy
Headers: { "Idempotency-Key": "any-unique-string" }
{
"receiver_address": "TYourReceiverAddress...", // 需要 Energy 的地址
"resource_amount": 100000
}
{
"order_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"status": "PENDING",
"total_price_sun": 2700000,
"total_price_trx": "2.7", // 立即从余额扣除
"balance_after_sun": 117800000
}
- 务必带
Idempotency-Key（任意唯一字符串，≤128 字符）。POST /buy会扣余额——超时后用同一个 key 重发即返回原订单，绝不会重复扣费。并发重复请求返回409 duplicate_request；key 24 小时后过期。完整契约：幂等性。
第 4 步——查询订单状态
GET https://tronagg.ai/api/v1/order/{order_id}
{
"id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"status": "COMPLETED", // PENDING → PROCESSING → 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）
quickstart.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()["balance_trx"], "TRX")
estimate = client.get("/estimate", params={"resource_amount": 100_000}).json()
print("10 万 Energy 价格：", 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"))