{ "openapi": "3.1.0", "info": { "title": "TRONAgg API", "description": "## What is TRONAgg API?\n\nThe TRONAgg API lets you **automate TRON Energy purchases** at TRONAgg's price. Your application can get quotes, buy Energy, and track orders — all through a simple REST API.\n\n## Base URL\n\n```\nhttps://tronagg.ai/api/v1\n```\n\nAll endpoints are relative to this base URL.\n\n## Authentication\n\nEvery 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](https://tronagg.ai/workspace) under **API Keys**.\n\n```bash\ncurl -H \"X-API-Key: ta_your_key_here\" https://tronagg.ai/api/v1/account\n```\n\nSee the [Authentication guide](/api-reference/authentication) for key management, security best practices, and error handling.\n\n## Endpoints Overview\n\nThe core purchase flow and its history:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/account` | GET | Check your balance, deposit address, and linked wallet |\n| `/estimate` | GET | Get a price quote before buying |\n| `/buy` | POST | Purchase Energy for a receiver address |\n| `/order/{id}` | GET | Track order status and get delegation TX IDs |\n| `/orders` | GET | List your orders, newest first |\n| `/transactions` | GET | Your balance ledger: purchases, deposits, refunds, fees |\n| `/deposits` | GET | Your incoming TRX deposits |\n\nThe API also covers [webhooks](/api-reference/webhooks) (push notifications instead of polling), [AutoEnergy](/api-reference/guide-autoenergy-fleet) subscriptions, the [Energy Agent](/api-reference/agent-get-summary) and [TRONAgg Radar](/api-reference/radar-get-status) address monitoring; see the sidebar for every endpoint.\n\nReady to make your first call? Follow the [Quickstart](/api-reference/quickstart) for a step-by-step walkthrough, or jump to [Code Examples](/api-reference/code-examples) for copy-paste Python and JavaScript snippets.\n\n## Error Codes\n\n| Code | Description |\n|------|-------------|\n| `400` | Bad request — check your parameters. Includes `insufficient_balance`: top up your account |\n| `401` | Unauthorized — invalid or missing API key |\n| `403` | Forbidden — the account is blocked, or the request's source IP is outside the key's allowlist (`ip_not_allowed`) |\n| `404` | Resource not found |\n| `409` | Conflict — e.g. `duplicate_request`: a purchase with the same `Idempotency-Key` is still being processed |\n| `422` | Validation error — see `detail` field for specifics |\n| `429` | Rate limit exceeded — wait the number of seconds in the `Retry-After` header |\n| `500` | Server error — retry or contact support |\n| `502` | A dependent operation failed (e.g. an energy-estimator simulation) — retry shortly |\n| `503` | Temporarily unavailable — retry later |\n\nEvery `error` code, the response shapes and the idempotency rules are listed in [Errors & conventions](/api-reference/errors-and-conventions).\n\n## Rate Limits\n\nEach 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.\n\n## Integrate with an AI coding assistant\n\nRather 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.\n\n```text\nYou are integrating the TRONAgg REST API to buy TRON Energy programmatically.\n\n- Base URL: https://tronagg.ai/api/v1\n- Auth: send my API key in an `X-API-Key` header on every request (keep it in an env var, never hardcode).\n- 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.\n\nCore flow:\n- GET /account — my balance and deposit address.\n- GET /estimate?resource_amount=&receiver_address= — a price quote incl. any one-time activation fee for the receiver, plus min_amount/max_amount order limits (null = no limit).\n- POST /buy — JSON body {\"receiver_address\": \"T...\", \"resource_amount\": }. 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.\n- GET /order/{id} — poll every 2-3s until status is \"COMPLETED\" or \"FAILED\" (statuses are UPPERCASE). FAILED orders are auto-refunded.\n\nHistory & webhooks (optional):\n- GET /orders, GET /transactions, GET /deposits — order history, balance ledger, deposit history (deposits: credited_at = spendable, verified_at = reorg-safe).\n- 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.\n\nErrors arrive as {\"detail\": {\"error\": \"\", ...}} — 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.\n\nBuild a small typed client that estimates the cost, buys Energy for a receiver, then polls the order until it reaches a terminal status.\n```\n\nPrefer 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)](/tools/ai-agents-mcp).", "version": "0.1.0" }, "servers": [ { "url": "https://tronagg.ai/api/v1", "description": "Production" } ], "paths": { "/account": { "get": { "tags": [ "programmatic-api" ], "summary": "Get Account", "description": "Returns your account information: balance in TRX, the deposit address for topping up, and your linked login wallet address (an empty string if no wallet is linked).", "operationId": "get_account", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/estimate": { "get": { "tags": [ "programmatic-api" ], "summary": "Get Estimate", "description": "Returns TRONAgg's current price for `resource_amount` Energy delivered for 1 hour — what `POST /buy` would charge your balance right now (your VIP price if you have one).\n\n**Parameters:**\n- `resource_amount` — amount of Energy to buy (in Energy units, not TRX)\n- `receiver_address` (optional) — the address that will receive the Energy. Pass it to include the one-time account-activation fee when the address is not yet activated on TRON. Without it the quote leaves that fee out, while `POST /buy` still charges it.\n\nThe response includes the unit price in SUN, the total cost, any activation fee, and the order-size limits (`min_amount` / `max_amount`). Use it to preview costs before committing to a purchase.", "operationId": "get_estimate", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "resource_amount", "in": "query", "required": true, "schema": { "type": "integer", "exclusiveMinimum": 0, "title": "Resource Amount" } }, { "name": "receiver_address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Receiver Address" }, "description": "Address that will receive the Energy. When it is not yet activated on TRON, the one-time activation fee is added to the totals and returned in `activation_fee_sun`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" } } } }, "400": { "description": "`unsupported_resource` or `invalid_duration` — only Energy for a 1-hour duration is offered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "422": { "description": "Request validation failed (e.g. `resource_amount` missing or not above 0) — `detail` is an array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "503": { "description": "`service_unavailable` — Energy purchasing is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/buy": { "post": { "tags": [ "programmatic-api" ], "summary": "Buy Energy", "description": "Purchase Energy for a receiver address. The cost is deducted from your account balance immediately — including a one-time account-activation fee (`activation_fee_sun`) when the receiver is not yet activated on TRON. The order starts as `PENDING`; Energy is typically delegated within seconds. Use the **Get Order** endpoint to poll for completion.\n\n`receiver_address` is checked before anything is charged: an invalid address returns `400 invalid_address`.\n\nSend an `Idempotency-Key` header so that a retry after a timeout returns the original order instead of placing a second one — see [Idempotency](/api-reference/errors-and-conventions#idempotency).", "operationId": "buy_energy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyResponse" } } } }, "400": { "description": "Purchase rejected; nothing was charged:\n- `insufficient_balance` — your balance is below the order total (no `message`; carries `current_balance` and `required_amount` in SUN)\n- `order_amount_below_minimum` / `order_amount_above_maximum` — keyed by `code`, with `min` / `max`\n- `invalid_address` — `receiver_address` is not a valid TRON address\n- `invalid_idempotency_key` — `Idempotency-Key` longer than 128 characters\n- `unsupported_resource` — only Energy is offered", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiInsufficientBalanceError" }, { "$ref": "#/components/schemas/ApiOrderAmountLimitError" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist. Or `reseller_suspended` (no `message`) — purchasing is suspended for your account; contact support.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "409": { "description": "`duplicate_request` — a request with the same `Idempotency-Key` is still being processed. Retry with the same key after a few seconds. If it keeps returning 409, check `GET /orders` before retrying with a new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Request body validation failed (e.g. a missing field, `resource_amount` not above 0, or a `duration` other than `1h`) — `detail` is an array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "500": { "description": "`internal_error` — unexpected error; the order was not placed. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "`service_unavailable` — Energy purchasing is temporarily unavailable; or `reseller_activation_balance_low` (no `message`) — purchasing is temporarily unavailable for your account. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128, "title": "Idempotency-Key" }, "description": "Any unique string of up to 128 characters (a UUID works well). A retry with the same key within 24 hours returns the original order's response instead of placing a new order." } ] } }, "/order/{order_id}": { "get": { "tags": [ "programmatic-api" ], "summary": "Get Order", "description": "Retrieve details for a specific order by its UUID. Use this to track order progress after creating a purchase.\n\n**Order statuses** (always upper-case):\n- `PENDING` — order placed and paid; Energy delegation in progress\n- `COMPLETED` — Energy delegated (`delegation_txids` usually lists the on-chain delegation transaction IDs)\n- `FAILED` — the order could not be fulfilled and was refunded automatically (see `error_message`)\n\nOrders placed through the API go `PENDING` → `COMPLETED` or `FAILED`. Orders paid directly from a wallet may also show `AWAITING_PAYMENT` or `PROCESSING`.", "operationId": "get_order", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Order Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "404": { "description": "`Order not found` — no such order, or it is not yours. `detail` is a plain string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "422": { "description": "`order_id` is not a valid UUID — `detail` is an array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } } } }, "/calculator/estimate-energy": { "get": { "tags": [ "public-api" ], "summary": "Energy Estimator", "description": "Find out **exactly how much energy** a TRC20 transfer will consume before you buy a rental — no guessing, no overpaying. TRONAgg simulates the `transfer(address,uint256)` call on-chain against live network state and returns the precise energy the transaction would burn, plus the equivalent TRX cost at the current `getEnergyFee` rate.\n\nDefaults to **USDT**; pass `contract_address` to estimate any other TRC20 token.\n\n**Why use it**\n- Size your energy rental precisely instead of relying on rough averages\n- Compare energy cost across different TRC20 tokens\n- Detect first-time receivers (a brand-new recipient costs ~2x more energy)\n\n**Good to know**\n- Energy prices move in real time — round the returned value **up** when placing an order\n- Rate limits: 10 req/min per IP, shared by both estimator endpoints (`429`), and 60 req/min shared to the TRON node (`503`)\n\nFor a quick USDT-only check, see the [USDT shortcut](/api-reference/estimate-energy-usdt) which takes the two addresses straight in the URL.", "operationId": "energy_estimator", "parameters": [ { "name": "from_address", "in": "query", "required": true, "schema": { "type": "string", "title": "From Address" }, "description": "Sender TRON address (T..., 34 chars)" }, { "name": "to_address", "in": "query", "required": true, "schema": { "type": "string", "title": "To Address" }, "description": "Receiver TRON address (T..., 34 chars)" }, { "name": "contract_address", "in": "query", "required": false, "schema": { "type": "string", "default": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "title": "Contract Address" }, "description": "TRC20 contract address. Defaults to USDT." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateEnergyResponse" } } } }, "422": { "description": "Invalid TRON address — `detail` is a string, e.g. `Invalid TRON address format: …`. A missing required parameter returns a `detail` array of field errors instead.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] } } } }, "429": { "description": "Rate limit exceeded — more than 10 requests/min from your IP, counted across both estimator endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } }, "502": { "description": "The TRON node could not simulate the transfer (contract error, invalid transaction, etc.)", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } }, "503": { "description": "The global outbound rate limit to the TRON node is exhausted — retry shortly", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } } } } }, "/calculator/estimate-energy/usdt/{from_address}/{to_address}": { "get": { "tags": [ "public-api" ], "summary": "Estimate USDT Transfer Energy", "description": "The fastest way to estimate a **USDT** transfer: pass the sender and receiver right in the URL and get back the exact energy it will burn — perfect for a quick lookup or a copy-paste link.\n\nIt runs the same on-chain simulation as the [Energy Estimator](/api-reference/energy-estimator), with the USDT contract (`TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`) wired in for you. Need a different TRC20 token? Use the full [Energy Estimator](/api-reference/energy-estimator) endpoint instead.\n\n**Good to know**\n- Energy prices move in real time — round the returned value **up** when placing an order\n- Rate limits: 10 req/min per IP, shared by both estimator endpoints (`429`), and 60 req/min shared to the TRON node (`503`)", "operationId": "estimate_energy_usdt", "parameters": [ { "name": "from_address", "in": "path", "required": true, "schema": { "type": "string", "title": "From Address" }, "description": "Sender TRON address (T..., 34 chars)" }, { "name": "to_address", "in": "path", "required": true, "schema": { "type": "string", "title": "To Address" }, "description": "Receiver TRON address (T..., 34 chars)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateEnergyResponse" } } } }, "422": { "description": "Invalid TRON address — `detail` is a string, e.g. `Invalid TRON address format: …`. A missing required parameter returns a `detail` array of field errors instead.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] } } } }, "429": { "description": "Rate limit exceeded — more than 10 requests/min from your IP, counted across both estimator endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } }, "502": { "description": "The TRON node could not simulate the transfer (contract error, invalid transaction, etc.)", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } }, "503": { "description": "The global outbound rate limit to the TRON node is exhausted — retry shortly", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "title": "Detail" } } } } } } } } }, "/pricing": { "get": { "tags": [ "public-api" ], "summary": "Current Energy Price", "description": "Our **live Energy price** — the same numbers the [tronagg.ai/pricing](https://tronagg.ai/pricing) page shows, as JSON. No API key required.\n\nThe snapshot carries our current price per Energy unit (in SUN), the anonymous market average across the public providers we track, how far below that average we sit, and the cost of the standard reference orders (65k Energy = 1 USDT transfer, 131k = 2) in TRX and ≈ USD.\n\n**Good to know**\n- Prices refresh about every minute; responses are cached server-side for ~60s\n- `below_market_percent` is `null` whenever we are not actually below the market average — the field never asserts a false claim\n- The market average is an anonymous aggregate — individual provider prices are never exposed", "operationId": "get_pricing", "responses": { "200": { "description": "Current pricing snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } } } } }, "/pricing/history": { "get": { "tags": [ "public-api" ], "summary": "Energy Price History", "description": "Our Energy price vs the anonymous market average **over time**. No API key required.\n\nPass `hours` for an hourly series (up to 168h / 7 days) or `days` for a daily series (up to 365). With neither, the series defaults to the **last 24 hours, hourly**. `hours` wins when both are given.\n\nEach point carries our price (SUN), the market average (SUN), and our price for a 65,000-Energy order — one USDT transfer — in TRX.\n\n**How buckets work**\n- Buckets are UTC-aligned. The series covers the last N hours or days and may include the current, partial bucket, so it can hold up to N+1 points\n- Each point is the last price recorded in its bucket (for `days`, the day's closing hourly rate), not an average over the bucket\n- Buckets without a recorded price of ours are left out\n\n**Good to know**\n- Responses are cached server-side for ~60s\n- Buckets with no recorded market data have `market_avg_price_sun: null`", "operationId": "get_pricing_history", "parameters": [ { "name": "hours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 168 }, { "type": "null" } ], "title": "Hours" }, "description": "Hourly window, up to 168h (7d). Takes precedence over `days`." }, { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ], "title": "Days" }, "description": "Daily window, up to 365d. Ignored if `hours` is set." } ], "responses": { "200": { "description": "Price history series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingHistoryResponse" } } } }, "422": { "description": "Validation error — `hours` or `days` out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pricing/auto-energy": { "get": { "tags": [ "public-api" ], "summary": "AutoEnergy Plan Pricing (Public)", "description": "Public pricing for the default [AutoEnergy](/api-reference/autoenergy-subscribe) plan — the activation fee, daily subscription fee, per-transfer charges, and minimum-usage fee, each in both SUN and TRX. No API key required.\n\nSame shape as [`GET /autoenergy/pricing`](/api-reference/autoenergy-pricing), but always shows the default plan, which may differ from a tariff assigned to your account. Responses are cached server-side for ~60s.", "operationId": "get_pricing_autoenergy", "responses": { "200": { "description": "Default AutoEnergy plan pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyPlanInfo" } } } } } } }, "/autoenergy/subscriptions": { "post": { "tags": [ "AutoEnergy" ], "summary": "Subscribe", "description": "Create **and activate** a subscription for an address: validates the address, charges the activation fee, and starts delegating Energy. Requires the entry threshold (activation fee + one daily fee + one 131k transfer) in balance. An address may hold only one live subscription, so the call is naturally idempotent on the active address — a repeat returns `409 address_busy`.\n\n**Billing**\n\n- The activation fee is charged now. The daily fee is first charged 24h after activation, then every 24h after the previous charge; missed cycles are not back-billed.\n- Each covered transfer is charged by its energy class (65k or 131k).\n- The subscription closes automatically with `insufficient_balance` when a daily fee can't be paid, or when, after a billed transfer, your balance is below one daily fee + one 131k transfer.\n- If the plan sets `min_daily_tx`, a completed 24h cycle with fewer transfers is charged `penalty_sun` once, as `autoenergy_penalty`.\n\nRead [`GET /autoenergy/pricing`](/api-reference/autoenergy-pricing) for the current amounts.", "operationId": "autoenergy_subscribe", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergySubscribeRequest" } } } }, "responses": { "201": { "description": "Subscription created and activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergySubscriptionResponse" } } } }, "400": { "description": "`insufficient_balance` — balance can't cover the entry threshold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "403": { "description": "`reseller_suspended` — AutoEnergy is suspended for your account. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "409": { "description": "`address_busy` — the address already has a live subscription (yours, or another account's: if `GET /autoenergy/subscriptions/{address}` returns 404, another account covers it); or `address_exists` — you have a closed subscription on it (reactivate or delete it first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "422": { "description": "`invalid_address` (object body, `detail.error`), or request validation failed (array body: `detail` is a list of field errors — e.g. `idle_hours` outside 24–72, `quota_max_tx` below 1, `expire_at` in the past).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AutoEnergyErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] } } } }, "500": { "description": "`internal_error` — unexpected server error. Check [`GET /autoenergy/subscriptions/{address}`](/api-reference/autoenergy-get-subscription) before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "502": { "description": "`fulfiller_unavailable` — Energy delegation could not be started right now. Nothing was charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "503": { "description": "`autoenergy_temporarily_unavailable` or `reseller_activation_balance_low` — AutoEnergy is temporarily unavailable for your account. Nothing was charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } }, "get": { "tags": [ "AutoEnergy" ], "summary": "List subscriptions", "description": "Return every AutoEnergy subscription owned by the authenticated key's user (active and closed).", "operationId": "autoenergy_list_subscriptions", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The caller's subscriptions.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AutoEnergySubscriptionResponse" } } } } } } } }, "/autoenergy/subscriptions/{address}": { "get": { "tags": [ "AutoEnergy" ], "summary": "Get subscription", "description": "Return the subscription for the given TRON address. An address you don't own is indistinguishable from a missing one — both return `404 not_found`.", "operationId": "autoenergy_get_subscription", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergySubscriptionResponse" } } } }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } }, "patch": { "tags": [ "AutoEnergy" ], "summary": "Update settings", "description": "Apply a partial settings update (idle window, transfer cap, expiry). Only provided fields change. An explicit `null` removes the transfer cap (`quota_max_tx`) or the expiry (`expire_at`), or turns off idle auto-close (`idle_hours`). Works on closed subscriptions too.", "operationId": "autoenergy_update_subscription", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyUpdateSettingsRequest" } } } }, "responses": { "200": { "description": "The updated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergySubscriptionResponse" } } } }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "422": { "description": "Request validation failed (e.g. `expire_at` in the past, `idle_hours` outside 24–72, `quota_max_tx` below 1); `detail` is an array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "AutoEnergy" ], "summary": "Delete subscription", "description": "Soft-delete a **closed** subscription: it disappears from the list, its history is kept, and the address can be added again as a fresh subscription. Only a closed subscription can be deleted.", "operationId": "autoenergy_delete", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." } ], "responses": { "204": { "description": "Deleted. No content." }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "409": { "description": "`not_deletable` — only a closed subscription can be deleted (close it first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } } }, "/autoenergy/subscriptions/{address}/reactivate": { "post": { "tags": [ "AutoEnergy" ], "summary": "Reactivate", "description": "Re-open a **closed** subscription: charges the activation fee again, resets `tx_used_total`, clears `closed_at`/`close_reason`, and resumes delegation. Requires the same entry threshold as subscribe (activation fee + one daily fee + one 131k transfer). The daily fee is first charged 24h after the reactivation.\n\nSettings (`idle_hours`, `quota_max_tx`, `expire_at`) are kept: if `expire_at` is already in the past, update or clear it first, or the subscription closes again as `expired`.", "operationId": "autoenergy_reactivate", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." } ], "responses": { "200": { "description": "The reactivated subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergySubscriptionResponse" } } } }, "400": { "description": "`insufficient_balance` — balance is below the entry threshold (activation fee + one daily fee + one 131k transfer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "403": { "description": "`reseller_suspended` — AutoEnergy is suspended for your account. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "409": { "description": "`not_reactivatable` — the subscription is not closed; or `address_busy` — the address now has a live subscription on another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "500": { "description": "`internal_error` — unexpected server error. Check [`GET /autoenergy/subscriptions/{address}`](/api-reference/autoenergy-get-subscription) before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "502": { "description": "`fulfiller_unavailable` — Energy delegation could not be resumed right now. Nothing was charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } }, "503": { "description": "`autoenergy_temporarily_unavailable` or `reseller_activation_balance_low` — AutoEnergy is temporarily unavailable for your account. Nothing was charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } } }, "/autoenergy/subscriptions/{address}/close": { "post": { "tags": [ "AutoEnergy" ], "summary": "Close", "description": "Close the subscription for the address (`close_reason: \"manual\"`). Nothing sent after the close is billed; transfers made before it may still appear as charges shortly after.\n\nClosing an already-closed subscription returns `204` and changes nothing — the original `close_reason` and `closed_at` are kept. A manual close does not send the `autoenergy.closed` webhook.", "operationId": "autoenergy_close", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." } ], "responses": { "204": { "description": "Closed (or already closed). No content." }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } } }, "/autoenergy/subscriptions/{address}/usage": { "get": { "tags": [ "AutoEnergy" ], "summary": "List usage", "description": "Return the usage events (covered transfers) for the subscription, most recent first. An event whose charge could not be collected has `billed_sun: 0`.", "operationId": "autoenergy_usage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Usage events, most recent first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AutoEnergyUsageItem" } } } } }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } } }, "/autoenergy/subscriptions/{address}/billing": { "get": { "tags": [ "AutoEnergy" ], "summary": "List billing", "description": "Return the charges billed for the subscription — activation, daily subscription, minimum-usage fee, and per-transfer — most recent first.", "operationId": "autoenergy_billing", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "The TRON address the subscription is bound to." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "title": "Offset" } } ], "responses": { "200": { "description": "Charges, most recent first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AutoEnergyBillingItem" } } } } }, "404": { "description": "`not_found` — no such subscription for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyErrorResponse" } } } } } } }, "/autoenergy/pricing": { "get": { "tags": [ "AutoEnergy" ], "summary": "Get pricing", "description": "Return the AutoEnergy pricing that applies to your new subscriptions: a tariff assigned to your account, otherwise the default plan. Pricing can change — call this rather than hard-coding the numbers.", "operationId": "autoenergy_pricing", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Pricing that applies to your new subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoEnergyPlanInfo" } } } } } } }, "/orders": { "get": { "tags": [ "programmatic-api" ], "summary": "List Orders", "description": "List your Energy orders, newest first. Results are paginated with `page`/`page_size`.\n\n**Filters:**\n- `status` — return only orders in this status (`PENDING`, `COMPLETED`, `FAILED`, …). Case-insensitive.\n- `receiver_address` — return only orders delivered to exactly this address. Pass the full 34-character TRON address; a partial address matches nothing.", "operationId": "list_orders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Page Size" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "description": "Return only orders in this status, e.g. `COMPLETED`. Case-insensitive." }, { "name": "receiver_address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Receiver Address" }, "description": "Return only orders whose receiver is exactly this TRON address." } ], "responses": { "200": { "description": "A page of orders, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiOrderListResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "422": { "description": "A query parameter is out of range (e.g. `page_size` above 100) — `detail` is an array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } } } }, "/transactions": { "get": { "tags": [ "programmatic-api" ], "summary": "List Transactions", "description": "List your balance-ledger entries, newest first. Uses opaque cursor pagination: pass the `next_cursor` from a response as the `cursor` of the next request, and repeat until `has_more` is `false`.\n\nOptionally filter to a single ledger entry type with `entry_type`.", "operationId": "list_transactions", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" }, "description": "Opaque pagination cursor: the `next_cursor` from the previous response, passed back unchanged. An unparsable value returns `400 invalid_cursor`; a cursor that does not match one of your entries restarts from the newest entry." }, { "name": "entry_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "deposit", "purchase", "withdrawal", "fee", "refund", "promo", "deposit_reversal", "reseller_markup", "reseller_commission", "reseller_transfer", "reseller_subsidy", "autoenergy_activate", "autoenergy_daily", "autoenergy_unit", "autoenergy_penalty", "agent_income", "energy_pass", "withdrawal_reversal" ] }, { "type": "null" } ], "title": "Entry Type" }, "description": "Filter to a single ledger entry type." } ], "responses": { "200": { "description": "A cursor-paginated ledger page, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTransactionListResponse" } } } }, "400": { "description": "`invalid_cursor` — the supplied `cursor` value could not be decoded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } } } }, "/deposits": { "get": { "tags": [ "programmatic-api" ], "summary": "List Deposits", "description": "List incoming TRX deposits to your account, newest first, using `limit`/`offset` pagination.\n\n- `credited_at` — when the deposit was credited; the funds are spendable from then on.\n- `verified_at` — set once the deposit clears its final check on the solidified chain, usually a few minutes later.\n- `status` — `confirmed` once credited; `failed` if the transaction was later dropped from the chain and the amount was debited back (a `deposit_reversal` ledger entry).\n\nThe list also includes TRX payments received on your Energy Agent dedicated addresses (credited as `agent_income`).", "operationId": "list_deposits", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } } ], "responses": { "200": { "description": "A page of deposits, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDepositListResponse" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "The account is blocked (plain-string `detail`: `Account is blocked`), or `ip_not_allowed` — the request's source IP is outside this key's IP allowlist.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiPlainErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorResponse" } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded` — more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } } } }, "/webhooks": { "post": { "tags": [ "programmatic-api" ], "summary": "Create Webhook", "description": "Register an HTTPS webhook endpoint to receive event notifications. The response returns the created destination and its `signing_secret`.\n\n**The signing secret is shown exactly once — store it now; it cannot be retrieved later.** Use it to verify the signature of incoming webhook deliveries.\n\nA webhook created here has `order.status_changed` enabled; the other events follow the per-event defaults listed in [Webhook events](/api-reference/webhook-events#events).\n\nRequirements:\n- Your account needs more than 1 TRX of **net confirmed deposits** (confirmed deposits minus withdrawals, including their fees). Purchases don't reduce it; withdrawals do.\n- The URL must use HTTPS and its host must resolve only to public IP addresses (`localhost`, `*.local` and `tronagg.ai` hosts are rejected). The host is checked again before every delivery.\n- Redirects are not followed. A trailing `/` is removed from the URL.\n- One webhook per URL, at most 10 webhooks per account.", "operationId": "create_webhook", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationCreate" } } } }, "responses": { "201": { "description": "Webhook created. The `signing_secret` is returned only here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationCreated" } } } }, "400": { "description": "The webhook could not be created. `detail.error` is one of:\n\n- `validation_error` — the URL does not use HTTPS, has no host, is a `tronagg.ai` host, its host could not be resolved or does not resolve only to public IP addresses; the URL is already connected to your account; or your account already has 10 webhooks. `detail.message` explains which.\n- `webhook_deposit_required` — your account does not yet have more than 1 TRX of net confirmed deposits. The body also carries `total_deposited_sun` (your current net confirmed deposits in SUN: confirmed deposits minus withdrawals, including their fees, floored at 0) and `required_total_deposited_sun` (`1000001`). Both are integers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" }, "examples": { "validation_error": { "summary": "Rejected URL", "value": { "detail": { "error": "validation_error", "message": "Webhook URL must use a public host" } } }, "webhook_deposit_required": { "summary": "Net confirmed deposits too low", "value": { "detail": { "error": "webhook_deposit_required", "message": "A confirmed deposit total greater than 1 TRX is required to create webhooks", "total_deposited_sun": 0, "required_total_deposited_sun": 1000001 } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "programmatic-api" ], "summary": "List Webhooks", "description": "List your registered webhook destinations. Signing secrets are never included. Your Telegram channels are not listed here.", "operationId": "list_webhooks", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Your webhook destinations.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationDestinationResponse" }, "title": "Response List Webhooks" } } } } } } }, "/webhooks/{destination_id}": { "delete": { "tags": [ "programmatic-api" ], "summary": "Delete Webhook", "description": "Delete one of your webhooks by id. Only webhook destinations can be deleted here; the id of any other notification channel (such as a Telegram chat) returns `404`.", "operationId": "delete_webhook", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Destination Id" } } ], "responses": { "204": { "description": "Deleted. No content." }, "404": { "description": "`not_found` — no webhook with this id on your account (including ids of non-webhook channels).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/webhooks/{destination_id}/test": { "post": { "tags": [ "programmatic-api" ], "summary": "Test Webhook", "description": "Send a signed `notification.test` event to the webhook to verify connectivity and your signature check. Returns `{\"status\": \"sent\"}` when your endpoint answers `2xx` within 10 seconds.\n\nLimited to 5 tests per hour per account, shared with the workspace **Send test** button.", "operationId": "test_webhook", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "destination_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Destination Id" } } ], "responses": { "200": { "description": "Test notification sent.", "content": { "application/json": { "schema": { "type": "object", "title": "TestWebhookResponse", "properties": { "status": { "type": "string", "enum": [ "sent" ], "title": "Status" } }, "required": [ "status" ] } } } }, "404": { "description": "`not_found` — no such webhook for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Too many tests — the limit is 5 per hour per account (shared with the workspace). The body is a plain string `detail`, not the structured error envelope.", "content": { "application/json": { "schema": { "type": "object", "title": "WebhookTestRateLimited", "properties": { "detail": { "type": "string", "title": "Detail", "example": "Too many webhook tests; limit is 5 per hour" } }, "required": [ "detail" ] } } } }, "502": { "description": "`delivery_failed` — the test notification could not be delivered to your endpoint: a non-`2xx` response, no answer within 10 seconds, a redirect, a connection error, or the URL no longer resolves only to public IP addresses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/summary": { "get": { "tags": [ "Energy Agent" ], "summary": "Energy Agent overview", "description": "Program status, your balance against the activation threshold (`can_activate`), your limits, `energy_min` (the minimum `energy_per_unit`) and `energy_max` (the maximum `energy_per_unit × max_units`, `null` = no limit), the price of 65,000 Energy (`quote_65k`, same shape as `GET /agent/quote`) and your lifetime sales totals. All amounts are integer SUN.", "operationId": "agent_get_summary", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSummary" } } } }, "503": { "description": "`service_unavailable`: prices are temporarily unavailable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBusinessError" }, "examples": { "service_unavailable": { "value": { "detail": { "error": "service_unavailable" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/agent/quote": { "get": { "tags": [ "Energy Agent" ], "summary": "What an amount of Energy costs you", "description": "`cost_now_sun` is what a sale of `energy` would be charged right now (your price, VIP discount included, rounded exactly like the charge). `cost_min_sun`/`cost_max_sun` are the lowest/highest retail price (no VIP discount) over the published weekly schedule and the current rate, in `timezone`; with a VIP discount `cost_now_sun` can be below `cost_min_sun`. A configuration's `base_payment_sun` must be at least `cost_max_sun` for its `energy_per_unit`.", "operationId": "agent_get_quote", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "energy", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 1000000000, "minimum": 1, "title": "Energy" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentQuote" } } } }, "503": { "description": "`service_unavailable`: prices are temporarily unavailable; retry later.", "content": { "application/json": { "examples": { "service_unavailable": { "value": { "detail": { "error": "service_unavailable" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/configs": { "get": { "tags": [ "Energy Agent" ], "summary": "List your configurations", "description": "Every active or paused configuration you own, newest first.", "operationId": "agent_list_configs", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Energy Agent" ], "summary": "Create a configuration", "description": "`own`: receive payments on your own address (`address` required). `generated`: we issue a dedicated address (omit `address`); payments to it are added to your balance, and it can be paused but never deleted. Requires the program enabled (403 `program_disabled`) and the activation balance (422 `below_min_balance`). Limits come from `GET /agent/summary`: `max_units` from 1 to `max_units_cap`; `energy_per_unit` at least `energy_min` and `energy_per_unit × max_units` at most `energy_max`. `base_payment_sun` must be a multiple of 1,000 SUN and at least `cost_max_sun` from `GET /agent/quote?energy=`. Unknown fields are a 422.", "operationId": "agent_create_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfig" } } } }, "403": { "description": "`program_disabled`: the program is not accepting changes right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBusinessError" }, "examples": { "program_disabled": { "value": { "detail": { "error": "program_disabled" } } } } } } }, "409": { "description": "`address_taken`: the address already belongs to an active configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBusinessError" }, "examples": { "address_taken": { "value": { "detail": { "error": "address_taken" } } } } } } }, "422": { "description": "Request validation error (a `detail` array) or a business refusal.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HTTPValidationError" }, { "$ref": "#/components/schemas/AgentBusinessError" } ] }, "examples": { "address_invalid": { "value": { "detail": { "error": "address_invalid" } } }, "address_reserved": { "value": { "detail": { "error": "address_reserved" } } }, "config_limit": { "value": { "detail": { "error": "config_limit", "max_configs": 10 } } }, "generated_limit": { "value": { "detail": { "error": "generated_limit", "max_generated": 3 } } }, "units_out_of_bounds": { "value": { "detail": { "error": "units_out_of_bounds", "max_units_cap": 50 } } }, "energy_out_of_bounds": { "value": { "detail": { "error": "energy_out_of_bounds", "energy_min": 65000, "energy_max": 1000000 } } }, "base_not_mtrx": { "value": { "detail": { "error": "base_not_mtrx" } } }, "base_below_cost": { "value": { "detail": { "error": "base_below_cost", "cost_max_sun": 2340000 } } }, "below_min_balance": { "value": { "detail": { "error": "below_min_balance", "min_balance_sun": 10000000, "balance_sun": 4200000 } } } } } } }, "503": { "description": "`service_unavailable`: prices are temporarily unavailable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBusinessError" }, "examples": { "service_unavailable": { "value": { "detail": { "error": "service_unavailable" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/agent/configs/{config_id}": { "patch": { "tags": [ "Energy Agent" ], "summary": "Update a configuration", "description": "Partial update: omitted fields stay unchanged and `title: null` clears the title; the numeric fields can't be null. Mode and address cannot change. Changing a numeric field re-checks the create limits. New values apply to payments received after the update.", "operationId": "agent_update_config", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Config Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfigUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfig" } } } }, "404": { "description": "`not_found`: no such configuration on your account.", "content": { "application/json": { "examples": { "not_found": { "value": { "detail": { "error": "not_found" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "422": { "description": "Request validation error (a `detail` array) or a business refusal.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HTTPValidationError" }, { "$ref": "#/components/schemas/AgentBusinessError" } ] }, "examples": { "units_out_of_bounds": { "value": { "detail": { "error": "units_out_of_bounds", "max_units_cap": 50 } } }, "energy_out_of_bounds": { "value": { "detail": { "error": "energy_out_of_bounds", "energy_min": 65000, "energy_max": 1000000 } } }, "base_not_mtrx": { "value": { "detail": { "error": "base_not_mtrx" } } }, "base_below_cost": { "value": { "detail": { "error": "base_below_cost", "cost_max_sun": 2340000 } } } } } } }, "503": { "description": "`service_unavailable`: prices are temporarily unavailable; retry later.", "content": { "application/json": { "examples": { "service_unavailable": { "value": { "detail": { "error": "service_unavailable" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } } } }, "delete": { "tags": [ "Energy Agent" ], "summary": "Delete a configuration", "description": "Own-address configurations only. A generated address is permanent (409 `generated_not_deletable`) — pause it instead. A configuration paused by support answers 409 `admin_paused`. A deleted configuration disappears from `GET /agent/configs` and its address can be used again; its payments stay in `GET /agent/payments` and in your totals.", "operationId": "agent_delete_config", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Config Id" } } ], "responses": { "204": { "description": "Successful Response" }, "404": { "description": "`not_found`: no such configuration on your account.", "content": { "application/json": { "examples": { "not_found": { "value": { "detail": { "error": "not_found" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "409": { "description": "`generated_not_deletable` (a TRONAgg address can't be deleted) or `admin_paused` (paused by TRONAgg support).", "content": { "application/json": { "examples": { "generated_not_deletable": { "value": { "detail": { "error": "generated_not_deletable" } } }, "admin_paused": { "value": { "detail": { "error": "admin_paused" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/configs/{config_id}/pause": { "post": { "tags": [ "Energy Agent" ], "summary": "Pause a configuration", "description": "Sets `pause_reason: user`; this also stops the automatic resume of an `insufficient_balance` pause. Payments to the address still arrive (credited to your balance for a TRONAgg address) but deliver no Energy, and nothing is returned to the customer. A configuration paused by support keeps `pause_reason: admin`. Idempotent.", "operationId": "agent_pause_config", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfig" } } } }, "404": { "description": "`not_found`: no such configuration on your account.", "content": { "application/json": { "examples": { "not_found": { "value": { "detail": { "error": "not_found" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agent/configs/{config_id}/resume": { "post": { "tags": [ "Energy Agent" ], "summary": "Resume a configuration", "description": "No-op on an active configuration. Otherwise a configuration paused by support answers 409 `admin_paused`; any other pause is lifted if the program is enabled (403 `program_disabled`) and your balance meets the activation threshold (422 `below_min_balance`).", "operationId": "agent_resume_config", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Config Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConfig" } } } }, "403": { "description": "`program_disabled`: the program is not accepting changes right now.", "content": { "application/json": { "examples": { "program_disabled": { "value": { "detail": { "error": "program_disabled" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "404": { "description": "`not_found`: no such configuration on your account.", "content": { "application/json": { "examples": { "not_found": { "value": { "detail": { "error": "not_found" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "409": { "description": "`admin_paused`: paused by TRONAgg support; contact support to resume.", "content": { "application/json": { "examples": { "admin_paused": { "value": { "detail": { "error": "admin_paused" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } }, "422": { "description": "Request validation error (a `detail` array) or `below_min_balance`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HTTPValidationError" }, { "$ref": "#/components/schemas/AgentBusinessError" } ] }, "examples": { "below_min_balance": { "value": { "detail": { "error": "below_min_balance", "min_balance_sun": 10000000, "balance_sun": 4200000 } } } } } } } } } }, "/agent/payments": { "get": { "tags": [ "Energy Agent" ], "summary": "Payments to your configurations", "description": "Newest first. `status`: processing, delivering, completed, failed (the order failed and its cost was refunded to your balance; the customer's TRX is not returned automatically) or skipped (no Energy; see `skip_reason`, which is `null` when the TRX transfer was reversed on-chain before Energy was ordered). `units`/`energy` are what the payment buys under the configuration at detection time. A sale whose TRX transfer was later reversed on-chain stays `completed` here but is left out of your totals. With slow-delivery compensation on your account, a late sale can be refunded to your balance while it stays `completed` with its original `cost_sun`.", "operationId": "agent_list_payments", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "config_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Config Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "processing", "delivering", "completed", "failed", "skipped" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPaymentPage" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/pay/{public_id}": { "get": { "tags": [ "Energy Agent" ], "summary": "Energy Agent payment details", "description": "Where to send TRX and what each payment buys: every `base_payment_sun` sent delivers `energy_per_unit` Energy for 1 hour to the sending address, up to `max_units` units per payment. Send plain TRX from the wallet that should receive the Energy (not from an exchange). TRC20 tokens and transfers under 0.1 TRX are ignored, and a payment sent from the configuration's own address delivers nothing. Only whole units up to `max_units` are delivered; any remainder or excess is not returned. `available` is true when a payment sent now would buy Energy; payments sent while it is false deliver no Energy. Cached for ~30s.", "operationId": "agent_get_pay_page", "parameters": [ { "name": "public_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Public Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPayConfig" } } } }, "404": { "description": "`not_found`: unknown or deleted link.", "content": { "application/json": { "examples": { "not_found": { "value": { "detail": { "error": "not_found" } } } }, "schema": { "$ref": "#/components/schemas/AgentBusinessError" } } } } }, "security": [] } }, "/watch/status": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Get Radar status", "description": "Your TRONAgg Radar status in one call. It answers even before access is granted, so it's the place to find out why Radar isn't available yet.\n\n- `enabled` and `access`: whether Radar is on and this account may use it; `access.reason` is `radar_disabled`, `account_disabled` or `radar_access_required` when it may not.\n- `head_block`, `lag_seconds` and `state`: how fresh Radar's view of the chain is. `delayed` means more than 30 seconds behind; readiness is then not confirmed by fresh data.\n- `limits`: your two address limits (`watch_only` for *Only alert me*, `with_energy` for the Energy actions) and how much of each is used.\n- `counts`: addresses by readiness and attention.\n- `today`: Energy additions since 00:00 UTC, what they cost (purchases in progress included) and the estimated TRX your sweeps didn't burn.", "operationId": "radar_get_status", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarStatus" }, "example": { "enabled": true, "access": { "granted": true, "reason": null }, "head_block": 87137548, "lag_seconds": 2, "state": "live", "limits": { "watch_only": { "used": 5, "max": 100 }, "with_energy": { "used": 1240, "max": 10000 } }, "counts": { "watched": 1245, "ready": 37, "needs_attention": 2, "attention_security": 1, "not_ready": 3, "waiting_to_sweep": 12, "energy_paused": 0, "watching": 5 }, "today": { "energy_added": 41, "spent_sun": 71955000, "saved_sun": 191634000 } } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/scenarios": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "List scenarios", "description": "Every scenario of your account, oldest first, with how many addresses use it (`address_count`) and what it spent today (`spent_today_sun`, since 00:00 UTC).", "operationId": "radar_list_scenarios", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioList" }, "example": { "scenarios": [ { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a70", "name": "Watched addresses", "action": "alert_only", "threshold": null, "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 50000000, "repeat_if_unswept": false, "energy_alerts": false, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": [ "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a62" ], "address_count": 5, "spent_today_sun": 0, "created_at": "2026-10-04T09:10:02Z", "updated_at": "2026-10-04T09:10:02Z" }, { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100.000000", "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 50000000, "repeat_if_unswept": false, "energy_alerts": true, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": null, "address_count": 1240, "spent_today_sun": 14040000, "created_at": "2026-10-04T09:12:44Z", "updated_at": "2026-10-04T09:12:44Z" } ] } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "TRONAgg Radar" ], "summary": "Create a scenario", "description": "Create a scenario: what Radar does for a group of addresses. Only `name` and `action` are required; every other field has a default.\n\n- `action`: `alert_only` (alerts only, never buys Energy), `add_on_deposit` (Energy for one transfer when deposits reach `threshold`, default `\"100\"`) or `add_after_transfer` (Energy for the next transfer after each one that used Energy).\n- `threshold`: counts USDT that arrives after the address joins the scenario and isn't swept yet. USDT already on the address doesn't count.\n- `energy_preset`: `65k` (a recipient that already holds USDT, default), `131k` (any recipient) or `custom` with `energy_custom`.\n- `energy_alerts`: Energy warnings (`address.energy.insufficient`, `address.trx.low`). Omitted, they're off for `alert_only` and on for the Energy actions, which always warn.\n- `notify_destination_ids`: `null` sends to every channel (new ones included), `[]` keeps alerts in Radar, a list sends to those channels only.\n\nNames are unique per account. Creating a scenario costs nothing: Energy is bought only when an address in it needs it.", "operationId": "radar_create_scenario", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioCreate" }, "example": { "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100", "energy_preset": "65k", "daily_budget_sun": 50000000 } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioView" }, "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100.000000", "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 50000000, "repeat_if_unswept": false, "energy_alerts": true, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": null, "address_count": 1240, "spent_today_sun": 14040000, "created_at": "2026-10-04T09:12:44Z", "updated_at": "2026-10-04T09:12:44Z" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "409": { "description": "`scenario_name_taken`: you already have a scenario with this name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "scenario_name_taken": { "value": { "detail": { "error": "scenario_name_taken", "message": "You already have a scenario with this name" } } } } } } }, "422": { "description": "Input Radar can't accept, with `field` naming it: `invalid_name`, `invalid_action`, `invalid_threshold`, `invalid_energy_preset`, `invalid_energy` (custom Energy outside `energy_min`…`energy_max`), `invalid_times_per_address_day`, `invalid_daily_budget` (outside `min_sun`…`max_sun`), `invalid_energy_alerts`, `invalid_active_hours`, `invalid_usdt_low_threshold`, `invalid_destinations` (`unknown` lists channel ids that aren't yours). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_name": { "value": { "detail": { "error": "invalid_name", "message": "Name must be 1 to 80 printable characters", "field": "name" } } }, "invalid_action": { "value": { "detail": { "error": "invalid_action", "message": "action must be alert_only, add_on_deposit or add_after_transfer", "field": "action" } } }, "invalid_threshold": { "value": { "detail": { "error": "invalid_threshold", "message": "Use up to six USDT decimal places", "field": "threshold" } } }, "invalid_energy_preset": { "value": { "detail": { "error": "invalid_energy_preset", "message": "energy_preset must be 65k, 131k or custom", "field": "energy_preset" } } }, "invalid_energy": { "value": { "detail": { "error": "invalid_energy", "message": "Custom Energy per charge is outside the order limits", "field": "energy_custom", "energy_min": 63999, "energy_max": 1000000 } } }, "invalid_times_per_address_day": { "value": { "detail": { "error": "invalid_times_per_address_day", "message": "Times per address a day must be 1 to 1000", "field": "times_per_address_day" } } }, "invalid_daily_budget": { "value": { "detail": { "error": "invalid_daily_budget", "message": "The daily budget is outside the allowed range", "field": "daily_budget_sun", "min_sun": 1000000, "max_sun": 1000000000000 } } }, "invalid_energy_alerts": { "value": { "detail": { "error": "invalid_energy_alerts", "message": "Scenarios that add Energy always warn about Energy", "field": "energy_alerts" } } }, "invalid_active_hours": { "value": { "detail": { "error": "invalid_active_hours", "message": "Working hours need an IANA time zone", "field": "active_hours" } } }, "invalid_usdt_low_threshold": { "value": { "detail": { "error": "invalid_usdt_low_threshold", "message": "The low-USDT alert needs a positive amount in raw units (6 decimals)", "field": "usdt_low_threshold_raw" } } }, "invalid_destinations": { "value": { "detail": { "error": "invalid_destinations", "message": "Alerts can only go to your own notification channels", "field": "notify_destination_ids", "unknown": [ "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a99" ] } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/scenarios/{scenario_id}": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Get a scenario", "description": "One scenario, with `address_count` and `spent_today_sun`.", "operationId": "radar_get_scenario", "parameters": [ { "name": "scenario_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Scenario Id" }, "description": "The scenario's id." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioView" }, "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100.000000", "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 50000000, "repeat_if_unswept": false, "energy_alerts": true, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": null, "address_count": 1240, "spent_today_sun": 14040000, "created_at": "2026-10-04T09:12:44Z", "updated_at": "2026-10-04T09:12:44Z" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "422": { "description": "The request didn't match the schema: FastAPI's `detail` array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "TRONAgg Radar" ], "summary": "Update a scenario", "description": "Change a scenario. Send only the fields to change; an explicit `null` clears a nullable field (`active_hours` → any time, `usdt_low_threshold` → off, `notify_destination_ids` → every channel). Changes apply to all of the scenario's addresses right away.\n\nChanging `action`:\n\n- moving away from `add_on_deposit` drops the threshold; moving to it without one sets `\"100\"`;\n- moving to an Energy action turns `energy_alerts` on; moving to `alert_only` turns it off unless you send `\"energy_alerts\": true`;\n- open deposits close, incoming USDT counts toward the threshold from zero again, and waiting Energy additions are cancelled;\n- when the addresses move between the `watch_only` and `with_energy` limits, all of them must fit (`409 radar_limit_exceeded`).\n\nSwitching `energy_preset` away from `custom` drops `energy_custom`.", "operationId": "radar_update_scenario", "parameters": [ { "name": "scenario_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Scenario Id" }, "description": "The scenario's id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioUpdate" }, "example": { "daily_budget_sun": 100000000, "repeat_if_unswept": true } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarScenarioView" }, "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100.000000", "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 100000000, "repeat_if_unswept": true, "energy_alerts": true, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": null, "address_count": 1240, "spent_today_sun": 14040000, "created_at": "2026-10-04T09:12:44Z", "updated_at": "2026-10-05T08:00:12Z" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "409": { "description": "`scenario_name_taken`; `radar_limit_exceeded` when a new action moves the addresses to a limit without room for all of them (`kind`, `used`, `max`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "scenario_name_taken": { "value": { "detail": { "error": "scenario_name_taken", "message": "You already have a scenario with this name" } } }, "radar_limit_exceeded": { "value": { "detail": { "error": "radar_limit_exceeded", "message": "This change would exceed your Radar address limit", "kind": "watch_only", "used": 60, "max": 100 } } } } } } }, "422": { "description": "Input Radar can't accept, with `field` naming it: `invalid_name`, `invalid_action`, `invalid_threshold`, `invalid_energy_preset`, `invalid_energy` (custom Energy outside `energy_min`…`energy_max`), `invalid_times_per_address_day`, `invalid_daily_budget` (outside `min_sun`…`max_sun`), `invalid_energy_alerts`, `invalid_active_hours`, `invalid_usdt_low_threshold`, `invalid_destinations` (`unknown` lists channel ids that aren't yours). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_name": { "value": { "detail": { "error": "invalid_name", "message": "Name must be 1 to 80 printable characters", "field": "name" } } }, "invalid_action": { "value": { "detail": { "error": "invalid_action", "message": "action must be alert_only, add_on_deposit or add_after_transfer", "field": "action" } } }, "invalid_threshold": { "value": { "detail": { "error": "invalid_threshold", "message": "Use up to six USDT decimal places", "field": "threshold" } } }, "invalid_energy_preset": { "value": { "detail": { "error": "invalid_energy_preset", "message": "energy_preset must be 65k, 131k or custom", "field": "energy_preset" } } }, "invalid_energy": { "value": { "detail": { "error": "invalid_energy", "message": "Custom Energy per charge is outside the order limits", "field": "energy_custom", "energy_min": 63999, "energy_max": 1000000 } } }, "invalid_times_per_address_day": { "value": { "detail": { "error": "invalid_times_per_address_day", "message": "Times per address a day must be 1 to 1000", "field": "times_per_address_day" } } }, "invalid_daily_budget": { "value": { "detail": { "error": "invalid_daily_budget", "message": "The daily budget is outside the allowed range", "field": "daily_budget_sun", "min_sun": 1000000, "max_sun": 1000000000000 } } }, "invalid_energy_alerts": { "value": { "detail": { "error": "invalid_energy_alerts", "message": "Scenarios that add Energy always warn about Energy", "field": "energy_alerts" } } }, "invalid_active_hours": { "value": { "detail": { "error": "invalid_active_hours", "message": "Working hours need an IANA time zone", "field": "active_hours" } } }, "invalid_usdt_low_threshold": { "value": { "detail": { "error": "invalid_usdt_low_threshold", "message": "The low-USDT alert needs a positive amount in raw units (6 decimals)", "field": "usdt_low_threshold_raw" } } }, "invalid_destinations": { "value": { "detail": { "error": "invalid_destinations", "message": "Alerts can only go to your own notification channels", "field": "notify_destination_ids", "unknown": [ "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a99" ] } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "TRONAgg Radar" ], "summary": "Delete a scenario", "description": "Delete a scenario. One that still has addresses needs `move_to`: all of them move there first, or nothing changes. Moved addresses follow the new scenario from then on: only USDT that arrives after the move counts toward its threshold.", "operationId": "radar_delete_scenario", "parameters": [ { "name": "scenario_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Scenario Id" }, "description": "The scenario to delete." }, { "name": "move_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Move To" }, "description": "The scenario that takes over its addresses. Required while it has addresses." } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account. `scenario_not_found` also covers a `move_to` that isn't yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "409": { "description": "`scenario_has_addresses`: the scenario has addresses and no `move_to` (`address_count` says how many); `radar_limit_exceeded`: `move_to` uses the other limit, without room for them all.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "scenario_has_addresses": { "value": { "detail": { "error": "scenario_has_addresses", "message": "This scenario still has addresses: choose a scenario to move them to", "address_count": 1240 } } }, "radar_limit_exceeded": { "value": { "detail": { "error": "radar_limit_exceeded", "message": "This change would exceed your Radar address limit", "kind": "with_energy", "used": 1000, "max": 1000 } } } } } } }, "422": { "description": "`invalid_move_to`: `move_to` is the scenario being deleted. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_move_to": { "value": { "detail": { "error": "invalid_move_to", "message": "Move the addresses to another scenario", "field": "move_to" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/check": { "post": { "tags": [ "TRONAgg Radar" ], "summary": "Check addresses", "description": "Preview a list before adding it: for each address, whether it's `new`, already watched (`exists`, with its `scenario_id`) or `invalid`. Results keep the order of your list, with each address as you sent it. Changes nothing.", "operationId": "radar_check_addresses", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarCheckRequest" }, "example": { "addresses": [ "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz", "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb2" ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarCheckResult" }, "example": { "results": [ { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "status": "exists", "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d" }, { "address": "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz", "status": "new", "scenario_id": null }, { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb2", "status": "invalid", "scenario_id": null } ] } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "422": { "description": "`invalid_batch`: send 1 to 1,000 addresses. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_batch": { "value": { "detail": { "error": "invalid_batch", "message": "Send between 1 and 1000 addresses", "field": "addresses" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "List addresses", "description": "Your watched addresses, with readiness, balances, the open deposit and attention items. Page with `next_cursor`: send it back as `cursor` with the same filters and `sort`. `total` counts every address matching the filters.", "operationId": "radar_list_addresses", "parameters": [ { "name": "scenario_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Scenario Id" }, "description": "Only addresses of this scenario." }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "needs_attention", "not_ready", "waiting_to_sweep", "energy_paused" ] }, { "type": "null" } ], "title": "State" }, "description": "`needs_attention`: an unreviewed security alert or a current problem. `not_ready`: `needs_energy`, `not_activated`, `frozen`, `low_trx` or `unknown`. `waiting_to_sweep`: a deposit waits to be swept. `energy_paused`: Energy is paused." }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Q" }, "description": "Search the label, the address and the external ID." }, { "name": "external_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "External Id" }, "description": "Exactly this external ID." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "last_activity", "title": "Sort", "enum": [ "last_activity", "usdt_desc", "waiting_desc" ] }, "description": "`last_activity` (newest activity first), `usdt_desc` (largest USDT balance first) or `waiting_desc` (deposit waiting longest first)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Limit" }, "description": "Addresses per page, 1 to 200." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Cursor" }, "description": "`next_cursor` of the previous page. Keep the same filters and `sort`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddressPage" }, "example": { "addresses": [ { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "label": "deposit-0042", "display_name": "deposit-0042", "external_id": "invoice-4821", "scenario": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit" }, "status": "active", "readiness": { "state": "ready", "energy_available": 65000, "energy_target": 65000, "energy_required": 64285, "deficit": 0, "stale": false, "updated_at": "2026-10-04T18:05:16Z", "energy_expires_at": "2026-10-04T19:05:15Z" }, "balances": { "usdt": "1250.000000", "trx_sun": 0 }, "episode": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "opened_at": "2026-10-04T18:04:57Z", "balance": "1250.000000", "waiting_seconds": 21, "blocker": null }, "last_event": { "kind": "address.sweep.ready", "at": "2026-10-04T18:05:18Z", "summary": "Sweep ready", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e" }, "attention": [], "additions_today": 1, "activated": true, "usdt_frozen": false, "energy_in_flight": false } ], "has_more": true, "next_cursor": "WyJhIiwxNzI4MDY1MTE4LCIwMTk5YTFiMiJd", "total": 1245 } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "422": { "description": "`invalid_state`, `invalid_sort`, `invalid_cursor`. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_state": { "value": { "detail": { "error": "invalid_state", "message": "Invalid address filter", "field": "state" } } }, "invalid_sort": { "value": { "detail": { "error": "invalid_sort", "message": "Invalid address sort", "field": "sort" } } }, "invalid_cursor": { "value": { "detail": { "error": "invalid_cursor", "message": "Invalid page cursor", "field": "cursor" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "TRONAgg Radar" ], "summary": "Add addresses", "description": "Start watching up to 1,000 addresses in one scenario. Each item gets its own result, in the order you sent them, so one bad line never fails the batch:\n\n- `created`: now watched;\n- `exists`: already watched (in this scenario, or in another one with `existing: \"skip\"`); its scenario, label and external ID don't change;\n- `moved`: was in another scenario and `existing` is `\"move\"`;\n- `duplicate`: the same address earlier in this request;\n- `invalid`: `error` says why: `invalid_address`, `invalid_label`, `invalid_external_id` or `external_id_taken`;\n- `limit_exceeded`: no room left in the scenario's limit. Items are admitted in request order.\n\n`summary` counts each status. An `add_on_deposit` threshold counts USDT that arrives after the address joins the scenario and isn't swept yet. USDT already on the address doesn't count.\n\nRadar alerts only on activity after an address is added.", "operationId": "radar_add_addresses", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddRequest" }, "example": { "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "existing": "skip", "items": [ { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "label": "deposit-0042", "external_id": "invoice-4821" }, { "address": "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz", "label": "deposit-0043" } ] } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddResult" }, "example": { "results": [ { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "status": "created", "error": null }, { "address": "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz", "status": "created", "error": null } ], "summary": { "created": 2, "exists": 0, "moved": 0, "duplicate": 0, "invalid": 0, "limit_exceeded": 0 } } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "422": { "description": "`empty_batch`, `batch_too_large` (more than 1,000 items; `max`), `invalid_existing`. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "empty_batch": { "value": { "detail": { "error": "empty_batch", "message": "Send at least one address", "field": "items" } } }, "batch_too_large": { "value": { "detail": { "error": "batch_too_large", "message": "Send at most 1000 addresses per request", "field": "items", "max": 1000 } } }, "invalid_existing": { "value": { "detail": { "error": "invalid_existing", "message": "existing must be \"skip\" or \"move\"", "field": "existing" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/bulk": { "post": { "tags": [ "TRONAgg Radar" ], "summary": "Change many addresses", "description": "Run one operation on up to 1,000 watched addresses:\n\n- `move` to `scenario_id`: they follow the new scenario from now on, and only USDT that arrives after the move counts toward its threshold;\n- `pause_energy`: no more Energy purchases; alerts and security alerts keep working, and the address keeps its place in the limit;\n- `resume`: Energy purchases again, and a waiting deposit is picked up;\n- `remove`: stop monitoring. The timeline stays for 90 days and the external ID is freed.\n\nEach address gets a result in request order: `ok` (also when nothing had to change), `not_found` (not watched), `limit_exceeded` (`move` without room in the target's limit) or `invalid` (not a TRON address, or repeated in the request).", "operationId": "radar_bulk_addresses", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarBulkRequest" }, "example": { "op": "pause_energy", "addresses": [ "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz" ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarBulkResult" }, "example": { "results": [ { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "status": "ok", "error": null }, { "address": "TXZomAoHDARzFEkZpMBcnp2ycByWYwtUBz", "status": "not_found", "error": null } ], "summary": { "ok": 1, "failed": 1 } } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "422": { "description": "`invalid_op`, `empty_batch`, `batch_too_large`, `scenario_required` (`move` without `scenario_id`). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_op": { "value": { "detail": { "error": "invalid_op", "message": "op must be move, pause_energy, resume or remove", "field": "op" } } }, "empty_batch": { "value": { "detail": { "error": "empty_batch", "message": "Send at least one address", "field": "items" } } }, "batch_too_large": { "value": { "detail": { "error": "batch_too_large", "message": "Send at most 1000 addresses per request", "field": "items", "max": 1000 } } }, "scenario_required": { "value": { "detail": { "error": "scenario_required", "message": "Moving addresses needs scenario_id", "field": "scenario_id" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/{address}": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Get an address", "description": "One watched address: readiness, balances, the open deposit, its last event and its attention items.", "operationId": "radar_get_address", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddressView" }, "example": { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "label": "deposit-0042", "display_name": "deposit-0042", "external_id": "invoice-4821", "scenario": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit" }, "status": "active", "readiness": { "state": "ready", "energy_available": 65000, "energy_target": 65000, "energy_required": 64285, "deficit": 0, "stale": false, "updated_at": "2026-10-04T18:05:16Z", "energy_expires_at": "2026-10-04T19:05:15Z" }, "balances": { "usdt": "1250.000000", "trx_sun": 0 }, "episode": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "opened_at": "2026-10-04T18:04:57Z", "balance": "1250.000000", "waiting_seconds": 21, "blocker": null }, "last_event": { "kind": "address.sweep.ready", "at": "2026-10-04T18:05:18Z", "summary": "Sweep ready", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e" }, "attention": [], "additions_today": 1, "activated": true, "usdt_frozen": false, "energy_in_flight": false } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `address_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "address_not_found": { "value": { "detail": { "error": "address_not_found", "message": "Address not found" } } } } } } }, "422": { "description": "`invalid_address`. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "TRONAgg Radar" ], "summary": "Update an address", "description": "Change a watched address. Send only what changes:\n\n- `label` (up to 80 characters) and `external_id` (up to 128, unique among your watched addresses): an explicit `null` clears them;\n- `scenario_id`: move the address to another scenario; only USDT that arrives after the move counts toward its threshold;\n- `status`: `energy_paused` stops Energy purchases (alerts keep working), `active` resumes them.\n\nReturns the updated address.", "operationId": "radar_update_address", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddressUpdate" }, "example": { "label": "deposit-0042", "status": "energy_paused" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarAddressView" }, "example": { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "label": "deposit-0042", "display_name": "deposit-0042", "external_id": "invoice-4821", "scenario": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit" }, "status": "energy_paused", "readiness": { "state": "energy_paused", "energy_available": 65000, "energy_target": 65000, "energy_required": 64285, "deficit": 0, "stale": false, "updated_at": "2026-10-04T18:05:16Z", "energy_expires_at": "2026-10-04T19:05:15Z" }, "balances": { "usdt": "1250.000000", "trx_sun": 0 }, "episode": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "opened_at": "2026-10-04T18:04:57Z", "balance": "1250.000000", "waiting_seconds": 21, "blocker": null }, "last_event": { "kind": "address.sweep.ready", "at": "2026-10-04T18:05:18Z", "summary": "Sweep ready", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e" }, "attention": [], "additions_today": 1, "activated": true, "usdt_frozen": false, "energy_in_flight": false } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `address_not_found`, `scenario_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "address_not_found": { "value": { "detail": { "error": "address_not_found", "message": "This address is not on Radar" } } }, "scenario_not_found": { "value": { "detail": { "error": "scenario_not_found", "message": "Scenario not found" } } } } } } }, "409": { "description": "`external_id_taken`: another watched address uses this external ID; `radar_limit_exceeded`: the new scenario's limit is full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "external_id_taken": { "value": { "detail": { "error": "external_id_taken", "message": "Another address on Radar already uses this external id", "external_id": "invoice-4821" } } }, "radar_limit_exceeded": { "value": { "detail": { "error": "radar_limit_exceeded", "message": "This change would exceed your Radar address limit", "kind": "with_energy", "used": 1000, "max": 1000 } } } } } } }, "422": { "description": "`invalid_address`, `invalid_label`, `invalid_external_id`, `invalid_status`, `invalid_scenario` (`scenario_id: null`). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } }, "invalid_label": { "value": { "detail": { "error": "invalid_label", "message": "label must be at most 80 printable characters", "field": "label" } } }, "invalid_status": { "value": { "detail": { "error": "invalid_status", "message": "status must be \"active\" or \"energy_paused\"", "field": "status" } } }, "invalid_scenario": { "value": { "detail": { "error": "invalid_scenario", "message": "scenario_id cannot be null", "field": "scenario_id" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "TRONAgg Radar" ], "summary": "Stop monitoring an address", "description": "Stop watching the address: no more alerts and no more Energy. Its events stay in `GET /events` for 90 days, its external ID is freed, and you can add it again at any time.", "operationId": "radar_remove_address", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." } ], "responses": { "204": { "description": "Stopped." }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `address_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "address_not_found": { "value": { "detail": { "error": "address_not_found", "message": "This address is not on Radar" } } } } } } }, "422": { "description": "`invalid_address`. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/{address}/reviews": { "post": { "tags": [ "TRONAgg Radar" ], "summary": "Mark an alert as reviewed", "description": "Mark a security or problem event of this address as reviewed (`event_id` from `attention[]` or the event feed). It leaves the address's attention items; nothing changes on the chain. Repeating it is harmless.", "operationId": "radar_review_event", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarReviewRequest" }, "example": { "event_id": 131 } } } }, "responses": { "204": { "description": "Reviewed." }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `event_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account. `event_not_found` also covers an event of another address, an event that isn't a security or problem alert, and an address you don't watch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "event_not_found": { "value": { "detail": { "error": "event_not_found", "message": "Attention signal not found" } } } } } } }, "422": { "description": "`invalid_address`. A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/{address}/energy/quote": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Quote Energy for an address", "description": "What adding Energy to this address would order and cost right now, for its next transfer. Buys nothing.\n\n- `energy`: the Energy the next transfer still needs, rounded up to the next 1,000 (never below the minimum order).\n- `total_price_sun`: that Energy at this hour's rate, with your VIP price.\n- `activation_fee_sun`: the one-time activation of an address that isn't activated yet, `0` otherwise.\n\nThe payable is `total_price_sun + activation_fee_sun`: pass it as `max_total_price_sun` to [Add Energy](/api-reference/radar-add-energy) to buy at no more than this price.", "operationId": "radar_get_energy_quote", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." }, { "name": "energy_preset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "65k", "131k" ] }, { "type": "null" } ], "title": "Energy Preset" }, "description": "`65k`: one USDT transfer to a wallet that already holds USDT. `131k`: to any wallet. Omitted: the scenario's preset." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarEnergyQuote" }, "example": { "energy": 131000, "total_price_sun": 3537000, "activation_fee_sun": 0 } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `address_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account. `radar_disabled` also means Energy additions are switched off for now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "address_not_found": { "value": { "detail": { "error": "address_not_found", "message": "Watched address not found" } } } } } } }, "409": { "description": "`already_ready`: the address already has the Energy for this preset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "already_ready": { "value": { "detail": { "error": "already_ready", "message": "Already ready" } } } } } } }, "422": { "description": "`invalid_address`, `invalid_energy_preset` (only `65k` or `131k`). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } }, "invalid_energy_preset": { "value": { "detail": { "error": "invalid_energy_preset", "message": "energy_preset must be 65k or 131k", "field": "energy_preset" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/addresses/{address}/energy": { "post": { "tags": [ "TRONAgg Radar" ], "summary": "Add Energy to an address", "description": "Buy Energy for the address's next transfer now, whatever its scenario's action, `alert_only` included. Paid from your TRONAgg balance.\n\n- `energy_preset`: `65k` (a recipient that already holds USDT) or `131k` (any recipient). Omitted: the scenario's preset.\n- `max_total_price_sun` (optional): the most you'll pay, activation included: `total_price_sun + activation_fee_sun` from the [quote](/api-reference/radar-get-energy-quote). If the fresh price is higher, you get `409 quote_expired` with the new `quote` and nothing is bought. Without it, the live price applies.\n\nThe same rules as automatic additions apply: the scenario's working hours, one addition in flight per address, and its `daily_budget_sun` (not `times_per_address_day`). `alert_only` scenarios never buy by themselves and have no budget: there, `max_total_price_sun` and your balance are the only caps. Radar also checks the address on the chain before anything is bought.\n\nThe response is the Action: `reserved` or `ordered` while the Energy is on its way, `delivered` once it arrived. `address.energy.charged` follows when it lands. This never moves USDT and never signs anything for you.", "operationId": "radar_add_energy", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "title": "Address" }, "description": "A watched TRON address (Base58Check, `T…`)." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarManualEnergyRequest" }, { "type": "null" } ], "title": "Body" }, "example": { "energy_preset": "131k", "max_total_price_sun": 3537000 } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarActionView" }, "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60", "kind": "manual", "status": "ordered", "reason": null, "energy_ordered": 131000, "total_price_sun": 3537000, "delegation_txid": null, "ready_at": null, "expires_at": null, "saved_sun": null, "created_at": "2026-10-04T18:04:58Z" } } } }, "400": { "description": "`insufficient_balance`: your balance doesn't cover the order. `current_balance` and `required_amount` are SUN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "insufficient_balance": { "value": { "detail": { "error": "insufficient_balance", "message": "Insufficient balance", "current_balance": 1200000, "required_amount": 3537000 } } } } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `address_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account. `radar_disabled` also means Energy additions are switched off for now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "address_not_found": { "value": { "detail": { "error": "address_not_found", "message": "Watched address not found" } } } } } } }, "409": { "description": "Nothing was bought: `already_ready` (the address has enough Energy), `in_flight` (an addition is already on its way), `budget_exhausted` (the scenario's daily budget), `quote_expired` (the price is above `max_total_price_sun`; `quote` is the new one), `frozen`, `energy_paused`, `outside_hours`, `no_bandwidth`, `contract` (a contract address can't receive Energy), `autoenergy_active` (an AutoEnergy subscription covers the address).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "already_ready": { "value": { "detail": { "error": "already_ready", "message": "Already ready" } } }, "in_flight": { "value": { "detail": { "error": "in_flight", "message": "In flight" } } }, "budget_exhausted": { "value": { "detail": { "error": "budget_exhausted", "message": "Budget exhausted" } } }, "quote_expired": { "value": { "detail": { "error": "quote_expired", "message": "Quote expired", "quote": { "energy": 131000, "total_price_sun": 3591000, "activation_fee_sun": 0 } } } }, "frozen": { "value": { "detail": { "error": "frozen", "message": "Frozen" } } }, "energy_paused": { "value": { "detail": { "error": "energy_paused", "message": "Energy paused" } } }, "outside_hours": { "value": { "detail": { "error": "outside_hours", "message": "Outside hours" } } }, "no_bandwidth": { "value": { "detail": { "error": "no_bandwidth", "message": "No bandwidth" } } }, "contract": { "value": { "detail": { "error": "contract", "message": "Contract" } } }, "autoenergy_active": { "value": { "detail": { "error": "autoenergy_active", "message": "Autoenergy active" } } } } } } }, "422": { "description": "`invalid_address`, `invalid_energy_preset` (only `65k` or `131k`). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } }, "invalid_energy_preset": { "value": { "detail": { "error": "invalid_energy_preset", "message": "energy_preset must be 65k or 131k", "field": "energy_preset" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/events": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "List events", "description": "The event feed: every event of your addresses from the last 90 days, the same events your webhooks receive, **oldest first**.\n\n- **Catch up**: send `since_id` (start with `0`) and store `next_since_id` after each page; it's the `since_id` you sent when there's nothing new.\n- **Finality**: events start as `finality: \"head\"` and turn `solid`, or rarely `reverted`. No webhook is sent for that. With `updated_since`, the feed returns events whose finality changed at or after that time: keep `updated_since` fixed and page with `since_id` from `0`.\n\n`data` is the webhook `data`, exactly as it was sent; the event's own `finality` is the current one.", "operationId": "radar_list_events", "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "description": "Only events of this watched address (Base58Check)." }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "description": "Only this event type, for example `address.sweep.ready`." }, { "name": "since_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 9223372036854775807, "minimum": 0 }, { "type": "null" } ], "title": "Since Id" }, "description": "Events after this id, oldest first. Start with `0`; send `next_since_id` for the next page." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated Since" }, "description": "Only events whose finality changed at or after this time (ISO-8601 with a time zone). Keep it fixed while paging with `since_id`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" }, "description": "Events per page, 1 to 500." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarEventsFeed" }, "example": { "events": [ { "id": 124, "type": "address.usdt.received", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "created_at": "2026-10-04T18:04:57Z", "finality": "solid", "finality_updated_at": "2026-10-04T18:05:51Z", "late": false, "data": { "address_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "display_name": "deposit-0042", "label": "deposit-0042", "external_id": "invoice-4821", "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "scenario_name": "Deposit addresses", "event_id": 124, "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "finality": "head", "asset": "USDT", "direction": "in", "amount": "1250.000000", "counterparty": "TYqHsaXKuUutMYADYKF15hVfVAYfmpggvo", "balance": "1250.000000" }, "review": null }, { "id": 125, "type": "address.sweep.ready", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "created_at": "2026-10-04T18:05:18Z", "finality": "solid", "finality_updated_at": "2026-10-04T18:05:51Z", "late": false, "data": { "address_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "display_name": "deposit-0042", "label": "deposit-0042", "external_id": "invoice-4821", "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "scenario_name": "Deposit addresses", "event_id": 125, "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "finality": "head", "episode_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "balance": "1250.000000", "energy_available": 65000, "energy_required": 64285, "expires_at": "2026-10-04T19:05:15Z", "source": "radar" }, "review": null } ], "next_since_id": 125 } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "422": { "description": "`invalid_address`, `invalid_event_type` (`kind` isn't an `address.*` event), `invalid_timestamp` (`updated_since` without a time zone). A body or parameter of the wrong type, or an unknown body field, returns FastAPI's `detail` array instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/HTTPValidationError" } ] }, "examples": { "invalid_address": { "value": { "detail": { "error": "invalid_address", "message": "Not a valid TRON address", "field": "address" } } }, "invalid_event_type": { "value": { "detail": { "error": "invalid_event_type", "message": "Unknown Radar event type", "field": "kind" } } }, "invalid_timestamp": { "value": { "detail": { "error": "invalid_timestamp", "message": "updated_since must include a time zone", "field": "updated_since" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/events/{signal_id}": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Get an event", "description": "One event with what Radar did about it: its Energy decisions (`actions`) and every delivery to your channels, with attempts, the webhook's HTTP status and latency.", "operationId": "radar_get_event", "parameters": [ { "name": "signal_id", "in": "path", "required": true, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "title": "Signal Id" }, "description": "The event's `id` (equal to `data.event_id` in webhooks)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarEventDetail" }, "example": { "event": { "id": 125, "type": "address.sweep.ready", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "created_at": "2026-10-04T18:05:18Z", "finality": "solid", "finality_updated_at": "2026-10-04T18:05:51Z", "late": false, "data": { "address_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "display_name": "deposit-0042", "label": "deposit-0042", "external_id": "invoice-4821", "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "scenario_name": "Deposit addresses", "event_id": 125, "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "finality": "head", "episode_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "balance": "1250.000000", "energy_available": 65000, "energy_required": 64285, "expires_at": "2026-10-04T19:05:15Z", "source": "radar" }, "review": null }, "actions": [ { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60", "kind": "auto", "status": "delivered", "reason": null, "energy_ordered": 65000, "total_price_sun": 1755000, "delegation_txid": "a91853964b278f64a91853964b278f64a91853964b278f64a91853964b278f64", "ready_at": "2026-10-04T18:05:15Z", "expires_at": "2026-10-04T19:05:15Z", "saved_sun": null, "created_at": "2026-10-04T18:04:58Z" } ], "deliveries": [ { "destination_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a62", "destination_name": "prod sweeper", "channel_type": "webhook", "status": "sent", "attempts": 1, "http_status": 204, "latency_ms": 412, "created_at": "2026-10-04T18:05:18Z", "sent_at": "2026-10-04T18:05:18Z" } ] } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `event_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "event_not_found": { "value": { "detail": { "error": "event_not_found", "message": "Signal not found" } } } } } } }, "422": { "description": "The request didn't match the schema: FastAPI's `detail` array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/events/{signal_id}/redeliver": { "post": { "tags": [ "TRONAgg Radar" ], "summary": "Resend an event", "description": "Send an event again. With `destination_id`, to that channel of yours; without it, to the channels of the address's current scenario. An address you no longer watch needs a `destination_id`.\n\nUp to 5 resends per event and 60 per account per hour; while 200 of your webhook deliveries are still queued, resends wait.", "operationId": "radar_redeliver_event", "parameters": [ { "name": "signal_id", "in": "path", "required": true, "schema": { "type": "integer", "maximum": 9223372036854775807, "minimum": 1, "title": "Signal Id" }, "description": "The event's `id` (equal to `data.event_id` in webhooks)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarRedeliverRequest" }, "example": { "destination_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a62" } } } }, "responses": { "202": { "description": "Queued for delivery." }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`, `event_not_found`, `destination_not_found`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } }, "event_not_found": { "value": { "detail": { "error": "event_not_found", "message": "Signal not found" } } }, "destination_not_found": { "value": { "detail": { "error": "destination_not_found", "message": "Channel not found" } } } } } } }, "409": { "description": "`address_not_watched`: the address is no longer watched, so name a `destination_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "address_not_watched": { "value": { "detail": { "error": "address_not_watched", "message": "Choose a channel to resend a past address event" } } } } } } }, "422": { "description": "The request didn't match the schema: FastAPI's `detail` array of field errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "`redelivery_rate_limited` (5 per event, 60 per account per hour) or `redelivery_backlogged` (200 webhook deliveries still queued). The API-wide limit of 1,000 requests a minute also applies, with a plain-string `detail` and `Retry-After`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "redelivery_rate_limited": { "value": { "detail": { "error": "redelivery_rate_limited" } } }, "redelivery_backlogged": { "value": { "detail": { "error": "redelivery_backlogged" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/watch/pricing": { "get": { "tags": [ "TRONAgg Radar" ], "summary": "Get Energy pricing", "description": "What one Energy addition costs, per preset: `now_sun` is what an addition made now would cost you (this hour's rate, with your VIP price); `min_sun` and `max_sun` span today's hourly rates. Prices change by the hour, so read them when you need them rather than storing them. `activation_fee_sun` is the one-time activation an address that isn't activated yet adds to its first addition. `schedule_url` is the hourly price schedule in the workspace.", "operationId": "radar_get_pricing", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarPricingView" }, "example": { "presets": { "65k": { "now_sun": 1755000, "min_sun": 1560000, "max_sun": 2145000 }, "131k": { "now_sun": 3537000, "min_sun": 3144000, "max_sun": 4323000 } }, "activation_fee_sun": 1100000, "schedule_url": "/workspace/pricing" } } } }, "401": { "description": "The `X-API-Key` header is missing, invalid or revoked. `detail` is a plain string: `API key required`, `Invalid API key` or `User not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } }, "403": { "description": "`radar_access_required`: the account has neither a Google sign-in nor 1 TRX of net confirmed deposits; `required_deposit_sun` and `allowed_auth_methods` say what unlocks it. The API-wide refusals also apply: a blocked account (plain-string `detail`) and `ip_not_allowed`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RadarErrorResponse" }, { "$ref": "#/components/schemas/ApiPlainErrorResponse" } ] }, "examples": { "radar_access_required": { "value": { "detail": { "error": "radar_access_required", "message": "Sign in with Google, or make a deposit of at least 1 TRX, to use Radar", "required_deposit_sun": 1000000, "allowed_auth_methods": [ "google" ] } } } } } } }, "404": { "description": "`radar_disabled`. `radar_disabled`: TRONAgg Radar isn't available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RadarErrorResponse" }, "examples": { "radar_disabled": { "value": { "detail": { "error": "radar_disabled", "message": "Radar is not available" } } } } } } }, "429": { "description": "`Rate limit exceeded`: more than 1,000 requests per minute for your account (shared by all of its API keys and workspace sessions). `detail` is a plain string; wait the number of seconds in `Retry-After`, then retry.", "headers": { "Retry-After": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlainErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "AccountResponse": { "properties": { "balance_trx": { "type": "string", "title": "Balance Trx", "description": "Account balance in TRX" }, "deposit_address": { "type": "string", "title": "Deposit Address", "description": "TRON address to send TRX deposits to" }, "wallet_address": { "type": "string", "title": "Wallet Address", "description": "Your linked TRON login wallet address; an empty string if no wallet is linked. Not a deposit target — send TRX to `deposit_address`." } }, "type": "object", "required": [ "balance_trx", "deposit_address", "wallet_address" ], "title": "AccountResponse", "description": "Account info: balance, deposit address, and wallet address." }, "EstimateResponse": { "properties": { "duration": { "type": "string", "title": "Duration", "description": "Rental duration — always `1h`." }, "unit_price_sun": { "type": "string", "title": "Unit Price Sun", "description": "Price per Energy unit in SUN, as a decimal string (e.g. `\"27.000000\"`). It can be fractional — parse it with a decimal type, not as an integer." }, "total_price_sun": { "type": "integer", "title": "Total Price Sun", "description": "Total your balance would be charged, in SUN — includes `activation_fee_sun`." }, "total_price_trx": { "type": "string", "title": "Total Price Trx", "description": "The same total in TRX (decimal string)." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time account-activation fee in SUN, included in the totals. Non-zero only when you pass a `receiver_address` that is not yet activated on TRON." }, "activation_fee_trx": { "type": "string", "title": "Activation Fee Trx", "description": "The activation fee in TRX (decimal string); `\"0\"` when there is none." }, "min_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Amount", "description": "Smallest `resource_amount` `POST /buy` accepts; `null` = no lower bound. Outside the bounds `POST /buy` returns `400`." }, "max_amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Amount", "description": "Largest `resource_amount` `POST /buy` accepts; `null` = no upper bound. Outside the bounds `POST /buy` returns `400`." }, "energy_pass_energy": { "type": "integer", "title": "Energy Pass Energy", "description": "Energy units your Energy Pass would cover right now; the totals are what your balance pays for the rest. `0` without an active Energy Pass." } }, "type": "object", "required": [ "duration", "unit_price_sun", "total_price_sun", "total_price_trx", "activation_fee_sun", "activation_fee_trx", "min_amount", "max_amount", "energy_pass_energy" ], "title": "EstimateResponse", "description": "Price quote for `resource_amount` Energy delivered for 1 hour." }, "BuyRequest": { "properties": { "receiver_address": { "type": "string", "title": "Receiver Address", "description": "TRON address that will receive the Energy delegation (base58, starts with `T`, 34 characters). Checked before anything is charged." }, "resource_amount": { "type": "integer", "exclusiveMinimum": 0, "title": "Resource Amount", "description": "Amount of Energy to buy, within `min_amount` / `max_amount` from `GET /estimate`." } }, "type": "object", "required": [ "receiver_address", "resource_amount" ], "title": "BuyRequest", "description": "Request body for buying energy via the programmatic API." }, "BuyResponse": { "properties": { "order_id": { "type": "string", "format": "uuid", "title": "Order Id", "description": "Order UUID — pass it to `GET /order/{order_id}`." }, "status": { "type": "string", "title": "Status", "description": "Order status — `PENDING` for a newly placed order." }, "total_price_sun": { "type": "integer", "title": "Total Price Sun", "description": "Total deducted from your balance, in SUN — includes `activation_fee_sun`." }, "total_price_trx": { "type": "string", "title": "Total Price Trx", "description": "Total deducted from your balance, in TRX (decimal string)." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time account-activation fee in SUN, included in the total. Non-zero only when the receiver was not yet activated on TRON." }, "balance_after_sun": { "type": "integer", "title": "Balance After Sun", "description": "Account balance after purchase in SUN" }, "energy_pass_energy": { "type": "integer", "title": "Energy Pass Energy", "description": "Energy units of this order paid by your Energy Pass; `total_price_sun` covers the rest. If the order fails, these units return to your Energy Pass allowance rather than to your balance. `0` without an Energy Pass." } }, "type": "object", "required": [ "order_id", "status", "total_price_sun", "total_price_trx", "balance_after_sun", "activation_fee_sun", "energy_pass_energy" ], "title": "BuyResponse", "description": "Response after creating a purchase." }, "ApiOrderResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Order UUID." }, "status": { "type": "string", "title": "Status", "description": "Order status, upper-case: `PENDING`, `COMPLETED` or `FAILED` for orders placed through the API; orders paid directly from a wallet may also show `AWAITING_PAYMENT` or `PROCESSING`." }, "resource_type": { "type": "string", "title": "Resource Type", "description": "Always `ENERGY`." }, "resource_amount": { "type": "integer", "title": "Resource Amount" }, "duration_sec": { "type": "integer", "title": "Duration Sec", "description": "Delegation duration in seconds (`3600` = 1 hour)." }, "total_price_sun": { "type": "integer", "title": "Total Price Sun", "description": "Total charged in SUN, including `activation_fee_sun`." }, "total_price_trx": { "type": "string", "title": "Total Price Trx", "description": "Total charged in TRX (decimal string)." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time account-activation fee in SUN included in the total; `0` when the receiver was already activated." }, "receiver_address": { "type": "string", "title": "Receiver Address", "description": "Address the Energy is delegated to." }, "provider_name": { "type": "string", "title": "Provider Name", "description": "Always `TRONAgg`. Kept for backward compatibility." }, "provider_slug": { "type": "string", "title": "Provider Slug", "description": "Always `tronagg`. Kept for backward compatibility." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Why the order failed — set only when `status` is `FAILED`." }, "delegation_txids": { "items": { "type": "string" }, "type": "array", "title": "Delegation Txids", "description": "On-chain delegation transaction IDs. Usually filled once the order is `COMPLETED`, but may be empty for some deliveries." } }, "type": "object", "required": [ "id", "status", "resource_type", "resource_amount", "duration_sec", "total_price_sun", "total_price_trx", "receiver_address", "provider_name", "provider_slug", "created_at", "completed_at", "error_message", "delegation_txids", "activation_fee_sun" ], "title": "ApiOrderResponse", "description": "Simplified order detail for the programmatic API." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError", "description": "Request validation failed: `detail` is an array of field errors." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "EstimateEnergyResponse": { "type": "object", "title": "EstimateEnergyResponse", "description": "Energy a TRC20 transfer will consume, plus its TRX burn cost.", "required": [ "from_address", "contract_address", "to_address", "energy_used", "fee" ], "properties": { "from_address": { "type": "string", "title": "From Address", "description": "Sender TRON address" }, "contract_address": { "type": "string", "title": "Contract Address", "description": "TRC20 contract address (USDT unless overridden)" }, "to_address": { "type": "string", "title": "To Address", "description": "Receiver TRON address" }, "energy_used": { "type": "integer", "title": "Energy Used", "description": "Exact energy units the transfer would consume" }, "fee": { "type": "number", "title": "Fee", "description": "TRX burned at the current network rate (energy_used x energy_fee / 1,000,000)" } } }, "ReferenceOrder": { "type": "object", "title": "ReferenceOrder", "description": "Our price for a standard reference order (e.g. one USDT transfer).", "properties": { "energy": { "type": "integer", "title": "Energy", "description": "Energy amount of the reference order." }, "usdt_transfers": { "type": "integer", "title": "Usdt Transfers", "description": "How many typical USDT transfers that Energy covers." }, "trx": { "type": "string", "title": "Trx", "description": "Cost at our current price, in TRX." }, "usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usd", "description": "Approximate cost in USD, or `null` when the TRX/USD rate is unavailable." } }, "required": [ "energy", "usdt_transfers", "trx" ] }, "CurrencyInfo": { "type": "object", "title": "CurrencyInfo", "description": "Currency conversion context for the USD figures.", "properties": { "trx_usd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trx Usd", "description": "Current TRX/USD rate, or `null` when unavailable." } } }, "EnergyPricing": { "type": "object", "title": "EnergyPricing", "description": "Our current Energy price and how it sits against the market average.", "properties": { "price_sun": { "type": "string", "title": "Price Sun", "description": "Our current price per Energy unit, in SUN (1 TRX = 1,000,000 SUN)." }, "market_avg_price_sun": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Market Avg Price Sun", "description": "Market average price per Energy unit, in SUN — an anonymous mean across the public providers we track, never an individual provider's price. `null` when no market data is available." }, "below_market_percent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Below Market Percent", "description": "How far below the market average our price sits, in percent. `null` whenever we are not below the market average." }, "market_provider_count": { "type": "integer", "title": "Market Provider Count", "description": "How many public providers we track for the market average. Providers without a current price are left out of the average itself." }, "reference_orders": { "type": "array", "title": "Reference Orders", "description": "Cost of the standard reference orders (65k Energy = 1 USDT transfer, 131k = 2) at our current price.", "items": { "$ref": "#/components/schemas/ReferenceOrder" } } }, "required": [ "price_sun", "market_provider_count", "reference_orders" ] }, "PricingResponse": { "type": "object", "title": "PricingResponse", "description": "Current public pricing snapshot.", "properties": { "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When our price was last updated (UTC)." }, "currency": { "$ref": "#/components/schemas/CurrencyInfo" }, "energy": { "$ref": "#/components/schemas/EnergyPricing" } }, "required": [ "updated_at", "currency", "energy" ] }, "PricingHistoryPoint": { "type": "object", "title": "PricingHistoryPoint", "description": "One bucket on the price history series.", "properties": { "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Bucket start (UTC)." }, "our_price_sun": { "type": "string", "title": "Our Price Sun", "description": "Our price per Energy unit in SUN — the last price recorded in this bucket." }, "market_avg_price_sun": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Market Avg Price Sun", "description": "Anonymous market average in SUN: the mean of each tracked public provider's last price recorded in this bucket. `null` when no market data was recorded." }, "trx_65k": { "type": "string", "title": "Trx 65K", "description": "Our price for a 65,000-Energy order (one USDT transfer) at `our_price_sun`, in TRX." } }, "required": [ "timestamp", "our_price_sun", "trx_65k" ] }, "PricingHistoryResponse": { "type": "object", "title": "PricingHistoryResponse", "description": "Our price vs the market average over time.", "properties": { "granularity": { "type": "string", "enum": [ "hourly", "daily" ], "title": "Granularity", "description": "Bucket size of the series: `hourly` (via `hours`) or `daily` (via `days`)." }, "duration": { "type": "string", "title": "Duration", "description": "Rental duration the series is priced at (currently always `1h`)." }, "history": { "type": "array", "title": "History", "description": "Series points, oldest first.", "items": { "$ref": "#/components/schemas/PricingHistoryPoint" } } }, "required": [ "granularity", "duration", "history" ] }, "AutoEnergyPlanInfo": { "type": "object", "title": "AutoEnergyPlanInfo", "description": "Pricing snapshot for a subscription's plan. Amounts are given in both SUN (int) and TRX (string).", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Plan name, e.g. `Basic`." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time activation fee, in SUN." }, "activation_fee_trx": { "type": "string", "title": "Activation Fee Trx", "description": "One-time activation fee, in TRX." }, "daily_sub_sun": { "type": "integer", "title": "Daily Sub Sun", "description": "Daily subscription fee, in SUN. Charged every 24h, first 24h after activation." }, "daily_sub_trx": { "type": "string", "title": "Daily Sub Trx", "description": "Daily subscription fee, in TRX. Charged every 24h, first 24h after activation." }, "unit_price_65k_sun": { "type": "integer", "title": "Unit Price 65K Sun", "description": "Per 65k-Energy transfer, in SUN." }, "unit_price_65k_trx": { "type": "string", "title": "Unit Price 65K Trx", "description": "Per 65k-Energy transfer, in TRX." }, "unit_price_131k_sun": { "type": "integer", "title": "Unit Price 131K Sun", "description": "Per 131k-Energy transfer, in SUN." }, "unit_price_131k_trx": { "type": "string", "title": "Unit Price 131K Trx", "description": "Per 131k-Energy transfer, in TRX." }, "min_daily_tx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Daily Tx", "description": "Minimum transfers per 24-hour billing cycle; fewer triggers the minimum-usage fee. Null when the plan has no minimum." }, "penalty_sun": { "type": "integer", "title": "Penalty Sun", "description": "Minimum-usage fee, in SUN, charged once per completed 24h cycle with fewer than `min_daily_tx` transfers (0 when none)." }, "penalty_trx": { "type": "string", "title": "Penalty Trx", "description": "Minimum-usage fee, in TRX, charged once per completed 24h cycle with fewer than `min_daily_tx` transfers (`\"0\"` when none)." } }, "required": [ "id", "name", "activation_fee_sun", "activation_fee_trx", "daily_sub_sun", "daily_sub_trx", "unit_price_65k_sun", "unit_price_65k_trx", "unit_price_131k_sun", "unit_price_131k_trx", "min_daily_tx", "penalty_sun", "penalty_trx" ] }, "AutoEnergySubscriptionResponse": { "type": "object", "title": "AutoEnergySubscriptionResponse", "description": "A subscription's status, counters, settings, and plan pricing.", "properties": { "address": { "type": "string", "title": "Address", "description": "The subscribed TRON address." }, "status": { "type": "string", "enum": [ "pending_activation", "active", "closed" ], "title": "Status", "description": "Lifecycle status: `active` or `closed`. `pending_activation` is reserved and not returned by these endpoints." }, "plan": { "$ref": "#/components/schemas/AutoEnergyPlanInfo" }, "tx_used_total": { "type": "integer", "title": "Tx Used Total", "description": "Transfers counted so far, including any whose charge could not be collected (reset on reactivate). Can slightly exceed `quota_max_tx`." }, "quota_max_tx": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Quota Max Tx", "description": "Transfer cap, or `null` for none. The subscription closes once `tx_used_total` reaches it; transfers already in progress are still billed, so the final count can slightly exceed the cap." }, "expire_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expire At", "description": "Auto-close time, or `null`." }, "idle_hours": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Idle Hours", "description": "Idle auto-close window in hours (24–72), or `null` when idle auto-close is off." }, "net_protect": { "type": "boolean", "title": "Net Protect", "description": "Read-only. Whether the address is also kept covered so transfers don't burn TRX for Bandwidth. On for the Basic plan; not settable via this API." }, "last_activity_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Activity At", "description": "Last covered transfer (or the activation, if none since); the idle window counts from here." }, "activated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Activated At", "description": "When it became active." }, "closed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Closed At", "description": "When it closed." }, "close_reason": { "anyOf": [ { "type": "string", "enum": [ "quota", "expired", "idle", "insufficient_balance", "reseller_insolvent", "manual" ] }, { "type": "null" } ], "title": "Close Reason", "description": "Why it closed, if closed: `quota` (transfer cap reached), `expired` (`expire_at` passed), `idle` (no transfers for `idle_hours`), `insufficient_balance` (a charge couldn't be paid or the balance fell below one daily fee + one 131k transfer), `reseller_insolvent` (the service for your account was stopped), `manual` (you closed it). New values may be added — accept unknown ones." } }, "required": [ "address", "status", "plan", "tx_used_total", "quota_max_tx", "expire_at", "idle_hours", "net_protect", "last_activity_at", "activated_at", "closed_at", "close_reason" ] }, "AutoEnergySubscribeRequest": { "type": "object", "title": "AutoEnergySubscribeRequest", "description": "Request to create and activate a subscription on an address.", "properties": { "address": { "type": "string", "title": "Address", "description": "The TRON address to keep Energy-ready." }, "idle_hours": { "type": "integer", "default": 24, "title": "Idle Hours", "description": "Idle auto-close window in hours, any integer from 24 to 72: the subscription closes (`idle`) after this long with no covered transfer.", "minimum": 24, "maximum": 72 }, "quota_max_tx": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "default": null, "title": "Quota Max Tx", "description": "Auto-close once this many transfers are counted. `null` for no cap. Transfers already in progress are still billed, so the final count can slightly exceed it." }, "expire_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "default": null, "title": "Expire At", "description": "Auto-close at this time. Must be in the future." } }, "required": [ "address" ] }, "AutoEnergyUpdateSettingsRequest": { "type": "object", "title": "AutoEnergyUpdateSettingsRequest", "description": "Partial settings update. Only provided fields are applied; an omitted field is left unchanged. An explicit `null` removes the cap or expiry, or turns off idle auto-close.", "properties": { "idle_hours": { "anyOf": [ { "type": "integer", "minimum": 24, "maximum": 72 }, { "type": "null" } ], "default": null, "title": "Idle Hours", "description": "Idle auto-close window in hours, any integer from 24 to 72. `null` turns idle auto-close off." }, "quota_max_tx": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "default": null, "title": "Quota Max Tx", "description": "Transfer cap. `null` removes the cap." }, "expire_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "default": null, "title": "Expire At", "description": "Auto-close time. `null` removes the expiry." } } }, "AutoEnergyUsageItem": { "type": "object", "title": "AutoEnergyUsageItem", "description": "A single usage event (one covered transfer).", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "units": { "type": "integer", "title": "Units", "description": "Billing units: 1 = 65k class, 2 = 131k class." }, "energy_class": { "type": "string", "enum": [ "65k", "131k" ], "title": "Energy Class", "description": "Energy class billed for the transfer." }, "used_energy": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Used Energy", "description": "Energy consumed, if known." }, "used_tx_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Used Tx Id", "description": "On-chain transaction id (may be `null` on older events)." }, "billed_sun": { "type": "integer", "title": "Billed Sun", "description": "Amount billed for this event, in SUN. 0 when the charge could not be collected (the subscription is then closed)." }, "billed_trx": { "type": "string", "title": "Billed Trx", "description": "Amount billed for this event, in TRX. `\"0\"` when the charge could not be collected." }, "occurred_at": { "type": "string", "format": "date-time", "title": "Occurred At", "description": "When the event occurred." } }, "required": [ "id", "units", "energy_class", "used_energy", "used_tx_id", "billed_sun", "billed_trx", "occurred_at" ] }, "AutoEnergyBillingItem": { "type": "object", "title": "AutoEnergyBillingItem", "description": "One AutoEnergy charge — activation, daily subscription, minimum-usage fee, or per-transfer.", "properties": { "kind": { "type": "string", "title": "Kind", "description": "Ledger entry type: `autoenergy_activate` (activation), `autoenergy_daily` (daily subscription), `autoenergy_unit` (per-transfer), or `autoenergy_penalty` (minimum-usage fee)." }, "amount_sun": { "type": "integer", "title": "Amount Sun", "description": "Positive magnitude charged, in SUN." }, "amount_trx": { "type": "string", "title": "Amount Trx", "description": "Positive magnitude charged, in TRX." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable line." }, "used_tx_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Used Tx Id", "description": "Linked on-chain tx id, for per-transfer charges." }, "at": { "type": "string", "format": "date-time", "title": "At", "description": "When the charge was posted." } }, "required": [ "kind", "amount_sun", "amount_trx", "description", "used_tx_id", "at" ] }, "AutoEnergyErrorResponse": { "type": "object", "title": "AutoEnergyErrorResponse", "description": "Structured error body. `detail.error` is a stable machine-readable slug.", "properties": { "detail": { "type": "object", "title": "Detail", "properties": { "error": { "type": "string", "title": "Error", "description": "Machine-readable error slug." }, "message": { "type": "string", "title": "Message", "description": "Human-readable explanation." } }, "required": [ "error", "message" ] } }, "required": [ "detail" ] }, "ApiOrderListItem": { "type": "object", "title": "ApiOrderListItem", "description": "Order list item for the programmatic API.", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "type": "string", "title": "Status", "description": "Order status, upper-case: `PENDING`, `COMPLETED` or `FAILED` for orders placed through the API; orders paid directly from a wallet may also show `AWAITING_PAYMENT` or `PROCESSING`." }, "resource_type": { "type": "string", "title": "Resource Type" }, "resource_amount": { "type": "integer", "title": "Resource Amount" }, "duration_sec": { "type": "integer", "title": "Duration Sec" }, "total_price_sun": { "type": "integer", "title": "Total Price Sun" }, "total_price_trx": { "type": "string", "title": "Total Price Trx" }, "activation_fee_sun": { "type": "integer", "default": 0, "title": "Activation Fee Sun", "description": "One-time account-activation fee in SUN included in the total; `0` when the receiver was already activated." }, "receiver_address": { "type": "string", "title": "Receiver Address" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "delegation_txids": { "items": { "type": "string" }, "type": "array", "title": "Delegation Txids", "description": "On-chain delegation transaction IDs. Usually filled once the order is `COMPLETED`, but may be empty for some deliveries." } }, "required": [ "id", "status", "resource_type", "resource_amount", "duration_sec", "total_price_sun", "total_price_trx", "receiver_address", "created_at", "completed_at", "delegation_txids", "activation_fee_sun" ] }, "ApiOrderListResponse": { "type": "object", "title": "ApiOrderListResponse", "description": "Page of the caller's orders, newest first.", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/ApiOrderListItem" }, "title": "Orders" }, "total": { "type": "integer", "title": "Total", "description": "Total orders matching the filter across all pages." }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "required": [ "orders", "total", "page", "page_size" ] }, "ApiTransactionItem": { "type": "object", "title": "ApiTransactionItem", "description": "Single balance-ledger entry for the programmatic API.", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "entry_type": { "type": "string", "title": "Entry Type", "description": "Ledger entry type (see the `entry_type` filter for the full list)." }, "amount_sun": { "type": "integer", "title": "Amount Sun", "description": "Signed amount in SUN (negative for debits)." }, "amount_trx": { "type": "string", "title": "Amount Trx", "description": "Signed amount in TRX." }, "balance_after_sun": { "type": "integer", "title": "Balance After Sun", "description": "Account balance in SUN immediately after this entry." }, "reference_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference Id", "description": "Related order/subscription id when applicable; may be an arbitrary marker string." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "required": [ "id", "entry_type", "amount_sun", "amount_trx", "balance_after_sun", "reference_id", "description", "created_at" ] }, "ApiTransactionListResponse": { "type": "object", "title": "ApiTransactionListResponse", "description": "Cursor-paginated ledger page (newest first).", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTransactionItem" }, "title": "Transactions" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether more entries are available past this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page; `null` when there are no more entries." } }, "required": [ "transactions", "has_more", "next_cursor" ] }, "ApiDepositItem": { "type": "object", "title": "ApiDepositItem", "description": "Single incoming TRX deposit.", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "from_address": { "type": "string", "title": "From Address" }, "amount_sun": { "type": "integer", "title": "Amount Sun" }, "amount_trx": { "type": "string", "title": "Amount Trx" }, "status": { "type": "string", "title": "Status", "description": "`confirmed` — credited to your balance; `failed` — the transaction was dropped from the chain after it was credited, and the amount was debited back (`deposit_reversal` ledger entry)." }, "credited_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Credited At", "description": "When the deposit was credited to your balance (spendable from then on). Stays set on a `failed` deposit." }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Verified At", "description": "Set once the deposit is re-checked on the solidified chain; `null` while the fast credit is still awaiting verification, and on a `failed` deposit." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "required": [ "id", "tx_hash", "from_address", "amount_sun", "amount_trx", "status", "credited_at", "verified_at", "created_at" ] }, "ApiDepositListResponse": { "type": "object", "title": "ApiDepositListResponse", "description": "Offset-paginated deposit history (newest first).", "properties": { "deposits": { "type": "array", "items": { "$ref": "#/components/schemas/ApiDepositItem" }, "title": "Deposits" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether more deposits are available past this page." } }, "required": [ "deposits", "has_more" ] }, "NotificationSubscriptionResponse": { "type": "object", "title": "NotificationSubscriptionResponse", "properties": { "event_type": { "type": "string", "title": "Event Type", "description": "Event name, e.g. `order.status_changed`. See [Webhook events](/api-reference/webhook-events)." }, "audience": { "type": "string", "enum": [ "customer", "reseller" ], "title": "Audience", "description": "`customer` for events about your own account; `reseller` for reseller events (reseller accounts only)." }, "enabled": { "type": "boolean", "title": "Enabled" }, "delivery_mode": { "type": "string", "enum": [ "immediate", "hourly_digest", "daily_digest" ], "title": "Delivery Mode", "description": "Currently always `immediate`." }, "settings": { "type": "object", "additionalProperties": true, "title": "Settings", "description": "Per-event settings: `threshold_sun` for `balance.low` (default `50000000`) and `reseller.balance.low` (default `500000000`); `hour` (0–23, default `9`) and `timezone` (default `UTC`) for the daily summaries. Empty for other events." } }, "required": [ "event_type", "audience", "enabled", "delivery_mode", "settings" ] }, "NotificationDestinationResponse": { "type": "object", "title": "NotificationDestinationResponse", "description": "A notification destination. Signing secrets are never included.", "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "channel_type": { "type": "string", "enum": [ "telegram", "webhook", "email" ], "title": "Channel Type", "description": "Always `webhook` on the `/webhooks` endpoints." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "status": { "type": "string", "title": "Status", "description": "`active` or `disabled`. Only `active` destinations receive events." }, "locale": { "type": "string", "title": "Locale" }, "config": { "type": "object", "additionalProperties": true, "title": "Config", "description": "Channel configuration. For a webhook: `url` (the URL deliveries are sent to, without a trailing `/`) and `format_version` (`v1`). Secrets are omitted." }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationSubscriptionResponse" }, "title": "Subscriptions", "description": "One entry per event and audience this webhook has a preference for, with whether it is enabled. Entries are created with the webhook's defaults when it is created; events added to TRONAgg later are absent (and disabled) until you enable them in **Workspace → Notifications**. See [Webhook events](/api-reference/webhook-events)." } }, "required": [ "id", "channel_type", "display_name", "status", "locale", "config", "subscriptions" ] }, "WebhookDestinationCreate": { "type": "object", "title": "WebhookDestinationCreate", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "title": "Name", "description": "A label for this webhook." }, "url": { "type": "string", "format": "uri", "title": "Url", "description": "HTTPS endpoint that will receive event deliveries. The host must resolve only to public IP addresses (not private, loopback, link-local, reserved or multicast); `localhost`, `*.local` and `tronagg.ai` hosts are rejected. This is checked again before every delivery and test. Redirects are not followed. A trailing `/` is removed: `https://example.com/hook/` is stored and called as `https://example.com/hook`. Each URL can be registered once per account; at most 10 webhooks per account." }, "locale": { "type": "string", "pattern": "^(en|zh)$", "default": "en", "title": "Locale", "description": "Stored with the destination. Webhook payloads are language-neutral JSON; this currently has no effect on webhook deliveries." } }, "required": [ "name", "url" ] }, "WebhookDestinationCreated": { "type": "object", "title": "WebhookDestinationCreated", "description": "Newly created webhook plus its signing secret (shown exactly once).", "properties": { "destination": { "$ref": "#/components/schemas/NotificationDestinationResponse" }, "signing_secret": { "type": "string", "title": "Signing Secret", "description": "Secret used to verify webhook signatures. Returned only in this response — store it now." } }, "required": [ "destination", "signing_secret" ] }, "ApiErrorResponse": { "type": "object", "title": "ApiErrorResponse", "description": "Structured error body. `detail.error` is a stable machine-readable slug; some codes add extra context fields next to it.", "properties": { "detail": { "type": "object", "title": "Detail", "properties": { "error": { "type": "string", "title": "Error", "description": "Machine-readable error slug." }, "message": { "type": "string", "title": "Message", "description": "Human-readable explanation. Present on most codes; a few omit it (see Errors & conventions)." } }, "required": [ "error" ] } }, "required": [ "detail" ] }, "AgentBusinessError": { "properties": { "detail": { "$ref": "#/components/schemas/AgentBusinessErrorDetail" } }, "type": "object", "required": [ "detail" ], "title": "AgentBusinessError", "description": "An Energy Agent refusal: `{\"detail\": {\"error\": \"\", ...extra fields}}`." }, "AgentBusinessErrorDetail": { "properties": { "error": { "type": "string", "title": "Error", "description": "Machine-readable error slug." } }, "additionalProperties": true, "type": "object", "required": [ "error" ], "title": "AgentBusinessErrorDetail", "description": "A stable `error` slug plus the slug's extra fields, if any. There is no\n`message` field." }, "AgentConfig": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "public_id": { "type": "string", "title": "Public Id" }, "mode": { "type": "string", "enum": [ "own", "generated" ], "title": "Mode" }, "address": { "type": "string", "title": "Address" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "energy_per_unit": { "type": "integer", "title": "Energy Per Unit" }, "base_payment_sun": { "type": "integer", "title": "Base Payment Sun" }, "max_units": { "type": "integer", "title": "Max Units" }, "status": { "type": "string", "enum": [ "active", "paused" ], "title": "Status" }, "pause_reason": { "anyOf": [ { "type": "string", "enum": [ "user", "insufficient_balance", "admin" ] }, { "type": "null" } ], "title": "Pause Reason", "description": "`user` (you paused it), `insufficient_balance` (set automatically when a sale failed for lack of balance; it lifts itself when a payment arrives while your balance is at or above `min_balance_sun`), `admin` (paused by support), or `null` when active." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "stats": { "$ref": "#/components/schemas/AgentConfigStats" } }, "type": "object", "required": [ "id", "public_id", "mode", "address", "title", "energy_per_unit", "base_payment_sun", "max_units", "status", "pause_reason", "created_at", "updated_at", "stats" ], "title": "AgentConfig" }, "AgentConfigCreate": { "properties": { "mode": { "type": "string", "enum": [ "own", "generated" ], "title": "Mode" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address", "description": "Your TRON address; required for `own`, omit (or `null`) for `generated`." }, "title": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Title", "description": "Trimmed; blank is stored as `null`." }, "energy_per_unit": { "type": "integer", "maximum": 1000000000.0, "title": "Energy Per Unit", "description": "At least `energy_min`, and `energy_per_unit × max_units` at most `energy_max` (`GET /agent/summary`)." }, "base_payment_sun": { "type": "integer", "maximum": 1000000000000000.0, "title": "Base Payment Sun", "description": "A multiple of 1,000 SUN and at least `cost_max_sun` from `GET /agent/quote?energy=`." }, "max_units": { "type": "integer", "maximum": 100000.0, "title": "Max Units", "description": "From 1 to `max_units_cap` (`GET /agent/summary`)." } }, "additionalProperties": false, "type": "object", "required": [ "mode", "energy_per_unit", "base_payment_sun", "max_units" ], "title": "AgentConfigCreate" }, "AgentConfigList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AgentConfig" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "AgentConfigList" }, "AgentConfigStats": { "properties": { "sales": { "type": "integer", "title": "Sales" }, "energy": { "type": "integer", "title": "Energy" }, "revenue_sun": { "type": "integer", "title": "Revenue Sun" }, "cost_sun": { "type": "integer", "title": "Cost Sun" }, "last_sale_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Sale At", "description": "When the latest sale's payment was detected." } }, "type": "object", "required": [ "sales", "energy", "revenue_sun", "cost_sun", "last_sale_at" ], "title": "AgentConfigStats", "description": "Sales of this configuration. A sale is a payment that placed an Energy order, excluding failed orders (their cost was refunded to your balance) and payments whose TRX transfer was later reversed on-chain; such a reversed payment can still show `completed` in `GET /agent/payments`. `revenue_sun` is the TRX customers sent, overpayments included. `cost_sun` is what your balance was charged; a slow-delivery compensation later refunded on a completed sale is not subtracted." }, "AgentConfigUpdate": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "title": "Title" }, "energy_per_unit": { "type": "integer", "maximum": 1000000000.0, "title": "Energy Per Unit" }, "base_payment_sun": { "type": "integer", "maximum": 1000000000000000.0, "title": "Base Payment Sun" }, "max_units": { "type": "integer", "maximum": 100000.0, "title": "Max Units" } }, "additionalProperties": false, "type": "object", "title": "AgentConfigUpdate", "description": "Partial update: an omitted key is unchanged and `\"title\": null` clears the title.\nThe numeric fields can't be null (422). Mode and address are immutable. New values\napply to payments received after the update." }, "AgentPayment": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "config_id": { "type": "string", "format": "uuid", "title": "Config Id" }, "tx_hash": { "type": "string", "title": "Tx Hash" }, "payer": { "type": "string", "title": "Payer", "description": "The address that sent the TRX; it receives the Energy." }, "amount_sun": { "type": "integer", "title": "Amount Sun", "description": "What the customer sent." }, "units": { "type": "integer", "title": "Units", "description": "Whole units this payment buys: `amount_sun // base_payment_sun`, at most `max_units`. Fixed when the payment is detected, from the configuration as it was then (later edits don't change it); Energy is delivered only when `status` is `delivering` or `completed`." }, "energy": { "type": "integer", "title": "Energy", "description": "`units × energy_per_unit`. Fixed when the payment is detected, from the configuration as it was then (later edits don't change it); Energy is delivered only when `status` is `delivering` or `completed`." }, "cost_sun": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Cost Sun", "description": "What your balance was charged for the order; `null` unless an order was placed." }, "status": { "type": "string", "enum": [ "processing", "delivering", "completed", "failed", "skipped" ], "title": "Status", "description": "`failed`: the order failed and its cost was refunded to your balance; the customer's TRX is not returned automatically. `skipped`: no Energy was ordered." }, "skip_reason": { "anyOf": [ { "type": "string", "enum": [ "below_base", "price_above_payment", "self_transfer", "insufficient_balance", "config_paused", "program_disabled", "order_rejected" ] }, { "type": "null" } ], "title": "Skip Reason", "description": "Why a `skipped` payment delivered nothing. `null` on a skipped payment whose TRX transfer was reversed on-chain before Energy was ordered. Treat the list as open: new reasons may be added." }, "order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Order Id", "description": "The Energy order placed for this payment; `null` unless one was placed." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the payment was detected." } }, "type": "object", "required": [ "id", "config_id", "tx_hash", "payer", "amount_sun", "units", "energy", "cost_sun", "status", "skip_reason", "order_id", "created_at" ], "title": "AgentPayment" }, "AgentPaymentPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/AgentPayment" }, "type": "array", "title": "Items" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "items", "page", "page_size", "has_more" ], "title": "AgentPaymentPage" }, "AgentQuote": { "properties": { "energy": { "type": "integer", "title": "Energy" }, "cost_now_sun": { "type": "integer", "title": "Cost Now Sun" }, "cost_min_sun": { "type": "integer", "title": "Cost Min Sun" }, "cost_max_sun": { "type": "integer", "title": "Cost Max Sun" }, "timezone": { "type": "string", "title": "Timezone" } }, "type": "object", "required": [ "energy", "cost_now_sun", "cost_min_sun", "cost_max_sun", "timezone" ], "title": "AgentQuote", "description": "What `energy` costs the agent. `cost_now_sun`: the charge right now (your price,\nVIP discount included, rounded exactly like the purchase). `cost_min_sun` /\n`cost_max_sun`: the lowest / highest **retail** charge (no VIP discount) over the\npublished weekly schedule and the current rate, so with a VIP discount `cost_now_sun`\ncan be below `cost_min_sun`." }, "AgentSummary": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the program accepts new and resumed configurations." }, "min_balance_sun": { "type": "integer", "title": "Min Balance Sun", "description": "Activation threshold: the balance needed to create or resume a configuration." }, "balance_sun": { "type": "integer", "title": "Balance Sun" }, "can_activate": { "type": "boolean", "title": "Can Activate", "description": "`enabled` and `balance_sun` ≥ `min_balance_sun`." }, "max_configs": { "type": "integer", "title": "Max Configs" }, "max_generated": { "type": "integer", "title": "Max Generated" }, "max_units_cap": { "type": "integer", "title": "Max Units Cap", "description": "The highest allowed `max_units`." }, "energy_min": { "type": "integer", "title": "Energy Min", "description": "The minimum `energy_per_unit`." }, "energy_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Energy Max", "description": "The maximum Energy one payment can buy (`energy_per_unit × max_units`); `null` = no limit." }, "quote_65k": { "$ref": "#/components/schemas/AgentQuote", "description": "The price of 65,000 Energy, same shape as `GET /agent/quote`." }, "totals": { "$ref": "#/components/schemas/AgentTotals" } }, "type": "object", "required": [ "enabled", "min_balance_sun", "balance_sun", "can_activate", "max_configs", "max_generated", "max_units_cap", "energy_min", "energy_max", "quote_65k", "totals" ], "title": "AgentSummary" }, "AgentTotals": { "properties": { "sales": { "type": "integer", "title": "Sales" }, "energy": { "type": "integer", "title": "Energy" }, "revenue_sun": { "type": "integer", "title": "Revenue Sun" }, "cost_sun": { "type": "integer", "title": "Cost Sun" } }, "type": "object", "required": [ "sales", "energy", "revenue_sun", "cost_sun" ], "title": "AgentTotals", "description": "Lifetime sales. A sale is a payment that placed an Energy order, excluding failed orders (their cost was refunded to your balance) and payments whose TRX transfer was later reversed on-chain; such a reversed payment can still show `completed` in `GET /agent/payments`. `revenue_sun` is the TRX customers sent, overpayments included. `cost_sun` is what your balance was charged; a slow-delivery compensation later refunded on a completed sale is not subtracted." }, "PublicPayConfig": { "properties": { "public_id": { "type": "string", "title": "Public Id" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "address": { "type": "string", "title": "Address" }, "energy_per_unit": { "type": "integer", "title": "Energy Per Unit" }, "base_payment_sun": { "type": "integer", "title": "Base Payment Sun" }, "max_units": { "type": "integer", "title": "Max Units" }, "available": { "type": "boolean", "title": "Available" }, "referral_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Referral Code" } }, "type": "object", "required": [ "public_id", "title", "address", "energy_per_unit", "base_payment_sun", "max_units", "available", "referral_code" ], "title": "PublicPayConfig", "description": "What a customer needs to pay an agent. No owner identity beyond the agent's\nown referral code (null when they have none)." }, "ApiPlainErrorResponse": { "type": "object", "title": "ApiPlainErrorResponse", "description": "Error body whose `detail` is a plain human-readable string.", "properties": { "detail": { "type": "string", "title": "Detail" } }, "required": [ "detail" ] }, "ApiInsufficientBalanceError": { "type": "object", "title": "ApiInsufficientBalanceError", "description": "`insufficient_balance` on `POST /buy`. This body has no `message`.", "properties": { "detail": { "type": "object", "title": "Detail", "properties": { "error": { "type": "string", "enum": [ "insufficient_balance" ], "title": "Error" }, "current_balance": { "type": "integer", "title": "Current Balance", "description": "Your balance in SUN." }, "required_amount": { "type": "integer", "title": "Required Amount", "description": "The order total in SUN (including any activation fee)." } }, "required": [ "error", "current_balance", "required_amount" ] } }, "required": [ "detail" ] }, "ApiOrderAmountLimitError": { "type": "object", "title": "ApiOrderAmountLimitError", "description": "`resource_amount` outside the order limits. Keyed by `code`, not `error`.", "properties": { "detail": { "type": "object", "title": "Detail", "properties": { "code": { "type": "string", "enum": [ "order_amount_below_minimum", "order_amount_above_maximum" ], "title": "Code" }, "message": { "type": "string", "title": "Message" }, "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min", "description": "Smallest accepted amount; `null` = no lower bound." }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max", "description": "Largest accepted amount; `null` = no upper bound." } }, "required": [ "code", "message", "min", "max" ] } }, "required": [ "detail" ] }, "RadarAccessView": { "properties": { "granted": { "type": "boolean", "title": "Granted", "description": "Whether this account can use Radar." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why not: `radar_disabled`, `account_disabled` or `radar_access_required` (sign in with Google or deposit 1 TRX). `null` when granted." } }, "type": "object", "required": [ "granted", "reason" ], "title": "RadarAccessView" }, "RadarActionView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The decision's id: `action_id` in Energy webhooks." }, "kind": { "type": "string", "title": "Kind", "description": "`auto` (the scenario) or `manual` (Add Energy).", "enum": [ "auto", "manual" ] }, "status": { "type": "string", "title": "Status", "description": "`reserved`, `ordered`, `delivered`, `blocked` (waits for its cause to clear), `deferred` (waits for working hours), `skipped` or `failed`.", "enum": [ "reserved", "ordered", "delivered", "blocked", "deferred", "skipped", "failed" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why it was blocked, deferred, skipped or failed; `null` otherwise." }, "energy_ordered": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Energy Ordered", "description": "Energy ordered." }, "total_price_sun": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Price Sun", "description": "What it cost or will cost (SUN)." }, "delegation_txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delegation Txid", "description": "The delegation transaction, once delivered." }, "ready_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Ready At", "description": "When the Energy arrived." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "When the Energy expires: one hour after it arrived." }, "saved_sun": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Saved Sun", "description": "Estimated TRX the sweep didn't burn (SUN), once a sweep used this Energy." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When Radar made the decision." } }, "type": "object", "required": [ "id", "kind", "status", "reason", "energy_ordered", "total_price_sun", "delegation_txid", "ready_at", "expires_at", "saved_sun", "created_at" ], "title": "RadarActionView", "description": "One Energy decision of Radar for an address.", "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a60", "kind": "auto", "status": "delivered", "reason": null, "energy_ordered": 65000, "total_price_sun": 1755000, "delegation_txid": "a91853964b278f64a91853964b278f64a91853964b278f64a91853964b278f64", "ready_at": "2026-10-04T18:05:15Z", "expires_at": "2026-10-04T19:05:15Z", "saved_sun": null, "created_at": "2026-10-04T18:04:58Z" } }, "RadarAddItem": { "properties": { "address": { "type": "string", "maxLength": 1024, "title": "Address", "description": "TRON address, Base58Check (`T…`)." }, "label": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Label", "description": "Up to 80 printable characters. Applies to new addresses only." }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "External Id", "description": "Your own reference, up to 128 printable characters, unique among your watched addresses. Applies to new addresses only." } }, "additionalProperties": false, "type": "object", "required": [ "address" ], "title": "RadarAddItem" }, "RadarAddRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RadarAddItem" }, "type": "array", "title": "Items", "description": "1 to 1,000 addresses." }, "scenario_id": { "type": "string", "format": "uuid", "title": "Scenario Id", "description": "The scenario they join." }, "existing": { "type": "string", "title": "Existing", "default": "skip", "description": "What to do with addresses already watched in another scenario: `skip` (leave them) or `move` (move them here).", "enum": [ "skip", "move" ] } }, "additionalProperties": false, "type": "object", "required": [ "items", "scenario_id" ], "title": "RadarAddRequest" }, "RadarAddResult": { "properties": { "results": { "items": { "$ref": "#/components/schemas/RadarItemResult" }, "type": "array", "title": "Results" }, "summary": { "$ref": "#/components/schemas/RadarAddSummary" } }, "type": "object", "required": [ "results", "summary" ], "title": "RadarAddResult" }, "RadarAddSummary": { "properties": { "created": { "type": "integer", "title": "Created" }, "exists": { "type": "integer", "title": "Exists" }, "moved": { "type": "integer", "title": "Moved" }, "duplicate": { "type": "integer", "title": "Duplicate" }, "invalid": { "type": "integer", "title": "Invalid" }, "limit_exceeded": { "type": "integer", "title": "Limit Exceeded" } }, "type": "object", "required": [ "created", "exists", "moved", "duplicate", "invalid", "limit_exceeded" ], "title": "RadarAddSummary" }, "RadarAddressPage": { "properties": { "addresses": { "items": { "$ref": "#/components/schemas/RadarAddressView" }, "type": "array", "title": "Addresses" }, "has_more": { "type": "boolean", "title": "Has More", "description": "More addresses follow." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Send as `cursor` for the next page; `null` on the last page." }, "total": { "type": "integer", "title": "Total", "description": "Addresses matching the filters." } }, "type": "object", "required": [ "addresses", "has_more", "next_cursor", "total" ], "title": "RadarAddressPage" }, "RadarAddressUpdate": { "properties": { "label": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Label", "description": "Up to 80 printable characters; `null` clears it." }, "external_id": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "External Id", "description": "Up to 128 printable characters, unique among your watched addresses; `null` clears it." }, "scenario_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Scenario Id", "description": "Move the address to this scenario." }, "status": { "anyOf": [ { "type": "string", "enum": [ "active", "energy_paused" ] }, { "type": "null" } ], "title": "Status", "description": "`energy_paused` stops Energy purchases (alerts keep working); `active` resumes them." } }, "additionalProperties": false, "type": "object", "title": "RadarAddressUpdate", "description": "Fields sent are changed; an explicit null clears `label` / `external_id`." }, "RadarAddressView": { "properties": { "address": { "type": "string", "title": "Address", "description": "The address, Base58Check." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Your label; `null` without one." }, "display_name": { "type": "string", "title": "Display Name", "description": "The label, or the shortened address." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "Your own reference; `null` without one." }, "scenario": { "$ref": "#/components/schemas/RadarScenarioRef" }, "status": { "type": "string", "title": "Status", "description": "`active`, or `energy_paused` when you paused Energy.", "enum": [ "active", "energy_paused" ] }, "readiness": { "$ref": "#/components/schemas/RadarReadinessView" }, "balances": { "$ref": "#/components/schemas/RadarBalances" }, "episode": { "anyOf": [ { "$ref": "#/components/schemas/RadarEpisodeView" }, { "type": "null" } ], "description": "The deposit waiting to be swept (`add_on_deposit`), or `null`." }, "last_event": { "anyOf": [ { "$ref": "#/components/schemas/RadarLastEvent" }, { "type": "null" } ], "description": "The address's latest event, or `null`." }, "attention": { "items": { "$ref": "#/components/schemas/RadarAttentionItem" }, "type": "array", "title": "Attention", "description": "Unreviewed security alerts and current problems." }, "additions_today": { "type": "integer", "title": "Additions Today", "description": "Automatic Energy additions since 00:00 UTC: what `times_per_address_day` limits." }, "activated": { "type": "boolean", "title": "Activated", "description": "Whether the account exists on the chain." }, "usdt_frozen": { "type": "boolean", "title": "Usdt Frozen", "description": "Whether the issuer froze its USDT." }, "energy_in_flight": { "type": "boolean", "title": "Energy In Flight", "description": "An Energy addition for this address is on its way." } }, "type": "object", "required": [ "address", "label", "display_name", "external_id", "scenario", "status", "readiness", "balances", "episode", "last_event", "attention", "additions_today", "activated", "usdt_frozen", "energy_in_flight" ], "title": "RadarAddressView", "description": "A watched address.", "example": { "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "label": "deposit-0042", "display_name": "deposit-0042", "external_id": "invoice-4821", "scenario": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit" }, "status": "active", "readiness": { "state": "ready", "energy_available": 65000, "energy_target": 65000, "energy_required": 64285, "deficit": 0, "stale": false, "updated_at": "2026-10-04T18:05:16Z", "energy_expires_at": "2026-10-04T19:05:15Z" }, "balances": { "usdt": "1250.000000", "trx_sun": 0 }, "episode": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5e", "opened_at": "2026-10-04T18:04:57Z", "balance": "1250.000000", "waiting_seconds": 21, "blocker": null }, "last_event": { "kind": "address.sweep.ready", "at": "2026-10-04T18:05:18Z", "summary": "Sweep ready", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e" }, "attention": [], "additions_today": 1, "activated": true, "usdt_frozen": false, "energy_in_flight": false } }, "RadarAttentionItem": { "properties": { "event_id": { "type": "integer", "title": "Event Id", "description": "The event's id: send it to `POST /addresses/{address}/reviews` once handled." }, "kind": { "type": "string", "title": "Kind", "description": "The event type: a security alert or a problem." }, "at": { "type": "string", "format": "date-time", "title": "At", "description": "When Radar recorded it." }, "data": { "additionalProperties": true, "type": "object", "title": "Data", "description": "The event's webhook `data`." } }, "type": "object", "required": [ "event_id", "kind", "at", "data" ], "title": "RadarAttentionItem" }, "RadarBalances": { "properties": { "usdt": { "type": "string", "title": "Usdt", "description": "USDT balance, six-decimal string." }, "trx_sun": { "type": "integer", "title": "Trx Sun", "description": "TRX balance in SUN." } }, "type": "object", "required": [ "usdt", "trx_sun" ], "title": "RadarBalances" }, "RadarBulkRequest": { "properties": { "op": { "type": "string", "title": "Op", "description": "`move`, `pause_energy`, `resume` or `remove`.", "enum": [ "move", "pause_energy", "resume", "remove" ] }, "addresses": { "items": { "type": "string" }, "type": "array", "title": "Addresses", "description": "1 to 1,000 watched addresses." }, "scenario_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Scenario Id", "description": "Target scenario; required for `move`." } }, "additionalProperties": false, "type": "object", "required": [ "op", "addresses" ], "title": "RadarBulkRequest" }, "RadarBulkResult": { "properties": { "results": { "items": { "$ref": "#/components/schemas/RadarItemResult" }, "type": "array", "title": "Results" }, "summary": { "$ref": "#/components/schemas/RadarBulkSummary" } }, "type": "object", "required": [ "results", "summary" ], "title": "RadarBulkResult" }, "RadarBulkSummary": { "properties": { "ok": { "type": "integer", "title": "Ok", "description": "Items that succeeded." }, "failed": { "type": "integer", "title": "Failed", "description": "Items that didn't." } }, "type": "object", "required": [ "ok", "failed" ], "title": "RadarBulkSummary" }, "RadarCheckItem": { "properties": { "address": { "type": "string", "title": "Address", "description": "The address as you sent it." }, "status": { "type": "string", "enum": [ "new", "exists", "invalid" ], "title": "Status", "description": "`new`, `exists` (already watched) or `invalid`." }, "scenario_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Scenario Id", "description": "The scenario of an address that `exists`; otherwise `null`." } }, "type": "object", "required": [ "address", "status", "scenario_id" ], "title": "RadarCheckItem" }, "RadarCheckRequest": { "properties": { "addresses": { "items": { "type": "string" }, "type": "array", "title": "Addresses", "description": "1 to 1,000 addresses." } }, "additionalProperties": false, "type": "object", "required": [ "addresses" ], "title": "RadarCheckRequest" }, "RadarCheckResult": { "properties": { "results": { "items": { "$ref": "#/components/schemas/RadarCheckItem" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "RadarCheckResult" }, "RadarCounts": { "properties": { "watched": { "type": "integer", "title": "Watched", "description": "Every watched address." }, "ready": { "type": "integer", "title": "Ready", "description": "Ready for their next transfer." }, "needs_attention": { "type": "integer", "title": "Needs Attention", "description": "Addresses with an unreviewed security alert or a current problem." }, "attention_security": { "type": "integer", "title": "Attention Security", "description": "Of those, addresses with an unreviewed security alert." }, "not_ready": { "type": "integer", "title": "Not Ready", "description": "Addresses that are `needs_energy`, `not_activated`, `frozen`, `low_trx` or `unknown`." }, "waiting_to_sweep": { "type": "integer", "title": "Waiting To Sweep", "description": "Addresses with a deposit waiting to be swept." }, "energy_paused": { "type": "integer", "title": "Energy Paused", "description": "Addresses with Energy paused." }, "watching": { "type": "integer", "title": "Watching", "description": "Addresses in `alert_only` scenarios with Energy warnings off." } }, "type": "object", "required": [ "watched", "ready", "needs_attention", "attention_security", "not_ready", "waiting_to_sweep", "energy_paused", "watching" ], "title": "RadarCounts", "description": "`watched` is every live address; `ready` and `not_ready` never count `watching` ones (\"Only alert me\" without Energy warnings)." }, "RadarDeliveryView": { "properties": { "destination_id": { "type": "string", "format": "uuid", "title": "Destination Id", "description": "Your channel's id." }, "destination_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Destination Name", "description": "Its name." }, "channel_type": { "type": "string", "title": "Channel Type", "description": "`telegram`, `webhook` or `email`.", "enum": [ "telegram", "webhook", "email" ] }, "status": { "type": "string", "title": "Status", "description": "`pending`, `sent`, `failed`, `coalesced` (folded into a Telegram digest) or `disabled` (the channel is off for this alert, or muted).", "enum": [ "pending", "sent", "failed", "coalesced", "disabled" ] }, "attempts": { "type": "integer", "title": "Attempts", "description": "Delivery attempts so far." }, "http_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Http Status", "description": "The webhook's last HTTP status." }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms", "description": "Time to deliver, in milliseconds." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the delivery was queued." }, "sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Sent At", "description": "When it was delivered." } }, "type": "object", "required": [ "destination_id", "destination_name", "channel_type", "status", "attempts", "http_status", "latency_ms", "created_at", "sent_at" ], "title": "RadarDeliveryView", "description": "One delivery of an event to a channel." }, "RadarEnergyQuote": { "properties": { "energy": { "type": "integer", "title": "Energy", "description": "Energy the next transfer still needs, rounded up to the next 1,000, with the minimum order applied." }, "total_price_sun": { "type": "integer", "title": "Total Price Sun", "description": "That Energy at this hour's rate, with your VIP price (SUN). Activation not included." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time activation of an address that isn't activated yet (SUN); `0` otherwise." } }, "type": "object", "required": [ "energy", "total_price_sun", "activation_fee_sun" ], "title": "RadarEnergyQuote", "description": "What adding Energy would order and cost now." }, "RadarEpisodeView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "The deposit's id: `episode_id` in webhooks." }, "opened_at": { "type": "string", "format": "date-time", "title": "Opened At", "description": "When deposits reached the threshold." }, "balance": { "type": "string", "title": "Balance", "description": "USDT balance waiting to be swept (the address's balance now), six-decimal string." }, "waiting_seconds": { "type": "integer", "title": "Waiting Seconds", "description": "Seconds since `opened_at`." }, "blocker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Blocker", "description": "Why Radar couldn't add Energy for this deposit, from its latest attempt, for example `insufficient_balance`, `budget`, `outside_hours`, `no_bandwidth` or `frozen`. `null` when nothing stands in the way." } }, "type": "object", "required": [ "id", "opened_at", "balance", "waiting_seconds", "blocker" ], "title": "RadarEpisodeView" }, "RadarEventDetail": { "properties": { "event": { "$ref": "#/components/schemas/RadarEventView" }, "actions": { "items": { "$ref": "#/components/schemas/RadarActionView" }, "type": "array", "title": "Actions", "description": "Radar's Energy decisions about this event." }, "deliveries": { "items": { "$ref": "#/components/schemas/RadarDeliveryView" }, "type": "array", "title": "Deliveries", "description": "Every delivery of the event and of its resends." } }, "type": "object", "required": [ "event", "actions", "deliveries" ], "title": "RadarEventDetail" }, "RadarEventView": { "properties": { "id": { "type": "integer", "title": "Id", "description": "The event id: the replay cursor, and `data.event_id` in webhooks." }, "type": { "type": "string", "title": "Type", "description": "An `address.*` event type." }, "address": { "type": "string", "title": "Address", "description": "The watched address." }, "tx_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tx Id", "description": "The transaction behind the event; `null` for events from Radar's own checks." }, "block_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Block Number", "description": "Its block; `null` without a transaction." }, "block_time": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Block Time", "description": "Its block's time; `null` without a transaction." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When Radar recorded the event." }, "finality": { "anyOf": [ { "type": "string", "enum": [ "head", "solid", "reverted" ] }, { "type": "null" } ], "title": "Finality", "description": "`head` (newest block), `solid` (irreversible) or `reverted` (the block was dropped); `null` without a transaction." }, "finality_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finality Updated At", "description": "When `finality` last changed." }, "late": { "type": "boolean", "title": "Late", "description": "Radar read the block more than 100 blocks (about five minutes) behind the chain." }, "data": { "additionalProperties": true, "type": "object", "title": "Data", "description": "The webhook `data`, exactly as sent." }, "review": { "anyOf": [ { "$ref": "#/components/schemas/RadarReview" }, { "type": "null" } ], "description": "Who marked it as reviewed, and when; `null` if nobody did." } }, "type": "object", "required": [ "id", "type", "address", "tx_id", "block_number", "block_time", "created_at", "finality", "finality_updated_at", "late", "data", "review" ], "title": "RadarEventView", "description": "One Radar event.", "example": { "id": 124, "type": "address.usdt.received", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "created_at": "2026-10-04T18:04:57Z", "finality": "solid", "finality_updated_at": "2026-10-04T18:05:51Z", "late": false, "data": { "address_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c", "address": "TXKc3d5gEqvKEayX9LySXNS5RLf4qDDEb1", "display_name": "deposit-0042", "label": "deposit-0042", "external_id": "invoice-4821", "scenario_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "scenario_name": "Deposit addresses", "event_id": 124, "tx_id": "c3f1a0d29e7b4c5a8d6e0f1b2a3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e", "block_number": 86792801, "block_time": "2026-10-04T18:04:54Z", "finality": "head", "asset": "USDT", "direction": "in", "amount": "1250.000000", "counterparty": "TYqHsaXKuUutMYADYKF15hVfVAYfmpggvo", "balance": "1250.000000" }, "review": null } }, "RadarEventsFeed": { "properties": { "events": { "items": { "$ref": "#/components/schemas/RadarEventView" }, "type": "array", "title": "Events", "description": "Oldest first." }, "next_since_id": { "type": "integer", "title": "Next Since Id", "description": "Send as `since_id` for the next page. Equals the `since_id` you sent when there are no new events." } }, "type": "object", "required": [ "events", "next_since_id" ], "title": "RadarEventsFeed", "description": "Oldest first; pass `next_since_id` back as `since_id` to continue." }, "RadarItemResult": { "properties": { "address": { "type": "string", "title": "Address", "description": "The address (as you sent it, if it isn't valid)." }, "status": { "type": "string", "title": "Status", "description": "Add: `created`, `exists`, `moved`, `duplicate`, `invalid` or `limit_exceeded`. Bulk: `ok`, `not_found`, `limit_exceeded` or `invalid`.", "enum": [ "created", "exists", "moved", "duplicate", "invalid", "limit_exceeded", "ok", "not_found" ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why an item is `invalid`, for example `invalid_address`, `invalid_label`, `invalid_external_id` or `external_id_taken`; otherwise `null`." } }, "type": "object", "required": [ "address", "status" ], "title": "RadarItemResult" }, "RadarLastEvent": { "properties": { "kind": { "type": "string", "title": "Kind", "description": "The event type, for example `address.usdt.received`." }, "at": { "type": "string", "format": "date-time", "title": "At", "description": "When Radar recorded it." }, "summary": { "type": "string", "title": "Summary", "description": "The event type in words, for example `Usdt received`. Branch on `kind`, not on this." }, "tx_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tx Id", "description": "Its transaction, when it has one." } }, "type": "object", "required": [ "kind", "at", "summary", "tx_id" ], "title": "RadarLastEvent" }, "RadarLimitsView": { "properties": { "watch_only": { "$ref": "#/components/schemas/RadarUsage", "description": "Addresses in `alert_only` scenarios." }, "with_energy": { "$ref": "#/components/schemas/RadarUsage", "description": "Addresses in `add_on_deposit` and `add_after_transfer` scenarios." } }, "type": "object", "required": [ "watch_only", "with_energy" ], "title": "RadarLimitsView" }, "RadarManualEnergyRequest": { "properties": { "max_total_price_sun": { "anyOf": [ { "type": "integer", "maximum": 9.223372036854776e+18, "minimum": 0.0 }, { "type": "null" } ], "title": "Max Total Price Sun", "description": "The most you'll pay, activation included (SUN): `total_price_sun + activation_fee_sun` of a quote. Omitted: the live price. On `alert_only` addresses this and your balance are the only caps." }, "energy_preset": { "anyOf": [ { "type": "string", "maxLength": 1024, "enum": [ "65k", "131k" ] }, { "type": "null" } ], "title": "Energy Preset", "description": "`65k` or `131k`. Omitted: the scenario's preset." } }, "additionalProperties": false, "type": "object", "title": "RadarManualEnergyRequest", "description": "Optional: an empty body or no body buys at the live price with the scenario's preset. Unknown fields are refused (422), so a misspelt `max_total_price_sun` never reads as \"no ceiling\"." }, "RadarPresetPrice": { "properties": { "now_sun": { "type": "integer", "title": "Now Sun", "description": "One addition now, with your VIP price (SUN)." }, "min_sun": { "type": "integer", "title": "Min Sun", "description": "The cheapest hour today (SUN)." }, "max_sun": { "type": "integer", "title": "Max Sun", "description": "The dearest hour today (SUN)." } }, "type": "object", "required": [ "now_sun", "min_sun", "max_sun" ], "title": "RadarPresetPrice" }, "RadarPricingView": { "properties": { "presets": { "additionalProperties": { "$ref": "#/components/schemas/RadarPresetPrice" }, "type": "object", "title": "Presets", "description": "Per preset: `65k` and `131k`." }, "activation_fee_sun": { "type": "integer", "title": "Activation Fee Sun", "description": "One-time activation an address that isn't activated yet adds to its first addition (SUN)." }, "schedule_url": { "type": "string", "title": "Schedule Url", "description": "The hourly price schedule in the workspace (a path on tronagg.ai)." } }, "type": "object", "required": [ "presets", "activation_fee_sun", "schedule_url" ], "title": "RadarPricingView" }, "RadarReadinessView": { "properties": { "state": { "type": "string", "enum": [ "ready", "needs_energy", "waiting_for_usdt", "not_activated", "frozen", "low_trx", "energy_paused", "unknown", "watching" ], "title": "State", "description": "`ready`: Energy for one transfer of the preset and bandwidth paid. `needs_energy`: less Energy than the next transfer needs. `waiting_for_usdt`: an `add_on_deposit` address whose deposits haven't reached its threshold. `not_activated`: not on the chain yet. `frozen`: the issuer froze its USDT. `low_trx`: can't pay its bandwidth. `energy_paused`: you paused Energy. `unknown`: not read from the chain yet. `watching`: an `alert_only` address with Energy warnings off; Energy isn't tracked." }, "energy_available": { "type": "integer", "title": "Energy Available", "description": "Energy the address has now." }, "energy_target": { "type": "integer", "title": "Energy Target", "description": "Energy one charge of the preset buys: 65,000, 131,000 or the custom amount." }, "energy_required": { "type": "integer", "title": "Energy Required", "description": "Energy the next transfer needs for the address to count as ready: 64,285, 130,285 or the custom amount. The gap is `energy_required − energy_available`." }, "deficit": { "type": "integer", "title": "Deficit", "description": "Energy Radar would buy now for the next transfer: the shortfall rounded up to the next 1,000, with the minimum order applied. `0` when ready or watching." }, "stale": { "type": "boolean", "title": "Stale", "description": "`true` when this isn't confirmed by fresh data: Radar is delayed, or the address hasn't been refreshed lately." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "When the address was last read from the chain." }, "energy_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Energy Expires At", "description": "When the Energy Radar added expires; `null` without Radar's Energy." } }, "type": "object", "required": [ "state", "energy_available", "energy_target", "energy_required", "deficit", "stale", "updated_at", "energy_expires_at" ], "title": "RadarReadinessView" }, "RadarRedeliverRequest": { "properties": { "destination_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Destination Id", "description": "One of your channels. Omitted: the channels of the address's current scenario." } }, "additionalProperties": false, "type": "object", "title": "RadarRedeliverRequest" }, "RadarReview": { "properties": { "by": { "type": "string", "title": "By", "description": "The id of the user who reviewed it." }, "at": { "type": "string", "format": "date-time", "title": "At", "description": "When." } }, "type": "object", "required": [ "by", "at" ], "title": "RadarReview" }, "RadarReviewRequest": { "properties": { "event_id": { "type": "integer", "maximum": 9.223372036854776e+18, "minimum": 1.0, "title": "Event Id", "description": "A security or problem event of this address." } }, "additionalProperties": false, "type": "object", "required": [ "event_id" ], "title": "RadarReviewRequest" }, "RadarScenarioCreate": { "properties": { "name": { "type": "string", "maxLength": 1024, "title": "Name", "description": "1 to 80 printable characters, unique per account." }, "action": { "type": "string", "maxLength": 1024, "title": "Action", "description": "`alert_only`, `add_on_deposit` or `add_after_transfer`.", "enum": [ "alert_only", "add_on_deposit", "add_after_transfer" ] }, "threshold": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "title": "Threshold", "description": "USDT amount, up to six decimals (`\"100\"` or `\"100.5\"`), for `add_on_deposit`: Energy when deposits reach it. Counts USDT that arrives after the address joins the scenario and isn't swept yet. USDT already on the address doesn't count. Default `\"100\"`. Refused for other actions." }, "energy_preset": { "type": "string", "maxLength": 1024, "title": "Energy Preset", "default": "65k", "description": "`65k` (default), `131k` or `custom`.", "enum": [ "65k", "131k", "custom" ] }, "energy_custom": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Energy Custom", "description": "Energy per charge for `custom`, within the order limits." }, "times_per_address_day": { "type": "integer", "maximum": 2147483647.0, "minimum": 0.0, "title": "Times Per Address Day", "default": 5, "description": "Automatic additions per address per day, 1 to 1,000. Default 5." }, "daily_budget_sun": { "type": "integer", "maximum": 9.223372036854776e+18, "minimum": 0.0, "title": "Daily Budget Sun", "default": 50000000, "description": "Cap on every Energy purchase per UTC day, manual ones included: 1,000,000 to 1,000,000,000,000 SUN. Default 50,000,000 (50 TRX). Manual buys on `alert_only` scenarios aren't capped by it." }, "repeat_if_unswept": { "type": "boolean", "title": "Repeat If Unswept", "default": false, "description": "Add Energy once more when a deposit isn't swept within the hour the Energy lasts. Default `false`." }, "energy_alerts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Energy Alerts", "description": "Energy warnings. Omitted: `false` for `alert_only`, `true` for the Energy actions. `false` is refused for the Energy actions." }, "active_hours": { "anyOf": [ { "$ref": "#/components/schemas/RadarActiveHours" }, { "type": "null" } ], "title": "Active Hours", "description": "Working hours, or `null` (default) for any time." }, "usdt_low_threshold": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "title": "Usdt Low Threshold", "description": "USDT amount, up to six decimals: send `address.usdt.low` below it. Default off." }, "notify_destination_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Notify Destination Ids", "description": "`null` (default): every channel, new ones included. `[]`: nowhere outside Radar. A list: those channels of yours." } }, "additionalProperties": false, "type": "object", "required": [ "name", "action" ], "title": "RadarScenarioCreate", "description": "A new scenario. Unknown fields are refused." }, "RadarScenarioList": { "properties": { "scenarios": { "items": { "$ref": "#/components/schemas/RadarScenarioView" }, "type": "array", "title": "Scenarios" } }, "type": "object", "required": [ "scenarios" ], "title": "RadarScenarioList" }, "RadarScenarioRef": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "action": { "type": "string", "title": "Action", "description": "`alert_only`, `add_on_deposit` or `add_after_transfer`.", "enum": [ "alert_only", "add_on_deposit", "add_after_transfer" ] } }, "type": "object", "required": [ "id", "name", "action" ], "title": "RadarScenarioRef" }, "RadarScenarioUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "title": "Name", "description": "1 to 80 printable characters, unique per account." }, "action": { "anyOf": [ { "type": "string", "maxLength": 1024, "enum": [ "alert_only", "add_on_deposit", "add_after_transfer" ] }, { "type": "null" } ], "title": "Action", "description": "`alert_only`, `add_on_deposit` or `add_after_transfer`." }, "threshold": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "title": "Threshold", "description": "USDT amount, up to six decimals, for `add_on_deposit`: Energy when deposits reach it. Counts USDT that arrives after the address joins the scenario and isn't swept yet. USDT already on the address doesn't count. `null` is refused while the action is `add_on_deposit`." }, "energy_preset": { "anyOf": [ { "type": "string", "maxLength": 1024, "enum": [ "65k", "131k", "custom" ] }, { "type": "null" } ], "title": "Energy Preset", "description": "`65k` (default), `131k` or `custom`." }, "energy_custom": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Energy Custom", "description": "Energy per charge for `custom`, within the order limits." }, "times_per_address_day": { "anyOf": [ { "type": "integer", "maximum": 2147483647.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Times Per Address Day", "description": "Automatic additions per address per day, 1 to 1,000. Default 5." }, "daily_budget_sun": { "anyOf": [ { "type": "integer", "maximum": 9.223372036854776e+18, "minimum": 0.0 }, { "type": "null" } ], "title": "Daily Budget Sun", "description": "Cap on every Energy purchase per UTC day, manual ones included: 1,000,000 to 1,000,000,000,000 SUN. Default 50,000,000 (50 TRX). Manual buys on `alert_only` scenarios aren't capped by it." }, "repeat_if_unswept": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Repeat If Unswept", "description": "Add Energy once more when a deposit isn't swept within the hour the Energy lasts. Default `false`." }, "energy_alerts": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Energy Alerts", "description": "Energy warnings. `false` is refused for the Energy actions. When `action` changes and this is omitted: `true` for the Energy actions, `false` for `alert_only`." }, "active_hours": { "anyOf": [ { "$ref": "#/components/schemas/RadarActiveHours" }, { "type": "null" } ], "title": "Active Hours", "description": "Working hours; `null` for any time." }, "usdt_low_threshold": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ], "title": "Usdt Low Threshold", "description": "USDT amount, up to six decimals; `null` turns the alert off." }, "notify_destination_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Notify Destination Ids", "description": "`null`: every channel. `[]`: nowhere outside Radar. A list: those channels of yours." } }, "additionalProperties": false, "type": "object", "title": "RadarScenarioUpdate", "description": "The fields to change. Unknown fields are refused." }, "RadarScenarioView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "action": { "type": "string", "title": "Action", "description": "`alert_only`, `add_on_deposit` or `add_after_transfer`.", "enum": [ "alert_only", "add_on_deposit", "add_after_transfer" ] }, "threshold": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Threshold", "description": "Energy when deposits reach this USDT amount (`add_on_deposit` only), six-decimal string; otherwise `null`." }, "energy_preset": { "type": "string", "title": "Energy Preset", "description": "`65k`, `131k` or `custom`.", "enum": [ "65k", "131k", "custom" ] }, "energy_custom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Energy Custom", "description": "Energy per charge for `custom`; otherwise `null`." }, "energy_target": { "type": "integer", "title": "Energy Target", "description": "Energy one charge buys: 65,000, 131,000 or `energy_custom`." }, "energy_required": { "type": "integer", "title": "Energy Required", "description": "Energy the next transfer needs for the address to be ready: 64,285, 130,285 or `energy_custom`." }, "times_per_address_day": { "type": "integer", "title": "Times Per Address Day", "description": "Automatic additions per address per day (UTC)." }, "daily_budget_sun": { "type": "integer", "title": "Daily Budget Sun", "description": "Cap on every Energy purchase of the scenario per UTC day, manual ones included (SUN). Manual buys on `alert_only` scenarios aren't capped by it." }, "repeat_if_unswept": { "type": "boolean", "title": "Repeat If Unswept", "description": "Add Energy once more when a deposit isn't swept within the hour the Energy lasts." }, "energy_alerts": { "type": "boolean", "title": "Energy Alerts", "description": "Energy warnings (`address.energy.insufficient`, `address.trx.low`). Always `true` for the Energy actions; off by default for `alert_only`." }, "active_hours": { "anyOf": [ { "$ref": "#/components/schemas/RadarActiveHours" }, { "type": "null" } ], "title": "Active Hours", "description": "Working hours, or `null` for any time." }, "usdt_low_threshold": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usdt Low Threshold", "description": "Send `address.usdt.low` below this USDT balance (six-decimal string); `null` when off." }, "notify_destination_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Notify Destination Ids", "description": "Where alerts go: `null` every channel (new ones included), `[]` nowhere outside Radar, or these channel ids." }, "address_count": { "type": "integer", "title": "Address Count", "description": "Watched addresses in the scenario." }, "spent_today_sun": { "type": "integer", "title": "Spent Today Sun", "description": "Spent today (UTC), purchases in progress included (SUN)." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "action", "threshold", "energy_preset", "energy_custom", "energy_target", "energy_required", "times_per_address_day", "daily_budget_sun", "repeat_if_unswept", "energy_alerts", "active_hours", "usdt_low_threshold", "notify_destination_ids", "address_count", "spent_today_sun", "created_at", "updated_at" ], "title": "RadarScenarioView", "description": "A scenario: what Radar does for a group of addresses.", "example": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5d", "name": "Deposit addresses", "action": "add_on_deposit", "threshold": "100.000000", "energy_preset": "65k", "energy_custom": null, "energy_target": 65000, "energy_required": 64285, "times_per_address_day": 5, "daily_budget_sun": 50000000, "repeat_if_unswept": false, "energy_alerts": true, "active_hours": null, "usdt_low_threshold": null, "notify_destination_ids": null, "address_count": 1240, "spent_today_sun": 14040000, "created_at": "2026-10-04T09:12:44Z", "updated_at": "2026-10-04T09:12:44Z" } }, "RadarStatus": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether TRONAgg Radar is switched on." }, "access": { "$ref": "#/components/schemas/RadarAccessView" }, "head_block": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Head Block", "description": "The last TRON block Radar has read; `null` before the first one." }, "lag_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Lag Seconds", "description": "Seconds since the newest block Radar has seen was produced; `null` before the first one." }, "state": { "type": "string", "enum": [ "live", "delayed" ], "title": "State", "description": "`live`, or `delayed` when Radar is more than 30 seconds behind the chain." }, "limits": { "$ref": "#/components/schemas/RadarLimitsView" }, "counts": { "$ref": "#/components/schemas/RadarCounts" }, "today": { "$ref": "#/components/schemas/RadarToday" } }, "type": "object", "required": [ "enabled", "access", "head_block", "lag_seconds", "state", "limits", "counts", "today" ], "title": "RadarStatus", "description": "Radar status: access, chain freshness, limits, counts and today's spend.", "example": { "enabled": true, "access": { "granted": true, "reason": null }, "head_block": 87137548, "lag_seconds": 2, "state": "live", "limits": { "watch_only": { "used": 5, "max": 100 }, "with_energy": { "used": 1240, "max": 10000 } }, "counts": { "watched": 1245, "ready": 37, "needs_attention": 2, "attention_security": 1, "not_ready": 3, "waiting_to_sweep": 12, "energy_paused": 0, "watching": 5 }, "today": { "energy_added": 41, "spent_sun": 71955000, "saved_sun": 191634000 } } }, "RadarToday": { "properties": { "energy_added": { "type": "integer", "title": "Energy Added", "description": "Energy additions since 00:00 UTC." }, "spent_sun": { "type": "integer", "title": "Spent Sun", "description": "What they cost since 00:00 UTC, purchases in progress included (SUN)." }, "saved_sun": { "type": "integer", "title": "Saved Sun", "description": "Estimated TRX your sweeps didn't burn today (SUN)." } }, "type": "object", "required": [ "energy_added", "spent_sun", "saved_sun" ], "title": "RadarToday", "description": "Since 00:00 UTC: Energy additions delivered, what purchases spent (in flight included) and the estimated savings." }, "RadarUsage": { "properties": { "used": { "type": "integer", "title": "Used", "description": "Addresses in this limit now." }, "max": { "type": "integer", "title": "Max", "description": "The most this account can have." } }, "type": "object", "required": [ "used", "max" ], "title": "RadarUsage" }, "RadarActiveHours": { "type": "object", "title": "RadarActiveHours", "description": "Working hours: Radar adds Energy only inside them. Alerts arrive at any time.", "properties": { "days": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "minItems": 1, "uniqueItems": true, "description": "Weekdays in `tz`: 0 = Monday … 6 = Sunday." }, "from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Opens at `HH:MM`." }, "to": { "type": "string", "pattern": "^(([01]\\d|2[0-3]):[0-5]\\d|24:00)$", "description": "Closes at `HH:MM`, or `24:00`. Earlier than `from` means overnight; equal to `from` is refused." }, "tz": { "type": "string", "maxLength": 64, "description": "IANA time zone, for example `Europe/Berlin`." }, "outside": { "type": "string", "enum": [ "alert_only", "defer" ], "default": "alert_only", "description": "Outside the hours: `alert_only` adds nothing; `defer` checks again when the hours start and adds Energy only if still needed." } }, "required": [ "days", "from", "to", "tz" ], "additionalProperties": false, "example": { "days": [ 0, 1, 2, 3, 4 ], "from": "09:00", "to": "18:00", "tz": "UTC", "outside": "defer" } }, "RadarErrorResponse": { "type": "object", "title": "RadarErrorResponse", "description": "A TRONAgg Radar refusal: `{\"detail\": {\"error\": \"\", \"message\": \"…\", …}}`. Branch on `error`; `message` is for logs.", "properties": { "detail": { "$ref": "#/components/schemas/RadarErrorDetail" } }, "required": [ "detail" ] }, "RadarErrorDetail": { "type": "object", "title": "RadarErrorDetail", "description": "A stable `error` slug, a human-readable `message` (absent on the resend 429s), `field` on input refusals, and the slug's extra fields.", "properties": { "error": { "type": "string", "title": "Error", "description": "Machine-readable error slug." }, "message": { "type": "string", "title": "Message", "description": "Human-readable explanation. Don't parse it." }, "field": { "type": "string", "title": "Field", "description": "The input a validation refusal is about." } }, "required": [ "error" ], "additionalProperties": true } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key obtained from your [TRONAgg workspace](https://tronagg.ai/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": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "programmatic-api", "description": "Endpoints for programmatic energy purchases via API key authentication" }, { "name": "public-api", "description": "Public endpoints — no API key required, rate-limited per IP" }, { "name": "AutoEnergy", "description": "Manage AutoEnergy subscriptions — keep Energy delegated to a TRON address so its transfers spend Energy instead of burning TRX." }, { "name": "Energy Agent", "description": "Resell TRON Energy under your own address: configure a price per unit, share the address or its pay page, and every TRX payment delivers Energy for 1 hour to the sender while your balance is charged our price." }, { "name": "TRONAgg Radar", "description": "Watch TRON addresses: USDT and TRX deposits, readiness for the next transfer and security changes, with optional Energy for the next transfer. Free to watch; Energy is paid from your balance." } ] }