{"openapi":"3.0.3","info":{"title":"PowerSun Agent API","version":"2.0.0","description":"TRON Energy & Bandwidth marketplace and DEX swap aggregator for AI agents. Buy and sell TRON network resources, swap tokens on SunSwap DEX with automatic energy delegation — all programmatically via 27 MCP tools, REST API, HTTP 402 pay-per-use (TRX), and x402 v2 (USDC on Base, buy-energy only). SDKs: npm @powersun/mcp-client, PyPI langchain-powersun & crewai-powersun, GitHub Action Hovsteder/tron-energy-action.","contact":{"name":"PowerSun","url":"https://powersun.vip"}},"servers":[{"url":"https://powersun.vip","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key obtained via the register/verify flow."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Estimate":{"type":"object","properties":{"estimate":{"type":"object","properties":{"txCount":{"type":"integer"},"energyPerTx":{"type":"integer"},"totalEnergyNeeded":{"type":"integer"},"durationMinutes":{"type":"integer"},"resourceType":{"type":"string"}}},"pricing":{"type":"object","properties":{"pricePerUnitSun":{"type":"integer"},"totalCostSun":{"type":"integer"},"totalCostTrx":{"type":"number"},"costPerTxTrx":{"type":"number"},"savingsPercent":{"type":"number"}}}}},"Order":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","active","processing","completed","failed","cancelled","expired"]},"resourceType":{"type":"string","enum":["ENERGY","BANDWIDTH"]},"energyDelegated":{"type":"integer"},"targetAddress":{"type":"string"},"durationMinutes":{"type":"integer"},"totalCostTrx":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}},"SwapQuote":{"type":"object","properties":{"quote":{"type":"object","properties":{"fromToken":{"type":"string","description":"Source token contract address"},"toToken":{"type":"string","description":"Destination token contract address"},"fromSymbol":{"type":"string","example":"TRX"},"toSymbol":{"type":"string","example":"USDT"},"amountIn":{"type":"string","description":"Input amount in base units"},"expectedAmountOut":{"type":"string","description":"Expected output amount in base units"},"amountOutMin":{"type":"string","description":"Minimum output with slippage"},"slippageBps":{"type":"integer","description":"Slippage tolerance in basis points"},"route":{"type":"array","items":{"type":"string"},"description":"DEX routing path"},"deadline":{"type":"integer","description":"Unix timestamp deadline"}}},"energy":{"type":"object","properties":{"estimatedUnits":{"type":"integer"},"costSun":{"type":"integer"},"costTrx":{"type":"number"}}},"unsignedTx":{"type":"object","description":"Unsigned TRON transaction to sign with your private key"},"nextAction":{"type":"object","properties":{"action":{"type":"string","enum":["sign_and_broadcast"]},"description":{"type":"string"},"broadcastUrl":{"type":"string"}}}}},"X402PaymentRequirements":{"type":"object","required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds","extra"],"properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","enum":["eip155:8453"]},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"USDC token contract address on Base"},"amount":{"type":"string","pattern":"^[0-9]+$","description":"Exact USDC amount in atomic units (6 decimals)"},"payTo":{"type":"string","description":"Quoted USDC recipient"},"maxTimeoutSeconds":{"type":"integer","enum":[120]},"extra":{"type":"object","required":["name","version","intentId"],"properties":{"name":{"type":"string","enum":["USD Coin"]},"version":{"type":"string","enum":["2"]},"intentId":{"type":"string","pattern":"^pi_x402_[a-f0-9]{16}$"}}}}},"PaymentRequired":{"type":"object","properties":{"error":{"type":"string","enum":["payment_required"]},"message":{"type":"string"},"x402Version":{"type":"integer","enum":[2],"description":"Present when x402 v2 is available for buy-energy"},"resource":{"type":"object","properties":{"url":{"type":"string","example":"https://powersun.vip/api/v2/agent/buy-energy"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"}}},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402PaymentRequirements"}},"payment":{"type":"object","description":"TRX on TRON payment option (async — deposit TRX then poll status)","properties":{"depositAddress":{"type":"string"},"requiredAmountTrx":{"type":"number"},"requiredAmountSun":{"type":"integer"},"intentId":{"type":"string"},"network":{"type":"string","example":"tron:mainnet"},"asset":{"type":"string","example":"TRX"},"scheme":{"type":"string","example":"tron-transfer"},"expiresAt":{"type":"string","format":"date-time"},"checkStatusUrl":{"type":"string"}}},"x402":{"type":"object","nullable":true,"description":"Convenience summary for buy-energy. Standard x402 v2 clients use resource and accepts, and return PAYMENT-SIGNATURE. Quote valid for two minutes.","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string","example":"USDC"},"maxAmountRequired":{"type":"string","description":"Legacy alias for accepts[0].amount (USDC atomic units)"},"payTo":{"type":"string","description":"EVM address to receive USDC"},"usdcContractAddress":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"intentId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"instructions":{"type":"object","properties":{"step1":{"type":"string"},"step2":{"type":"string"},"step3":{"type":"string"},"note":{"type":"string"}}}}}}},"paths":{"/api/v2/agent/register":{"post":{"operationId":"registerAgent","summary":"Start agent registration","description":"Returns a challenge string to sign with your TRON wallet private key.","tags":["Registration"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"TRON wallet address (T-format)","example":"TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}}}}}},"responses":{"200":{"description":"Challenge created","content":{"application/json":{"schema":{"type":"object","properties":{"challengeId":{"type":"string"},"challenge":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"instructions":{"type":"string"}}}}}}}}},"/api/v2/agent/verify":{"post":{"operationId":"verifyAgent","summary":"Verify signed challenge","description":"Submit the signed challenge to receive an API key.","tags":["Registration"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challengeId","address","signature"],"properties":{"challengeId":{"type":"string"},"address":{"type":"string"},"signature":{"type":"string","description":"Hex-encoded signature from tronWeb.trx.signMessageV2()"}}}}}},"responses":{"200":{"description":"Verification successful","content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"string"},"address":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/v2/agent/estimate":{"post":{"operationId":"estimateCost","summary":"Estimate energy cost","description":"Calculate the cost of purchasing TRON Energy for a number of transactions. No authentication required.","tags":["Market"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["txCount"],"properties":{"txCount":{"type":"integer","minimum":1,"description":"Number of transactions","example":10},"txType":{"type":"string","enum":["trc20_transfer","trc20_transfer_new","trc10_transfer","contract_call"],"default":"trc20_transfer"},"durationMinutes":{"type":"integer","enum":[2,5,10,15,30,60,360,1440,10080,43200],"default":60},"resourceType":{"type":"string","enum":["ENERGY","BANDWIDTH"],"default":"ENERGY"}}}}}},"responses":{"200":{"description":"Cost estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}}}}},"/api/v2/agent/buy-energy":{"post":{"operationId":"buyEnergy","summary":"Buy energy","description":"Purchase TRON Energy for a target address.\n\nThree modes:\n1. **X-API-Key header**: deducts from TRX balance → 200 + order\n2. **PAYMENT-SIGNATURE header**: x402 v2 USDC on Base → 200 final result or 202 pending confirmation. Poll the same intent; do not pay again. Late confirmed payments credit the account with order: null.\n3. **No auth headers**: returns 402 with TRX instructions and, when available, a two-minute x402 quote. Copy resource and accepts[0] into the signed payload unchanged.","tags":["Orders"],"security":[{"apiKey":[]},{}],"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64-encoded JSON: {x402Version: 2, resource, accepted, payload: {signature, authorization: {from, to, value, validAfter, validBefore, nonce}}}. Copy resource and accepted from the quote, including accepted.extra.intentId. Sign EIP-3009 using the quoted USD Coin / 2 domain on Base. X-PAYMENT remains a compatibility alias."},{"name":"X-PAYMENT-INTENT-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Optional compatibility hint. If present, must match accepted.extra.intentId in PAYMENT-SIGNATURE."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetAddress","txCount"],"properties":{"targetAddress":{"type":"string","description":"TRON address to delegate energy to","example":"TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},"txCount":{"type":"integer","minimum":1,"example":10},"txType":{"type":"string","enum":["trc20_transfer","trc20_transfer_new","trc10_transfer","contract_call"],"default":"trc20_transfer"},"durationMinutes":{"type":"integer","default":60},"maxPriceTrx":{"type":"number","description":"Maximum acceptable total price in TRX"},"resourceType":{"type":"string","enum":["ENERGY","BANDWIDTH"],"default":"ENERGY"},"x402IntentId":{"type":"string","description":"Optional compatibility hint; must match accepted.extra.intentId in PAYMENT-SIGNATURE"}}}}}},"responses":{"200":{"description":"Order created, or final x402 result. A late confirmed x402 payment credits the account and returns order: null with paymentStage: credited.","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"type":"boolean","enum":[false]},"intentId":{"type":"string"},"paymentStage":{"type":"string","enum":["completed","credited"]},"order":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/Order"}]},"settlement":{"type":"object","properties":{"network":{"type":"string","example":"eip155:8453"},"usdcPaid":{"type":"number"},"baseTxHash":{"type":"string"}}}}}}}},"202":{"description":"Payment outcome is pending. Poll checkStatusUrl using the same intent ID; do not sign a new payment or pay again.","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"type":"boolean","enum":[true]},"intentId":{"type":"string"},"status":{"type":"string","enum":["processing"]},"paymentStage":{"type":"string"},"checkStatusUrl":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required — dual-scheme options (TRX on TRON + USDC on Base)","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 JSON with x402Version, resource, and accepts. Also available under the legacy X-PAYMENT-REQUIRED alias.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v2/agent/balance":{"get":{"operationId":"getBalance","summary":"Get balance","description":"Get current TRX balance and estimated transaction capacity.","tags":["Account"],"responses":{"200":{"description":"Balance info","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"balanceTrx":{"type":"number"},"balanceSun":{"type":"integer"},"depositAddress":{"type":"string"},"estimatedCapacity":{"type":"object"}}}}}}}}},"/api/v2/agent/order/{orderId}":{"get":{"operationId":"getOrderStatus","summary":"Get order status","description":"Get detailed order status including delegation progress and fills.","tags":["Orders"],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Order not found"}}}},"/api/v2/agent/payment-status/{intentId}":{"get":{"operationId":"getPaymentStatus","summary":"Check payment status","description":"Poll status of a 402 payment intent. No authentication required.","tags":["Payments"],"security":[],"parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payment intent status","content":{"application/json":{"schema":{"type":"object","properties":{"intentId":{"type":"string"},"status":{"type":"string","enum":["pending","received","processing","completed","expired","failed"]},"requiredAmountTrx":{"type":"number"},"message":{"type":"string"},"scheme":{"type":"string","enum":["tron-transfer","exact"]},"paymentStage":{"type":"string","description":"x402 journal phase; unknown means confirmation is pending, not a failed payment"},"requiredAmountUsdc":{"type":"string"},"receivedAmountUsdc":{"type":"string"},"settlementTransaction":{"type":"string"},"order":{"type":"object","nullable":true,"allOf":[{"$ref":"#/components/schemas/Order"}],"description":"Null for completed payments credited without an order"}}}}}}}}},"/api/v2/agent/broadcast":{"post":{"operationId":"broadcastTransaction","summary":"Broadcast transaction","description":"Broadcast a pre-signed TRON transaction with automatic energy delegation. Use X-API-Key to pay from TRX balance, or request without authentication for TRX 402 instructions. USDC x402 is supported only by /buy-energy.","tags":["Broadcast"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Pre-signed TRON transaction object","required":["txID","raw_data","raw_data_hex","signature"],"properties":{"txID":{"type":"string"},"raw_data":{"type":"object"},"raw_data_hex":{"type":"string"},"signature":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Transaction broadcast result"}}}},"/api/v2/agent/swap":{"post":{"operationId":"getSwapQuote","summary":"Get swap quote with energy delegation","description":"Get a price quote and unsigned transaction for swapping tokens on SunSwap DEX with automatic energy delegation. Sign the returned unsignedTx and broadcast via /api/v2/agent/broadcast. Use X-API-Key to pay from TRX balance, or request without authentication for TRX 402 instructions. USDC x402 is supported only by /buy-energy.","tags":["Swap"],"security":[{"apiKey":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromToken","toToken","amountIn"],"properties":{"fromToken":{"type":"string","description":"Token to sell — symbol (TRX, USDT, SUN, ...) or TRC-20 contract address","example":"TRX"},"toToken":{"type":"string","description":"Token to buy — symbol or TRC-20 contract address","example":"USDT"},"amountIn":{"type":"string","description":"Amount in base units (SUN for TRX, 6 decimals for USDT)","example":"10000000"},"slippageBps":{"type":"integer","minimum":1,"maximum":5000,"description":"Slippage tolerance in basis points (default: 50 = 0.5%)","example":100},"senderAddress":{"type":"string","description":"TRON address of the sender (defaults to registered address)"}}}}}},"responses":{"200":{"description":"Swap quote with unsigned transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapQuote"}}}},"402":{"description":"Payment required — TRX on TRON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/paygo/config":{"get":{"operationId":"paygoConfig","summary":"Paygo: partner configuration self-check","description":"Call this FIRST when wiring up an integration: proves the API key is valid and paygo-enabled, and returns every parameter your code needs — payment address (payTo), your tariff, allowed token contracts, limits, and the exact transaction requirements /submit will enforce (expirations, fee_limit, exact-amount payment).","tags":["Paygo"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Partner configuration","content":{"application/json":{"schema":{"type":"object","properties":{"partnerName":{"type":"string"},"enabled":{"type":"boolean"},"sandbox":{"type":"boolean"},"payTo":{"type":"string"},"tariff":{"type":"object","properties":{"energyPriceSun":{"type":"integer"},"bandwidthPriceSun":{"type":"integer"}}},"allowedContracts":{"type":"array","items":{"type":"string"}},"limits":{"type":"object"},"requirements":{"type":"object"},"serverTime":{"type":"string","format":"date-time"}}}}}},"401":{"description":"API_KEY_REQUIRED / INVALID_API_KEY"},"403":{"description":"PAYGO_NOT_ENABLED — the key works but paygo is not enabled for it (contact PowerSun)"}}}},"/api/v1/paygo/estimate":{"post":{"operationId":"paygoEstimate","summary":"Paygo: exact fee quote for one token transfer","description":"Partner API (wallet integrations). Returns an exact, fixed-price fee quote for a specific sender→recipient TRC-20 transfer, computed by live simulation on the TRON node (recipient storage state and the TIP-491 dynamic energy factor included). The quoted feeTrx is final: the user signs a TRX payment for exactly this amount. Requires a partner API key enabled for paygo.","tags":["Paygo"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from","to","tokenContract","amount"],"properties":{"from":{"type":"string","description":"Sender TRON address (base58)"},"to":{"type":"string","description":"Recipient TRON address (base58)"},"tokenContract":{"type":"string","description":"TRC-20 contract address","example":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"},"amount":{"type":"string","description":"Transfer amount in raw token units (USDT: 6 decimals)","example":"25000000"}}}}}},"responses":{"200":{"description":"Fixed-price quote","content":{"application/json":{"schema":{"type":"object","properties":{"estimateId":{"type":"string","example":"pe_7c11d9a0"},"energy":{"type":"integer","example":64285},"bandwidth":{"type":"integer","example":613},"burnCostTrx":{"type":"string","example":"6.7735"},"feeTrx":{"type":"string","example":"5.6332"},"feeSun":{"type":"integer","example":5633200,"description":"EXACT payment amount in SUN — build the TRX payment for precisely this integer value (do NOT derive it from feeTrx with float math; a 1-SUN mismatch is rejected with PAYMENT_MISMATCH)"},"energyPriceSun":{"type":"integer","example":80},"bandwidthPriceSun":{"type":"integer","example":800},"payTo":{"type":"string"},"validUntil":{"type":"string","format":"date-time"},"recipientInitialized":{"type":"boolean"}}}}}},"422":{"description":"Transfer would fail on-chain right now (insufficient balance, blacklist) — SIMULATION_FAILED"}}}},"/api/v1/paygo/submit":{"post":{"operationId":"paygoSubmit","summary":"Paygo: submit both signed transactions","description":"Submit the signed token transfer and the signed TRX fee payment for a previously issued estimate. PowerSun executes the full sequence server-side: payment first, then resource delegation and the transfer broadcast. Idempotent — re-submitting the same pair returns the existing order.","tags":["Paygo"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["estimateId","signedTransaction","signedPayment"],"properties":{"estimateId":{"type":"string"},"signedTransaction":{"type":"object","description":"Signed token transfer (expiration must be ≥ 5 minutes; extend BEFORE signing; fee_limit ≥ 1 TRX)"},"signedPayment":{"type":"object","description":"Signed TRX transfer of exactly feeSun (from the estimate) to payTo"},"dryRun":{"type":"boolean","description":"Integration-testing aid: run the COMPLETE validation pipeline (parsing, txID integrity, estimate cross-checks, signature recovery, duplicate detection, price freshness) but create nothing — no order, the estimate stays unconsumed, no funds can move. Response: {dryRun:true, valid:true, priceStillValid, currentFeeSun}. Use it to verify your transaction-building code before spending anything."}}}}}},"responses":{"200":{"description":"Order accepted","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","example":"po_31bb02e4"},"status":{"type":"string","example":"received"}}}}}},"409":{"description":"PRICE_CHANGED (fresh estimateId + feeTrx in body, re-sign the payment) or DUPLICATE_TX"},"410":{"description":"ESTIMATE_EXPIRED — request a new estimate"}}}},"/api/v1/paygo/order/{orderId}":{"get":{"operationId":"paygoOrderStatus","summary":"Paygo: order status","description":"Poll order state: received → paying → paid → delegating → broadcasting → confirmed → completed. Failures after a confirmed payment are refunded on-chain in full; the refund txId appears in the response. Recommended polling interval: 2–3 s.","tags":["Paygo"],"security":[{"apiKey":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order state","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string","enum":["received","paying","paid","delegating","broadcasting","confirmed","completed","failed"]},"paymentTxId":{"type":"string","nullable":true},"broadcastTxId":{"type":"string"},"refund":{"type":"object","nullable":true,"properties":{"txId":{"type":"string"},"amountTrx":{"type":"string"}}},"refundPending":{"type":"boolean","description":"true when the order failed after the fee payment confirmed and the on-chain refund has not been sent yet (it is automatic — keep polling until `refund` is populated)"},"failureCode":{"type":"string","nullable":true,"enum":["payment_failed","tx_expired","resim_failed","delegation_failed","broadcast_failed","onchain_revert"]},"failureDescription":{"type":"string","nullable":true,"description":"Human-readable explanation of the failure, safe to show to end users: what happened, whether funds moved, and what to do next"},"errorMessage":{"type":"string","nullable":true,"description":"Raw technical detail for debugging/support"},"timestamps":{"type":"object"}}}}}},"404":{"description":"Unknown orderId"}}}},"/mcp":{"post":{"operationId":"mcpMessage","summary":"MCP endpoint","description":"Model Context Protocol endpoint for AI agent tool integration. Supports Streamable HTTP transport with stateful sessions.","tags":["MCP"],"security":[{"apiKey":[]},{}],"parameters":[{"name":"Mcp-Session-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Session ID for existing sessions"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"JSON-RPC 2.0 message","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string"},"params":{"type":"object"},"id":{"type":"integer"}}}}}},"responses":{"200":{"description":"JSON-RPC response"}}}}},"tags":[{"name":"Registration","description":"Agent registration and API key management"},{"name":"Market","description":"Market data and cost estimation"},{"name":"Orders","description":"Energy/bandwidth purchase orders"},{"name":"Account","description":"Account balance and deposit info"},{"name":"Payments","description":"HTTP 402 payment flow"},{"name":"Broadcast","description":"Transaction broadcast with energy delegation"},{"name":"Swap","description":"DEX token swap via SunSwap with automatic energy delegation"},{"name":"Paygo","description":"Wallet integration: pay-per-transaction broadcast. End users pay per transfer in TRX with no account or deposit; the wallet signs both transactions, PowerSun supplies resources and broadcasts. Partner API key required — contact partnerships@powersun.vip"},{"name":"MCP","description":"Model Context Protocol for AI agents"}]}