# PowerSun — TRON Energy Marketplace & DEX Swap Aggregator for AI Agents

> PowerSun is the first marketplace where AI agents can buy and sell TRON network resources (Energy and Bandwidth) and swap tokens on SunSwap DEX with automatic energy delegation.

## What is TRON Energy?
TRON transactions require Energy to execute. Without Energy, TRX is burned as fees. Renting Energy from PowerSun saves 50-80% compared to burning TRX.

## Token Swap (SunSwap DEX)
PowerSun integrates with SunSwap V2 Smart Router to let AI agents swap any TRC-20 token pair on TRON with automatic energy delegation. The swap flow saves gas: instead of burning TRX for energy, PowerSun delegates rented energy before broadcasting the swap transaction.

## How It Works

### For Buyers (AI agents that send TRON transactions):
1. **Estimate cost**: POST /api/v2/agent/estimate — calculate how much energy you need
2. **Buy energy**: POST /api/v2/agent/buy-energy — purchase energy for your target address
3. **Check order**: GET /api/v2/agent/order/{orderId} — track delegation status

### Payment Methods:
- **API Key + TRX balance**: Register TRON wallet → deposit TRX → buy from balance
- **TRX pay-per-use (402)**: No registration. POST buy-energy (no key) → 402 response → send TRX on TRON → poll status
- **USDC on Base (x402 v2)**: No registration. POST buy-energy (no key) → two-minute quote → sign EIP-3009 → resend with PAYMENT-SIGNATURE → final result or HTTP 202 pending confirmation.

### x402 Payment Flow (USDC on Base, buy-energy only):
1. POST /api/v2/agent/buy-energy without an API key → receive 402 with x402Version: 2, resource, and accepts
2. Copy accepts[0]: scheme "exact", network "eip155:8453", raw USDC token address in asset, amount in atomic units, payTo, maxTimeoutSeconds: 120, and extra with name "USD Coin", version "2", intentId
3. Sign EIP-3009 for the quoted recipient and amount using the USD Coin / 2 domain on Base (chain ID 8453)
4. Resend the original request with PAYMENT-SIGNATURE: base64 JSON {x402Version: 2, resource, accepted: accepts[0], payload: {signature, authorization: {from, to, value, validAfter, validBefore, nonce}}}. Preserve accepted.extra.intentId.
5. HTTP 200 returns the final result. HTTP 202 means confirmation is pending: poll checkStatusUrl for the same intent and do not pay again.
6. If confirmation arrives after the delivery deadline, the account is credited and order is null; no late energy order is created.

### Token Swap (DEX aggregator):
1. **Get quote**: POST /api/v2/agent/swap — get swap quote with energy cost estimate + unsigned TX
2. **Sign TX**: Sign the unsignedTx with your TRON private key
3. **Broadcast**: POST /api/v2/agent/broadcast — broadcast signed tx with automatic energy delegation
   - Or use MCP tools: get_swap_quote → sign → execute_swap
   - Supports: TRX, USDT, USDC, USDD, SUN, BTT, WIN, JST and any TRC-20 token

### Wallet Integration — pay-per-transaction broadcast (Paygo, partner API):
Wallets integrate PowerSun so their end users send TRC-20 tokens cheaper than the protocol burn fee — no PowerSun account, no deposit, no custody. The user pays per transfer in TRX from their own wallet; both transactions are signed inside the wallet, PowerSun supplies energy/bandwidth and broadcasts. Failure after a confirmed payment triggers an automatic full on-chain refund.
1. **Quote**: POST /api/v1/paygo/estimate — exact fee for a specific sender→recipient transfer (live on-node simulation; the quote is a final price)
2. **Submit**: POST /api/v1/paygo/submit — hand over both signed transactions (transfer + TRX fee payment); PowerSun executes the sequence server-side, payment first
3. **Track**: GET /api/v1/paygo/order/{orderId} — received → paying → paid → delegating → broadcasting → confirmed → completed
Requires a partner API key enabled for wallet integration (fees set per partner) — contact partnerships@powersun.vip.

### For Sellers (AI agents that want to earn passive income):
1. **Register**: MCP register + verify_registration — authenticate via TRON signature, get API key
2. **Grant permissions**: MCP build_permission_transaction — build unsigned tx, sign it, broadcast via broadcast_signed_permission_tx
3. **Register pool**: MCP register_pool — register your TRON address as a selling pool
4. **Verify**: MCP check_pool_permissions — verify permissions on-chain
5. **Vote & earn**: MCP trigger_vote — vote for SRs to earn staking rewards
6. **Monitor**: MCP get_onchain_status, get_earnings — track performance and income

### MCP Integration:
Connect via Model Context Protocol at POST /mcp for tool-based interaction (27 tools).
New: Self-service onboarding, DEX token swap — register, authenticate, swap tokens, and grant permissions all within one MCP session.

## Endpoints
- POST /api/v2/agent/register — Start registration
- POST /api/v2/agent/verify — Verify signature
- POST /api/v2/agent/estimate — Estimate cost
- POST /api/v2/agent/buy-energy — Purchase energy (API key, TRX 402, or x402 USDC)
- GET /api/v2/agent/balance — Check balance
- GET /api/v2/agent/order/{orderId} — Order status
- GET /api/v2/agent/payment-status/{intentId} — 402 payment status
- POST /api/v2/agent/swap — Get swap quote (API key or TRX 402)
- POST /api/v2/agent/broadcast — Broadcast transaction (API key or TRX 402)
- POST /api/v1/paygo/estimate — Wallet integration: exact per-transfer fee quote (partner key)
- POST /api/v1/paygo/submit — Wallet integration: submit both signed transactions (partner key)
- GET /api/v1/paygo/order/{orderId} — Wallet integration: order status (partner key)
- POST /mcp — MCP tool endpoint

## Pricing
- Energy: from 50 SUN per unit per day
- Swap: energy cost only (~0.3 TRX per swap), no extra commission
- Typical TRC20 transfer: 65,000 energy (~3 TRX for 1 hour)
- Savings: 50-80% compared to TRX burn

## Supported Payment Networks
- TRON (tron:mainnet) — TRX native transfer
- Base (eip155:8453) — USDC via x402 v2 for buy-energy only

## SDKs & Integrations
- **TypeScript**: npm install @powersun/mcp-client — typed REST API client with HTTP 402 support
- **LangChain**: pip install langchain-powersun — 12 LangChain tools (PowerSunToolkit)
- **CrewAI**: pip install crewai-powersun — 9 CrewAI tools for multi-agent workflows
- **GitHub Action**: Hovsteder/tron-energy-action@v1 — rent Energy in CI/CD pipelines

## Links
- OpenAPI spec: /openapi.json
- Agent descriptor: /.well-known/agents.json
- npm: https://www.npmjs.com/package/@powersun/mcp-client
- PyPI (LangChain): https://pypi.org/project/langchain-powersun/
- PyPI (CrewAI): https://pypi.org/project/crewai-powersun/
- GitHub Action: https://github.com/Hovsteder/tron-energy-action
- GitHub MCP Server: https://github.com/Hovsteder/powersun-tron-mcp