TRONAgg API
What is TRONAgg API?
The TRONAgg API lets you rent TRON Energy or Bandwidth for one hour at TRONAgg's price. Your application can get quotes, buy either resource, and track orders — all through a simple REST API. Energy is the default; set resource_type=BANDWIDTH on the estimate and the purchase to rent Bandwidth.
Base URL
https://tronagg.ai/api/v1
All endpoints are relative to this base URL.
Authentication
Every request requires an API key in the X-API-Key header — except the endpoints tagged public-api (pricing and energy estimators), which need no key. Create one in the TRONAgg workspace under API Keys.
curl -H "X-API-Key: ta_your_key_here" https://tronagg.ai/api/v1/account
See the Authentication guide for key management, security best practices, and error handling.
Endpoints Overview
The core purchase flow and its history:
| Endpoint | Method | Description |
|---|---|---|
/account | GET | Check your balance, deposit address, and linked wallet |
/estimate | GET | Get a price quote before buying |
/buy | POST | Rent Energy or Bandwidth for a receiver address |
/order/{id} | GET | Track order status and get delegation TX IDs |
/orders | GET | List your orders, newest first |
/transactions | GET | Your balance ledger: purchases, deposits, refunds, fees |
/deposits | GET | Your incoming TRX deposits |
The API also covers webhooks (push notifications instead of polling), AutoEnergy subscriptions, the Energy Agent and TRONAgg Radar address monitoring; see the sidebar for every endpoint.
Ready to make your first call? Follow the Quickstart for a step-by-step walkthrough, or jump to Code Examples for copy-paste Python and JavaScript snippets.
Error Codes
| Code | Description |
|---|---|
400 | Bad request — check your parameters. Includes insufficient_balance: top up your account |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — the account is blocked, or the request's source IP is outside the key's allowlist (ip_not_allowed) |
404 | Resource not found |
409 | Conflict — e.g. duplicate_request: a purchase with the same Idempotency-Key is still being processed |
422 | Validation error — see detail field for specifics |
429 | Rate limit exceeded — wait the number of seconds in the Retry-After header |
500 | Server error — retry or contact support |
502 | A dependent operation failed (e.g. an energy-estimator simulation) — retry shortly |
503 | Temporarily unavailable — retry later |
Every error code, the response shapes and the idempotency rules are listed in Errors & conventions.
Rate Limits
Each account may make 1,000 requests per minute, shared by all of its API keys and signed-in workspace sessions. Past that you receive 429 Too Many Requests with a Retry-After header — wait that many seconds before retrying. The public endpoints are limited per IP instead; see each endpoint.
Integrate with an AI coding assistant
Rather than write the client by hand, hand the whole integration to an AI coding assistant. Paste the prompt below into Claude, Cursor, or ChatGPT — it carries everything the assistant needs (base URL, X-API-Key auth, SUN units, and the endpoints) to build a working integration.
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.
Prefer not to write code at all? The same operations are available as an MCP server — connect your assistant directly and let it call TRONAgg as a tool instead of writing an integration. See Use TRONAgg from AI agents (MCP).
Authentication
- API Key: ApiKeyAuth
API key obtained from your TRONAgg workspace under API Keys. Keys use the format ta_... and must be passed in the X-API-Key header with every request. Keep your key secret — if it is compromised, revoke it and create a new one immediately.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |