# PowerSun — Complete AI Agent Guide

> Full reference for integrating with the TRON Energy & Bandwidth marketplace and DEX swap aggregator.
> For a shorter overview, see /llms.txt

## Overview
PowerSun lets AI agents buy and sell TRON network resources (Energy and Bandwidth) and swap tokens on SunSwap DEX with automatic energy delegation.
Energy is required to execute smart contracts on TRON. Renting it saves 50-80% vs burning TRX.
Token swaps use SunSwap V2 Smart Router — PowerSun delegates energy for the swap transaction, so you only pay the energy rental cost instead of burning TRX.

## Base URL
https://powersun.vip

## Authentication Methods

### 1. API Key (recommended for repeat usage)
```
# Step 1: Register
POST /api/v2/agent/register
Content-Type: application/json
{"address": "TYourTronAddress..."}

# Response: {"challenge": "Sign this message: powersun-...", "expiresAt": "..."}

# Step 2: Verify signature
POST /api/v2/agent/verify
{"address": "TYourTronAddress...", "signature": "0x...hex..."}

# Response: {"apiKey": "ps_...", "address": "T..."}

# Step 3: Use API key in all requests
X-API-Key: ps_...
```

### 2. HTTP 402 Pay-per-use (TRX, no registration)
```
# Step 1: Request without API key
POST /api/v2/agent/buy-energy
{"targetAddress": "T...", "energyAmount": 65000, "duration": "1h"}

# Response: 402 Payment Required
# Body includes: intentId, depositAddress, requiredAmountTrx

# Step 2: Send TRX on TRON to depositAddress

# Step 3: Poll for completion
GET /api/v2/agent/payment-status/{intentId}
```

### 3. x402 USDC on Base (sync, no registration)
```
# Step 1: Request without API key → get 402 with x402 block
POST /api/v2/agent/buy-energy
{"targetAddress": "T...", "energyAmount": 65000, "duration": "1h"}

# Response 402 includes x402.paymentRequirements with:
#   scheme: "exact", network: "eip155:8453", maxAmountRequired (USDC atomic units)
#   payTo (0x address), asset (USDC on Base)

# Step 2: Sign EIP-3009 transferWithAuthorization for the USDC amount
# Step 3: Resend with headers:
POST /api/v2/agent/buy-energy
X-PAYMENT: <base64 encoded payment payload>
X-PAYMENT-INTENT-ID: pi_x402_...
{"targetAddress": "T...", "energyAmount": 65000, "duration": "1h"}

# Response: 200 with order details (instant)
```

## API Endpoints

### POST /api/v2/agent/estimate
Estimate cost before buying.
```
Request:  {"targetAddress": "T...", "energyAmount": 65000, "duration": "1h"}
Response: {"estimate": {"totalCostSun": 3250000, "totalCostTrx": 3.25, "pricePerUnit": 50, ...}}
```

### POST /api/v2/agent/buy-energy
Purchase energy delegation.
```
Request:  {"targetAddress": "T...", "energyAmount": 65000, "duration": "1h"}
Headers:  X-API-Key: ps_...
Response: {"order": {"orderId": "uuid", "status": "pending", ...}}
```

### GET /api/v2/agent/balance
Check account balance and deposit info.
```
Headers:  X-API-Key: ps_...
Response: {"address": "T...", "balanceTrx": 15.5, "balanceSun": 15500000, ...}
```

### GET /api/v2/agent/order/{orderId}
Track order status and delegation progress.

### GET /api/v2/agent/payment-status/{intentId}
Poll 402 payment intent status (no auth needed).

### POST /api/v2/agent/broadcast
Broadcast a pre-signed TRON transaction with automatic energy delegation.
Three modes: API key (balance deduction), x402 (USDC on Base, instant), or no auth (returns 402 with cost estimate).
\`\`\`
Request body: Pre-signed TRON transaction object {txID, raw_data, raw_data_hex, signature}
With X-API-Key: broadcasts immediately, cost deducted from balance
With X-PAYMENT + X-PAYMENT-INTENT-ID: x402 USDC settlement + broadcast
Without auth: 402 response with energy cost estimate and payment options
\`\`\`

### POST /api/v2/agent/swap
Get swap quote for SunSwap DEX with energy cost estimate.
\`\`\`
Request:  {"fromToken": "TRX", "toToken": "USDT", "amountIn": "10000000", "slippageBps": 100}
Headers:  X-API-Key: ps_...
Response: {
  "quote": {"fromSymbol": "TRX", "toSymbol": "USDT", "expectedAmountOut": "...", "amountOutMin": "...", "route": [...]},
  "energy": {"estimatedUnits": 350000, "costSun": 17500000, "costTrx": 17.5},
  "unsignedTx": {...},
  "nextAction": {"action": "sign_and_broadcast", "broadcastUrl": "/api/v2/agent/broadcast"}
}
\`\`\`
Supported tokens: TRX, USDT, USDC, USDD, SUN, BTT, WIN, JST, or any TRC-20 contract address.

## MCP Tools (27 total)

Connect: POST /mcp (Streamable HTTP transport)
Optional auth: X-API-Key header (or use register + verify_registration to get one)

### Onboarding Tools (public, no auth needed to start):
- **register** — Start agent registration with TRON address, get challenge to sign
- **verify_registration** — Verify signed challenge, receive API key, session upgraded in-place
- **build_permission_transaction** — Build unsigned AccountPermissionUpdate tx for granting platform permissions (auth required)
- **broadcast_signed_permission_tx** — Broadcast signed permission tx and verify on-chain (auth required)

### Market Tools (public, no auth):
- **get_prices** — Current energy/bandwidth prices for all duration tiers
- **estimate_cost** — Calculate cost for a specific energy/bandwidth amount and duration
- **get_available_resources** — Check available energy/bandwidth in the marketplace
- **get_market_overview** — Full market snapshot (prices + availability + order stats)

### Buyer Tools (auth required):
- **get_balance** — Account balance and deposit address
- **buy_energy** — Purchase energy delegation for a target address
- **broadcast_transaction** — Broadcast pre-signed TRON tx with energy
- **get_orders** — List your recent orders
- **get_order_status** — Detailed order status with fills
- **get_deposit_info** — Get deposit address and payment instructions

### Swap Tools (auth required):
- **get_swap_quote** — Get price quote and unsigned TX for SunSwap DEX token swap (TRX, USDT, USDC, SUN, BTT, WIN, JST, any TRC-20)
- **execute_swap** — Execute pre-signed swap TX with automatic energy delegation

### Seller Tools (auth required):
- **register_pool** — Register TRON address as a selling pool
- **get_pool_stats** — Pool performance and delegation stats
- **get_earnings** — Earnings breakdown and history
- **get_auto_selling_config** — Current auto-selling configuration
- **configure_auto_selling** — Enable/disable auto-selling with price settings
- **get_pool_delegations** — Active delegations from your pool
- **withdraw_earnings** — Withdraw earned TRX to your wallet
- **get_onchain_status** — Live blockchain state (balance, frozen, votes, rewards)
- **check_pool_permissions** — Verify platform has required on-chain permissions
- **trigger_vote** — Vote for Super Representative to earn staking rewards
- **get_auto_action_history** — View auto-action execution logs (stake, vote, claim)

## Pricing
- Energy: from 50 SUN per unit per day
- Typical TRC20 transfer: ~65,000 energy (~3 TRX for 1 hour)
- DEX swap: ~350,000 energy (~0.3 TRX energy cost), no extra commission
- Savings: 50-80% compared to TRX burn
- Available durations: 1h, 3h, 6h, 12h, 1d, 3d, 7d, 14d, 30d

## Rate Limits
- Authenticated: 100 req/min
- Unauthenticated: 20 req/min
- MCP sessions: no hard limit (fair use)

## Error Codes
- 400: Bad request (missing/invalid parameters)
- 401: Unauthorized (invalid or missing API key)
- 402: Payment Required (use 402 flow or x402)
- 404: Resource not found
- 429: Rate limit exceeded
- 500: Internal server error

## Supported Networks
- TRON mainnet (tron:mainnet) — TRX native transfers
- Base (eip155:8453) — USDC via x402 protocol (contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

## SDKs & Integrations

### TypeScript (npm)
\`\`\`bash
npm install @powersun/mcp-client
\`\`\`
\`\`\`typescript
import { PowerSun, PaymentRequiredError } from '@powersun/mcp-client';
const ps = new PowerSun({ apiKey: 'ps_...' });

// Market data (no auth)
const prices = await ps.market.getPrices();
const estimate = await ps.market.estimateCost({ txCount: 10, durationMinutes: 60 });

// Buy energy
const order = await ps.buyer.buyEnergy({ targetAddress: 'T...', txCount: 5, durationMinutes: 60 });

// HTTP 402 flow (no API key)
const ps402 = new PowerSun();
try { await ps402.buyer.buyEnergy({ targetAddress: 'T...', txCount: 1 }); }
catch (err) {
  if (err instanceof PaymentRequiredError) {
    // err.payment.depositAddress, err.payment.requiredAmountTrx
  }
}
\`\`\`

### LangChain (PyPI)
\`\`\`bash
pip install langchain-powersun
\`\`\`
\`\`\`python
from langchain_powersun import PowerSunToolkit
tools = PowerSunToolkit(api_key="ps_...").get_tools()  # 12 tools
# Use with create_react_agent or create_tool_calling_agent
\`\`\`

### CrewAI (PyPI)
\`\`\`bash
pip install crewai-powersun
\`\`\`
\`\`\`python
from crewai_powersun import PowerSunBuyEnergyTool, PowerSunEstimateCostTool
# Use directly in CrewAI Agent tools=[...]
# Supports POWERSUN_API_KEY env var
\`\`\`

### GitHub Action
\`\`\`yaml
- uses: Hovsteder/tron-energy-action@v1
  with:
    target-address: ${{ secrets.DEPLOYER_ADDRESS }}
    tx-count: '10'
    api-key: ${{ secrets.POWERSUN_API_KEY }}
\`\`\`

## Discovery Files
- OpenAPI spec: /openapi.json
- Short LLM guide: /llms.txt
- Full LLM guide: /llms-full.txt (this file)
- Agent descriptor: /.well-known/agents.json
- AI plugin manifest: /.well-known/ai-plugin.json

## SDK Links
- 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