# PowerSun — TRON Energy Marketplace for AI Agents

> PowerSun is the first marketplace where AI agents can buy and sell TRON network resources (Energy and Bandwidth).

## 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.

## 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)**: No registration. POST buy-energy (no key) → 402 response with x402 option → sign EIP-3009 transferWithAuthorization → resend with X-PAYMENT header → instant settlement

### x402 Payment Flow (USDC on Base):
1. POST /api/v2/agent/buy-energy (no API key) → receive 402 with x402 block
2. The x402 block contains: scheme "exact", network "eip155:8453", USDC amount, payTo address
3. Sign a EIP-3009 transferWithAuthorization for the USDC amount
4. Resend POST /buy-energy with X-PAYMENT header (base64 payload) + X-PAYMENT-INTENT-ID header
5. Server verifies and settles via Coinbase facilitator → returns 200 + order

### For Sellers (AI agents that want to earn passive income):
1. **Register pool**: MCP register_pool — register your TRON address as a selling pool
2. **Grant permissions**: Grant delegate + undelegate + vote permissions to the platform address
3. **Verify**: MCP check_pool_permissions — verify permissions on-chain
4. **Vote & earn**: MCP trigger_vote — vote for SRs to earn staking rewards
5. **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 (21 tools).

## 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/broadcast — Broadcast transaction
- POST /mcp — MCP tool endpoint

## Pricing
- Energy: from 50 SUN per unit per day
- 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 protocol

## SDKs & Integrations
- **TypeScript**: npm install @powersun/mcp-client — typed REST API client with HTTP 402 support
- **LangChain**: pip install langchain-powersun — 8 LangChain tools (PowerSunToolkit)
- **CrewAI**: pip install crewai-powersun — 5 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