{"openapi":"3.0.3","info":{"title":"TronEnergyFrog Customer API","version":"1.0.0","contact":{"email":"support@tronenergyfrog.com"},"x-guidance":"For a registration-free TRON Energy rental, POST /v1/x402/quotes with the target TRON address, then POST the returned payment_url without PAYMENT-SIGNATURE to receive the x402 v2 USDC challenge. Pay one advertised option, retry the same URL with PAYMENT-SIGNATURE, and poll status_url until fulfillment completes.","description":"Customer API for TRON energy rentals and wallet activation.\n\n### Get an API key\n\n1. Open [@tron_energy_frog_bot](https://t.me/tron_energy_frog_bot?start=lang_en).\n2. Choose **Account → Generate API key**.\n3. Save the key immediately; it is shown only once.\n\n### Use the API key\n\n1. In Swagger UI, click **Authorize**.\n2. Paste only the API key into **Value**; do not include `Bearer`.\n3. Click **Authorize** again. Swagger UI adds the Bearer prefix automatically.\n\nFor direct API requests, send `Authorization: Bearer <apikey>` yourself.\n\n### x402 for AI agents\n\nNo account or API key is required for the [x402 endpoints](/v1/x402). Create a free quote, then pay with USDC on Base (preferred) or Solana.\n\n[x402 discovery page](https://tronenergyfrog.com/x402)\n\n[AI-friendly Markdown reference](/v1/docs/markdown)"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"**Value accepts only the API key. Do not include `Bearer`.**\n\n1. Get and save it from [@tron_energy_frog_bot](https://t.me/tron_energy_frog_bot?start=lang_en): **Account → Generate API key** (shown once).\n2. Paste only the key into **Value** below.\n3. Click **Authorize**; Swagger UI adds the Bearer prefix automatically.\n\nFor direct API requests, add this header yourself:\n\n`Authorization: Bearer <apikey>`"}},"schemas":{}},"paths":{"/v1/profile":{"get":{"summary":"Get the account profile","tags":["profile"],"description":"Returns the authenticated account identity, API-key status, discount, and TRX balance.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Account profile and TRX balance.","content":{"application/json":{"schema":{"description":"Account profile and TRX balance.","type":"object","required":["id","status","telegram_id","google_email","auth_methods","discount_percent","api_key_configured","balance"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"telegram_id":{"type":"string","nullable":true},"google_email":{"type":"string","nullable":true},"auth_methods":{"type":"array","items":{"type":"string","enum":["google","telegram"]},"uniqueItems":true},"discount_percent":{"type":"string","nullable":true},"api_key_configured":{"type":"boolean"},"balance":{"type":"object","required":["currency","available_sun","available_trx","reserved_sun","reserved_trx"],"properties":{"currency":{"type":"string","enum":["TRX"]},"available_sun":{"type":"string","pattern":"^[0-9]+$"},"available_trx":{"description":"Available balance in TRX, rounded half-up to three decimals.","type":"string","pattern":"^(?:0|[1-9][0-9]*)\\.[0-9]{3}$"},"reserved_sun":{"type":"string","pattern":"^[0-9]+$"},"reserved_trx":{"description":"Reserved balance in TRX, rounded half-up to three decimals.","type":"string","pattern":"^(?:0|[1-9][0-9]*)\\.[0-9]{3}$"}}}}},"example":{"id":"11111111-1111-4111-8111-111111111111","status":"active","telegram_id":"123456789","google_email":"frog@example.com","auth_methods":["google","telegram"],"discount_percent":"5.00","api_key_configured":true,"balance":{"currency":"TRX","available_sun":"1234499","available_trx":"1.234","reserved_sun":"1234500","reserved_trx":"1.235"}}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/wallets":{"get":{"summary":"List saved wallets","tags":["profile"],"description":"Returns the authenticated account's saved TRON wallets.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Saved TRON wallets.","content":{"application/json":{"schema":{"description":"Saved TRON wallets.","type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"description":"A saved TRON wallet.","type":"object","required":["address","label","color"],"properties":{"address":{"type":"string","minLength":34,"maxLength":34},"label":{"type":"string","nullable":true,"maxLength":64},"color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"]}},"example":{"address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","label":"Treasury","color":"frog"}}}}},"example":{"items":[{"address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","label":"Treasury","color":"frog"}]}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/wallets/{address}":{"put":{"summary":"Save a wallet","tags":["profile"],"description":"Creates or updates a saved TRON wallet label and color.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Display label and optional color.","type":"object","additionalProperties":false,"required":["label"],"properties":{"label":{"type":"string","nullable":true,"maxLength":64},"color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"]}}},"example":{"label":"Treasury","color":"frog"}}},"description":"Display label and optional color."},"parameters":[{"schema":{"type":"string","minLength":34,"maxLength":34},"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","in":"path","name":"address","required":true}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"A saved TRON wallet.","content":{"application/json":{"schema":{"description":"A saved TRON wallet.","type":"object","required":["address","label","color"],"properties":{"address":{"type":"string","minLength":34,"maxLength":34},"label":{"type":"string","nullable":true,"maxLength":64},"color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"]}}},"example":{"address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","label":"Treasury","color":"frog"}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}},"delete":{"summary":"Delete a saved wallet","tags":["profile"],"description":"Removes a saved TRON wallet from the authenticated account.","parameters":[{"schema":{"type":"string","minLength":34,"maxLength":34},"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","in":"path","name":"address","required":true}],"security":[{"BearerAuth":[]}],"responses":{"204":{"description":"Wallet deleted.","content":{"application/json":{"schema":{"description":"Wallet deleted."}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rates/network-fees":{"get":{"summary":"Get TRON network fee estimates","tags":["quotes"],"description":"Returns separate recipient-balance profiles using a recency-weighted median of successful snapshots from the last 30 minutes, plus the current minimum_custom_energy_amount for custom requests. If live data fails, recent persisted snapshots are marked as fallback; if none remain, documented expected values are returned.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"TRON network burn estimates from a recency-weighted median of up to six successful snapshots from the last 30 minutes. Recipient balance profiles are inferred from distinct observed Energy-use cohorts because historical token balances are unavailable from the feed.","content":{"application/json":{"schema":{"description":"TRON network burn estimates from a recency-weighted median of up to six successful snapshots from the last 30 minutes. Recipient balance profiles are inferred from distinct observed Energy-use cohorts because historical token balances are unavailable from the feed.","type":"object","additionalProperties":false,"required":["is_fallback","energy_fee_sun","energy_fee_trx","minimum_custom_energy_amount","updated_at","profiles"],"properties":{"is_fallback":{"description":"True when the live refresh failed. A positive snapshot_count means recent persisted data is being used; zero means the documented expected 65K/130K values are being used.","type":"boolean"},"energy_fee_sun":{"type":"string","pattern":"^[0-9]+$"},"energy_fee_trx":{"description":"Network burn price in TRX per Energy unit.","type":"string"},"minimum_custom_energy_amount":{"description":"Current operator-configured minimum for custom Energy amounts. The API schema's 64,000 minimum is the absolute safety floor; this runtime value may be higher. Standard 65,000 and 130,000 presets are still accepted.","type":"integer","minimum":64000,"maximum":200000000},"updated_at":{"type":"string","format":"date-time"},"profiles":{"type":"object","additionalProperties":false,"required":["recipient_has_usdt","recipient_zero_usdt"],"properties":{"recipient_has_usdt":{"type":"object","additionalProperties":false,"required":["median_energy_used","median_commission_sun","median_commission_trx","snapshot_count"],"properties":{"median_energy_used":{"type":"integer","minimum":1,"maximum":1000000},"median_commission_sun":{"type":"string","pattern":"^[0-9]+$"},"median_commission_trx":{"type":"string"},"snapshot_count":{"description":"Recent five-minute poll snapshots used by the recency-weighted median. Zero means expected fallback values are shown.","type":"integer","minimum":0,"maximum":6}},"description":"Lower-Energy cohort, inferred to represent recipients that already hold USDT."},"recipient_zero_usdt":{"type":"object","additionalProperties":false,"required":["median_energy_used","median_commission_sun","median_commission_trx","snapshot_count"],"properties":{"median_energy_used":{"type":"integer","minimum":1,"maximum":1000000},"median_commission_sun":{"type":"string","pattern":"^[0-9]+$"},"median_commission_trx":{"type":"string"},"snapshot_count":{"description":"Recent five-minute poll snapshots used by the recency-weighted median. Zero means expected fallback values are shown.","type":"integer","minimum":0,"maximum":6}},"description":"Higher-Energy cohort, inferred to represent recipients with a zero USDT balance."}}}}},"example":{"is_fallback":false,"energy_fee_sun":"100","energy_fee_trx":"0.0001","minimum_custom_energy_amount":64000,"updated_at":"2026-07-15T12:00:00.000Z","profiles":{"recipient_has_usdt":{"median_energy_used":64285,"median_commission_sun":"6428500","median_commission_trx":"6.4285","snapshot_count":6},"recipient_zero_usdt":{"median_energy_used":130285,"median_commission_sun":"13028500","median_commission_trx":"13.0285","snapshot_count":6}}}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rates/network-fees/{target_address}":{"get":{"summary":"Estimate fees for a wallet","tags":["quotes"],"description":"Checks whether the target holds USDT and estimates the Energy needed for its next transfer.","parameters":[{"schema":{"type":"string","minLength":34,"maxLength":34},"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","in":"path","name":"target_address","required":true}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Network fee estimate selected from the target wallet's USDT balance state.","content":{"application/json":{"schema":{"description":"Network fee estimate selected from the target wallet's USDT balance state.","type":"object","required":["target_address","usdt_balance","has_usdt_balance","energy_amount","estimated_commission_sun","estimated_commission_trx","network_fee_fallback","checked_at"],"properties":{"target_address":{"type":"string","minLength":34,"maxLength":34},"usdt_balance":{"description":"USDT token balance in USDT units, with up to six decimal places; this is not the raw TRC-20 base-unit value.","type":"string","pattern":"^(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,6})?$"},"has_usdt_balance":{"type":"boolean"},"energy_amount":{"type":"integer","enum":[65000,130000]},"estimated_commission_sun":{"type":"string","pattern":"^[0-9]+$"},"estimated_commission_trx":{"type":"string"},"network_fee_fallback":{"type":"boolean"},"checked_at":{"type":"string","format":"date-time"}}},"example":{"target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","usdt_balance":"0.000223","has_usdt_balance":true,"energy_amount":65000,"estimated_commission_sun":"6500000","estimated_commission_trx":"6.5","network_fee_fallback":false,"checked_at":"2026-07-15T12:00:00.000Z"}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rates/energy":{"post":{"summary":"Get the current energy rate","tags":["quotes"],"description":"Returns the authenticated account's current unlocked customer price.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Requested Energy amount and duration; omitted values default to 65,000 Energy for one hour.","type":"object","additionalProperties":false,"properties":{"energy_amount":{"description":"Energy amount to price. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000},"duration_seconds":{"type":"integer","enum":[3600,86400]},"custom_amount":{"type":"boolean"}}},"example":{"energy_amount":65000,"duration_seconds":3600}}},"description":"Requested Energy amount and duration; omitted values default to 65,000 Energy for one hour."},"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current unlocked customer price and estimated network savings.","content":{"application/json":{"schema":{"description":"Current unlocked customer price and estimated network savings.","type":"object","required":["kind","energy_amount","duration_seconds","price_sun","price_trx","currency","average_commission_sun","average_commission_trx","savings_sun","savings_trx","savings_percent","network_fee_updated_at","network_fee_fallback"],"properties":{"kind":{"type":"string","enum":["energy"]},"energy_amount":{"type":"integer","minimum":64000,"maximum":200000000},"duration_seconds":{"type":"integer","enum":[3600,86400]},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"average_commission_sun":{"type":"string","pattern":"^[0-9]+$"},"average_commission_trx":{"type":"string"},"savings_sun":{"type":"string","pattern":"^[0-9]+$"},"savings_trx":{"type":"string"},"savings_percent":{"type":"string"},"network_fee_updated_at":{"type":"string","format":"date-time"},"network_fee_fallback":{"type":"boolean"}}},"example":{"kind":"energy","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","average_commission_sun":"6500000","average_commission_trx":"6.5","savings_sun":"4880000","savings_trx":"4.88","savings_percent":"75.07","network_fee_updated_at":"2026-07-15T12:00:00.000Z","network_fee_fallback":false}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/quotes/energy":{"post":{"summary":"Create an energy quote","tags":["quotes"],"description":"Locks a live account price briefly before a rental is submitted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Energy product and optional target wallet. For a custom amount, first read minimum_custom_energy_amount from GET /v1/rates/network-fees; 64,000 remains the absolute safety floor.","type":"object","additionalProperties":false,"properties":{"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"custom_amount":{"type":"boolean"}}},"example":{"energy_amount":65000,"duration_seconds":3600,"target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"}}},"description":"Energy product and optional target wallet. For a custom amount, first read minimum_custom_energy_amount from GET /v1/rates/network-fees; 64,000 remains the absolute safety floor."},"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Short-lived energy quote with estimated network savings.","content":{"application/json":{"schema":{"description":"Short-lived energy quote with estimated network savings.","type":"object","required":["quote_id","kind","target_address","price_sun","price_trx","currency","valid_until","energy_amount","duration_seconds","average_commission_sun","average_commission_trx","savings_sun","savings_trx","savings_percent","network_fee_updated_at","network_fee_fallback"],"properties":{"quote_id":{"type":"string","format":"uuid","example":"11111111-1111-4111-8111-111111111111"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"valid_until":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["energy"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"nullable":true,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600},"average_commission_sun":{"type":"string","pattern":"^[0-9]+$"},"average_commission_trx":{"type":"string"},"savings_sun":{"type":"string","pattern":"^[0-9]+$"},"savings_trx":{"type":"string"},"savings_percent":{"type":"string"},"network_fee_updated_at":{"type":"string","format":"date-time"},"network_fee_fallback":{"type":"boolean"}}},"example":{"quote_id":"11111111-1111-4111-8111-111111111111","kind":"energy","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","valid_until":"2026-07-15T12:01:00.000Z","average_commission_sun":"6500000","average_commission_trx":"6.5","savings_sun":"4880000","savings_trx":"4.88","savings_percent":"75.07","network_fee_updated_at":"2026-07-15T12:00:00.000Z","network_fee_fallback":false}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/quotes/activation":{"post":{"summary":"Create an activation quote","tags":["quotes"],"description":"Locks a live price for activating the target TRON wallet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Target TRON wallet to activate.","type":"object","additionalProperties":false,"required":["target_address"],"properties":{"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"}}},"example":{"target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"}}},"description":"Target TRON wallet to activate."},"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Short-lived wallet activation quote.","content":{"application/json":{"schema":{"description":"Short-lived wallet activation quote.","type":"object","required":["quote_id","kind","target_address","price_sun","price_trx","currency","valid_until"],"properties":{"quote_id":{"type":"string","format":"uuid","example":"11111111-1111-4111-8111-111111111111"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"valid_until":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["activation"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"}}},"example":{"quote_id":"22222222-2222-4222-8222-222222222222","kind":"activation","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","price_sun":"1100000","price_trx":"1.1","currency":"TRX","valid_until":"2026-07-15T12:01:00.000Z"}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rental":{"post":{"summary":"Submit an energy rental","tags":["operations"],"description":"Consumes an energy quote, reserves account funds, and queues the rental.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Locked quote and, when the quote omitted it, target TRON wallet.","type":"object","additionalProperties":false,"required":["quote_id"],"properties":{"quote_id":{"type":"string","format":"uuid","example":"11111111-1111-4111-8111-111111111111"},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","example":"order-2026-0001"}}},"example":{"quote_id":"11111111-1111-4111-8111-111111111111","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","project_id":"order-2026-0001"}}},"description":"Locked quote and, when the quote omitted it, target TRON wallet."},"security":[{"BearerAuth":[]}],"responses":{"202":{"description":"An energy rental operation and its current status.","content":{"application/json":{"schema":{"description":"An energy rental operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at","energy_amount","duration_seconds"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["energy"]},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600}}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/activation":{"post":{"summary":"Submit a wallet activation","tags":["operations"],"description":"Consumes an activation quote, reserves account funds, and queues the activation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Locked quote and, when the quote omitted it, target TRON wallet.","type":"object","additionalProperties":false,"required":["quote_id"],"properties":{"quote_id":{"type":"string","format":"uuid","example":"11111111-1111-4111-8111-111111111111"},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","example":"order-2026-0001"}}},"example":{"quote_id":"11111111-1111-4111-8111-111111111111","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","project_id":"order-2026-0001"}}},"description":"Locked quote and, when the quote omitted it, target TRON wallet."},"security":[{"BearerAuth":[]}],"responses":{"202":{"description":"A wallet activation operation and its current status.","content":{"application/json":{"schema":{"description":"A wallet activation operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["activation"]}}},"example":{"id":"44444444-4444-4444-8444-444444444444","project_id":"activation-2026-0001","kind":"activation","status":"processing","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","price_sun":"1100000","price_trx":"1.1","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:05.000Z","completed_at":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rental/auto":{"post":{"summary":"Create an automatic energy rental","tags":["operations"],"description":"Generates a live quote, accepts it immediately, reserves account funds, and queues the rental.","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Energy rental details and an optional user-scoped external project reference. For a custom amount, first read minimum_custom_energy_amount from GET /v1/rates/network-fees; 64,000 remains the absolute safety floor.","type":"object","additionalProperties":false,"required":["target_address"],"properties":{"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600},"custom_amount":{"type":"boolean"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","example":"order-2026-0001"}}},"example":{"target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"project_id":"order-2026-0001"}}},"description":"Energy rental details and an optional user-scoped external project reference. For a custom amount, first read minimum_custom_energy_amount from GET /v1/rates/network-fees; 64,000 remains the absolute safety floor."},"security":[{"BearerAuth":[]}],"responses":{"202":{"description":"An energy rental operation and its current status.","content":{"application/json":{"schema":{"description":"An energy rental operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at","energy_amount","duration_seconds"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["energy"]},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600}}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/operations/by-project/{projectId}":{"get":{"summary":"Get an operation by project ID","tags":["operations"],"description":"Returns one operation using its user-scoped external project_id.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$"},"example":"order-2026-0001","in":"path","name":"projectId","required":true}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"A rental or activation operation and its current status.","content":{"application/json":{"schema":{"description":"A rental or activation operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at","energy_amount","duration_seconds"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["energy","activation"]},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"nullable":true,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"nullable":true,"example":3600}}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/operations/{id}":{"get":{"summary":"Get an operation","tags":["operations"],"description":"Returns one rental or activation owned by the authenticated account.","parameters":[{"schema":{"type":"string","format":"uuid"},"example":"33333333-3333-4333-8333-333333333333","in":"path","name":"id","required":true}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"A rental or activation operation and its current status.","content":{"application/json":{"schema":{"description":"A rental or activation operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at","energy_amount","duration_seconds"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["energy","activation"]},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"nullable":true,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"nullable":true,"example":3600}}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/rentals":{"get":{"summary":"List rental history","tags":["operations"],"description":"Returns a cursor-paginated page of the account's energy rentals.","parameters":[{"schema":{"type":"array","items":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"minItems":1,"maxItems":100,"uniqueItems":true},"example":["queued","processing"],"in":"query","name":"status","required":false,"description":"Repeat this query parameter to match any of several statuses."},{"schema":{"type":"string","minLength":34,"maxLength":34},"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","in":"query","name":"target_address","required":false},{"schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z","in":"query","name":"created_from","required":false},{"schema":{"type":"string","format":"date-time"},"example":"2026-07-15T12:00:00.000Z","in":"query","name":"created_to","required":false},{"schema":{"type":"string","maxLength":512},"example":"eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTE1VDEyOjAwOjAwLjAwMFoiLCJpZCI6IjMzMzMzMzMzLTMzMzMtNDMzMy04MzMzLTMzMzMzMzMzMzMzMyJ9","in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"example":20,"in":"query","name":"limit","required":false}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"A page of rental operations.","content":{"application/json":{"schema":{"description":"A page of rental operations.","type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"description":"An energy rental operation and its current status.","type":"object","required":["id","project_id","kind","status","target_address","price_sun","price_trx","currency","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at","energy_amount","duration_seconds"],"properties":{"id":{"type":"string","format":"uuid","example":"33333333-3333-4333-8333-333333333333"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"currency":{"type":"string","enum":["TRX"]},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"kind":{"type":"string","enum":["energy"]},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"example":3600}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}}},"next_cursor":{"type":"string","nullable":true}}},"example":{"items":[{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"queued","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":null}],"next_cursor":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/transactions":{"get":{"summary":"List transaction history","tags":["operations"],"description":"Returns a cursor-paginated page of deposits, rentals, and activations.","parameters":[{"schema":{"type":"array","items":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed","pending","completed","expired","canceled","frozen","spam","rejected","refunded"]},"minItems":1,"maxItems":100,"uniqueItems":true},"example":["queued","processing"],"in":"query","name":"status","required":false,"description":"Repeat this query parameter to match any of several statuses."},{"schema":{"type":"string","enum":["energy","activation","deposit"]},"example":"deposit","in":"query","name":"kind","required":false,"description":"Limit transaction history to rentals, activations, or deposits."},{"schema":{"type":"string","minLength":34,"maxLength":34},"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","in":"query","name":"target_address","required":false},{"schema":{"type":"string","format":"date-time"},"example":"2026-07-01T00:00:00.000Z","in":"query","name":"created_from","required":false},{"schema":{"type":"string","format":"date-time"},"example":"2026-07-15T12:00:00.000Z","in":"query","name":"created_to","required":false},{"schema":{"type":"string","maxLength":512},"example":"eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTE1VDEyOjAwOjAwLjAwMFoiLCJpZCI6IjMzMzMzMzMzLTMzMzMtNDMzMy04MzMzLTMzMzMzMzMzMzMzMyJ9","in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"example":20,"in":"query","name":"limit","required":false}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"A page of account transaction history.","content":{"application/json":{"schema":{"description":"A page of account transaction history.","type":"object","required":["items","next_cursor"],"properties":{"items":{"type":"array","items":{"description":"A deposit, rental, or activation history item.","type":"object","required":["id","project_id","provider","txid","kind","status","target_address","energy_amount","duration_seconds","price_sun","price_trx","amount_sun","amount_trx","fee_percent","fee_sun","fee_trx","invoice_amount_sun","invoice_amount_trx","currency","asset","wallet_label","wallet_color","error_code","created_at","updated_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._:-]+$","nullable":true,"example":"order-2026-0001"},"provider":{"type":"string","nullable":true},"txid":{"type":"string","pattern":"^[a-f0-9]{64}$","nullable":true},"kind":{"type":"string","enum":["energy","activation","deposit"]},"status":{"type":"string","enum":["queued","processing","submitted","unknown","succeeded","failed","pending","completed","expired","canceled","frozen","spam","rejected","refunded"]},"target_address":{"type":"string","minLength":34,"maxLength":34,"nullable":true,"example":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm"},"energy_amount":{"description":"Energy amount to rent. 64,000 is the absolute safety floor; custom amounts must also meet the current minimum_custom_energy_amount returned by GET /v1/rates/network-fees. Standard 65,000 and 130,000 presets remain available.","type":"integer","minimum":64000,"maximum":200000000,"nullable":true,"example":65000},"duration_seconds":{"type":"integer","enum":[3600,86400],"nullable":true,"example":3600},"price_sun":{"type":"string","pattern":"^[0-9]+$"},"price_trx":{"type":"string"},"amount_sun":{"type":"string","pattern":"^[0-9]+$","nullable":true},"amount_trx":{"type":"string","nullable":true},"fee_percent":{"type":"string","nullable":true},"fee_sun":{"type":"string","pattern":"^[0-9]+$","nullable":true},"fee_trx":{"type":"string","nullable":true},"invoice_amount_sun":{"type":"string","pattern":"^[0-9]+$","nullable":true},"invoice_amount_trx":{"type":"string","nullable":true},"currency":{"type":"string","enum":["TRX"]},"asset":{"type":"string","enum":["TRX"],"nullable":true},"wallet_label":{"type":"string","nullable":true},"wallet_color":{"type":"string","enum":["frog","coral","gold","sky","violet","slate"],"nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"example":{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"succeeded","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":"2026-07-15T12:00:30.000Z","provider":null,"txid":null,"amount_sun":null,"amount_trx":null,"fee_percent":null,"fee_sun":null,"fee_trx":null,"invoice_amount_sun":null,"invoice_amount_trx":null,"asset":null}}},"next_cursor":{"type":"string","nullable":true}}},"example":{"items":[{"id":"33333333-3333-4333-8333-333333333333","project_id":"order-2026-0001","kind":"energy","status":"succeeded","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"price_sun":"1620000","price_trx":"1.62","currency":"TRX","wallet_label":"Treasury","wallet_color":"frog","error_code":null,"created_at":"2026-07-15T12:00:00.000Z","updated_at":"2026-07-15T12:00:00.000Z","completed_at":"2026-07-15T12:00:30.000Z","provider":null,"txid":null,"amount_sun":null,"amount_trx":null,"fee_percent":null,"fee_sun":null,"fee_trx":null,"invoice_amount_sun":null,"invoice_amount_trx":null,"asset":null}],"next_cursor":null}}}},"default":{"description":"A machine-readable API error.","content":{"application/json":{"schema":{"description":"A machine-readable API error.","type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"request_id":{"type":"string"}}},"example":{"type":"about:blank","title":"Request validation failed","status":400,"code":"INVALID_REQUEST","request_id":"req-1"}}}}}}},"/v1/x402":{"get":{"summary":"Discover registration-free x402 Energy rental","tags":["x402"],"description":"Machine-readable entry point for AI agents. Create a free quote, pay its POST URL with x402 v2 USDC on Base (preferred) or Solana, then poll the status URL.","security":[],"responses":{"200":{"description":"x402 capabilities and endpoints.","content":{"application/json":{"schema":{"description":"x402 capabilities and endpoints.","type":"object","additionalProperties":false,"required":["available","registration_required","x402_version","quote_endpoint","payment_endpoint_template","status_endpoint_template","payment_headers","accepted","documentation_url"],"properties":{"available":{"type":"boolean"},"registration_required":{"type":"boolean","enum":[false]},"x402_version":{"type":"integer","enum":[2]},"quote_endpoint":{"type":"string"},"payment_endpoint_template":{"type":"string"},"status_endpoint_template":{"type":"string"},"payment_headers":{"type":"object","required":["required","signature","response"],"properties":{"required":{"type":"string"},"signature":{"type":"string"},"response":{"type":"string"}}},"accepted":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["network","network_name","asset","asset_address","preferred"],"properties":{"network":{"type":"string"},"network_name":{"type":"string"},"asset":{"type":"string","enum":["USDC"]},"asset_address":{"type":"string"},"preferred":{"type":"boolean"}}}},"documentation_url":{"type":"string"}}},"example":{"available":true,"registration_required":false,"x402_version":2,"quote_endpoint":"POST /v1/x402/quotes","payment_endpoint_template":"POST /v1/x402/rentals/{quote_id}","status_endpoint_template":"GET /v1/x402/rentals/{quote_id}","payment_headers":{"required":"PAYMENT-REQUIRED","signature":"PAYMENT-SIGNATURE","response":"PAYMENT-RESPONSE"},"accepted":[{"network":"eip155:8453","network_name":"Base","asset":"USDC","asset_address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","preferred":true},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","network_name":"Solana","asset":"USDC","asset_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","preferred":false}],"documentation_url":"https://tronenergyfrog.com/x402"}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"description":"Request failed.","type":"object","additionalProperties":true,"required":["status","code"],"properties":{"status":{"type":"integer"},"code":{"type":"string"},"title":{"type":"string"},"request_id":{"type":"string"}}}}}}}}},"/v1/x402/quotes":{"post":{"summary":"Create a free x402 Energy quote","tags":["x402"],"description":"Locks the Energy price and TRX/USD conversion for ten minutes. No registration, API key, wallet signature, or payment is required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["target_address"],"properties":{"target_address":{"type":"string","minLength":34,"maxLength":34},"energy_amount":{"type":"integer","minimum":64000,"maximum":200000000},"duration_seconds":{"type":"integer","enum":[3600,86400]},"custom_amount":{"type":"boolean"}}},"example":{"target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600}}}},"security":[],"responses":{"201":{"description":"Rate-locked x402 Energy rental and its payment/fulfillment status.","content":{"application/json":{"schema":{"description":"Rate-locked x402 Energy rental and its payment/fulfillment status.","type":"object","additionalProperties":false,"required":["quote_id","status","target_address","energy_amount","duration_seconds","custom_amount","price_sun","price_trx","price_usdc","payment_amount_atomic","currency","trx_usd_rate","trx_usd_rate_observed_at","payment_url","status_url","valid_until","accepted","payment","operation","error_code","created_at","updated_at"],"properties":{"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"payment_required, settling, settlement_failed, fulfillment_pending, expired, or the linked rental operation status."},"target_address":{"type":"string","minLength":34,"maxLength":34},"energy_amount":{"type":"integer"},"duration_seconds":{"type":"integer","enum":[3600,86400]},"custom_amount":{"type":"boolean"},"price_sun":{"type":"string","pattern":"^[1-9][0-9]*$"},"price_trx":{"type":"string"},"price_usdc":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$"},"payment_amount_atomic":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Exact USDC amount in six-decimal atomic units on either accepted network."},"currency":{"type":"string","enum":["USDC"]},"trx_usd_rate":{"type":"string"},"trx_usd_rate_observed_at":{"type":"string","format":"date-time"},"payment_url":{"type":"string"},"status_url":{"type":"string"},"valid_until":{"type":"string","format":"date-time"},"accepted":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["network","network_name","asset","asset_address","preferred"],"properties":{"network":{"type":"string"},"network_name":{"type":"string"},"asset":{"type":"string","enum":["USDC"]},"asset_address":{"type":"string"},"preferred":{"type":"boolean"}}}},"payment":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["network","transaction","payer","settled_at"],"properties":{"network":{"type":"string","enum":["eip155:8453","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]},"transaction":{"type":"string"},"payer":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"type":"string","format":"date-time"}}}]},"operation":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["id","status","error_code","created_at","updated_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"quote_id":"8bb302b8-c245-48a6-94f7-90f00652a32d","status":"payment_required","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"custom_amount":false,"price_sun":"2500000","price_trx":"2.5","price_usdc":"0.780865","payment_amount_atomic":"780865","currency":"USDC","trx_usd_rate":"0.31234567","trx_usd_rate_observed_at":"2026-07-29T12:00:00.000Z","payment_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","status_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","valid_until":"2026-07-29T12:10:00.000Z","accepted":[{"network":"eip155:8453","network_name":"Base","asset":"USDC","asset_address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","preferred":true},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","network_name":"Solana","asset":"USDC","asset_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","preferred":false}],"payment":null,"operation":null,"error_code":null,"created_at":"2026-07-29T12:00:00.000Z","updated_at":"2026-07-29T12:00:00.000Z"}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"description":"Request failed.","type":"object","additionalProperties":true,"required":["status","code"],"properties":{"status":{"type":"integer"},"code":{"type":"string"},"title":{"type":"string"},"request_id":{"type":"string"}}}}}}}}},"/v1/x402/rentals/{quote_id}":{"post":{"operationId":"payX402EnergyRental","summary":"Pay and submit an x402 Energy rental","tags":["x402"],"description":"POST once to receive a 402 challenge, then retry the same URL with PAYMENT-SIGNATURE. Base USDC is preferred and listed first; Solana USDC is the fallback. The PAYMENT-RESPONSE header confirms settlement.","requestBody":{"required":true,"content":{"application/json":{"schema":{},"example":{}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"example":"8bb302b8-c245-48a6-94f7-90f00652a32d","in":"path","name":"quote_id","required":true},{"schema":{"type":"string"},"in":"header","name":"payment-signature","required":false,"description":"Base64-encoded x402 v2 PaymentPayload. Omit on the first request."}],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.000001","max":"1000"},"protocols":[{"x402":{}}]},"responses":{"202":{"description":"Payment verified; inspect PAYMENT-RESPONSE and poll status_url.","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Base64-encoded x402 settlement response."}},"content":{"application/json":{"schema":{"description":"Payment verified; inspect PAYMENT-RESPONSE and poll status_url.","type":"object","additionalProperties":false,"required":["quote_id","status","target_address","energy_amount","duration_seconds","custom_amount","price_sun","price_trx","price_usdc","payment_amount_atomic","currency","trx_usd_rate","trx_usd_rate_observed_at","payment_url","status_url","valid_until","accepted","payment","operation","error_code","created_at","updated_at"],"properties":{"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"payment_required, settling, settlement_failed, fulfillment_pending, expired, or the linked rental operation status."},"target_address":{"type":"string","minLength":34,"maxLength":34},"energy_amount":{"type":"integer"},"duration_seconds":{"type":"integer","enum":[3600,86400]},"custom_amount":{"type":"boolean"},"price_sun":{"type":"string","pattern":"^[1-9][0-9]*$"},"price_trx":{"type":"string"},"price_usdc":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$"},"payment_amount_atomic":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Exact USDC amount in six-decimal atomic units on either accepted network."},"currency":{"type":"string","enum":["USDC"]},"trx_usd_rate":{"type":"string"},"trx_usd_rate_observed_at":{"type":"string","format":"date-time"},"payment_url":{"type":"string"},"status_url":{"type":"string"},"valid_until":{"type":"string","format":"date-time"},"accepted":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["network","network_name","asset","asset_address","preferred"],"properties":{"network":{"type":"string"},"network_name":{"type":"string"},"asset":{"type":"string","enum":["USDC"]},"asset_address":{"type":"string"},"preferred":{"type":"boolean"}}}},"payment":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["network","transaction","payer","settled_at"],"properties":{"network":{"type":"string","enum":["eip155:8453","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]},"transaction":{"type":"string"},"payer":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"type":"string","format":"date-time"}}}]},"operation":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["id","status","error_code","created_at","updated_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"quote_id":"8bb302b8-c245-48a6-94f7-90f00652a32d","status":"payment_required","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"custom_amount":false,"price_sun":"2500000","price_trx":"2.5","price_usdc":"0.780865","payment_amount_atomic":"780865","currency":"USDC","trx_usd_rate":"0.31234567","trx_usd_rate_observed_at":"2026-07-29T12:00:00.000Z","payment_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","status_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","valid_until":"2026-07-29T12:10:00.000Z","accepted":[{"network":"eip155:8453","network_name":"Base","asset":"USDC","asset_address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","preferred":true},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","network_name":"Solana","asset":"USDC","asset_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","preferred":false}],"payment":null,"operation":null,"error_code":null,"created_at":"2026-07-29T12:00:00.000Z","updated_at":"2026-07-29T12:00:00.000Z"}}}},"402":{"description":"Payment is required. Decode PAYMENT-REQUIRED, pay one option, and retry with PAYMENT-SIGNATURE.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 PaymentRequired object; Base USDC is listed first."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Compatibility copy of PAYMENT-REQUIRED for x402 discovery crawlers."}},"content":{"application/json":{"schema":{"description":"Payment is required. Decode PAYMENT-REQUIRED, pay one option, and retry with PAYMENT-SIGNATURE.","type":"object","additionalProperties":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"quote_id":{"type":"string","format":"uuid"},"status_url":{"type":"string"}}}}}},"403":{"description":"The quote is missing or expired; no payment was verified or settled.","content":{"application/json":{"schema":{"description":"The quote is missing or expired; no payment was verified or settled.","type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"description":"Request failed.","type":"object","additionalProperties":true,"required":["status","code"],"properties":{"status":{"type":"integer"},"code":{"type":"string"},"title":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"get":{"summary":"Get x402 payment and rental status","tags":["x402"],"description":"Poll the capability URL returned with the quote. A random quote ID is sufficient; no registration or API key is required.","parameters":[{"schema":{"type":"string","format":"uuid"},"example":"8bb302b8-c245-48a6-94f7-90f00652a32d","in":"path","name":"quote_id","required":true}],"security":[],"responses":{"200":{"description":"Rate-locked x402 Energy rental and its payment/fulfillment status.","content":{"application/json":{"schema":{"description":"Rate-locked x402 Energy rental and its payment/fulfillment status.","type":"object","additionalProperties":false,"required":["quote_id","status","target_address","energy_amount","duration_seconds","custom_amount","price_sun","price_trx","price_usdc","payment_amount_atomic","currency","trx_usd_rate","trx_usd_rate_observed_at","payment_url","status_url","valid_until","accepted","payment","operation","error_code","created_at","updated_at"],"properties":{"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"payment_required, settling, settlement_failed, fulfillment_pending, expired, or the linked rental operation status."},"target_address":{"type":"string","minLength":34,"maxLength":34},"energy_amount":{"type":"integer"},"duration_seconds":{"type":"integer","enum":[3600,86400]},"custom_amount":{"type":"boolean"},"price_sun":{"type":"string","pattern":"^[1-9][0-9]*$"},"price_trx":{"type":"string"},"price_usdc":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$"},"payment_amount_atomic":{"type":"string","pattern":"^[1-9][0-9]*$","description":"Exact USDC amount in six-decimal atomic units on either accepted network."},"currency":{"type":"string","enum":["USDC"]},"trx_usd_rate":{"type":"string"},"trx_usd_rate_observed_at":{"type":"string","format":"date-time"},"payment_url":{"type":"string"},"status_url":{"type":"string"},"valid_until":{"type":"string","format":"date-time"},"accepted":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["network","network_name","asset","asset_address","preferred"],"properties":{"network":{"type":"string"},"network_name":{"type":"string"},"asset":{"type":"string","enum":["USDC"]},"asset_address":{"type":"string"},"preferred":{"type":"boolean"}}}},"payment":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["network","transaction","payer","settled_at"],"properties":{"network":{"type":"string","enum":["eip155:8453","solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]},"transaction":{"type":"string"},"payer":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"type":"string","format":"date-time"}}}]},"operation":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["id","status","error_code","created_at","updated_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}}]},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"example":{"quote_id":"8bb302b8-c245-48a6-94f7-90f00652a32d","status":"payment_required","target_address":"TLLM21wteSPs4hKjbxgmH1L6poyMjeTbHm","energy_amount":65000,"duration_seconds":3600,"custom_amount":false,"price_sun":"2500000","price_trx":"2.5","price_usdc":"0.780865","payment_amount_atomic":"780865","currency":"USDC","trx_usd_rate":"0.31234567","trx_usd_rate_observed_at":"2026-07-29T12:00:00.000Z","payment_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","status_url":"/v1/x402/rentals/8bb302b8-c245-48a6-94f7-90f00652a32d","valid_until":"2026-07-29T12:10:00.000Z","accepted":[{"network":"eip155:8453","network_name":"Base","asset":"USDC","asset_address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","preferred":true},{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","network_name":"Solana","asset":"USDC","asset_address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","preferred":false}],"payment":null,"operation":null,"error_code":null,"created_at":"2026-07-29T12:00:00.000Z","updated_at":"2026-07-29T12:00:00.000Z"}}}},"default":{"description":"Request failed.","content":{"application/json":{"schema":{"description":"Request failed.","type":"object","additionalProperties":true,"required":["status","code"],"properties":{"status":{"type":"integer"},"code":{"type":"string"},"title":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}},"servers":[{"url":"/","description":"Current API origin"}],"tags":[{"name":"profile","description":"Account profile and saved wallets."},{"name":"quotes","description":"Rates and short-lived account quotes."},{"name":"operations","description":"Rentals, activations, and transaction history."},{"name":"x402","description":"Registration-free USDC payment and Energy rental endpoints for AI agents."}]}