npm package: @powersun/mcp-client
Description: TypeScript SDK for PowerSun.vip — TRON Energy & Bandwidth marketplace and DEX swap aggregator with 27 MCP tools. Register, buy energy, swap tokens, sell resources, earn passive income.
Author: PowerSun.vip
Latest version: 1.3.0

# @powersun/mcp-client

TypeScript SDK for [PowerSun.vip](https://powersun.vip) — the TRON Energy & Bandwidth marketplace and DEX swap aggregator with 27 MCP tools for AI agents.

## Install

```bash
npm install @powersun/mcp-client
```

## Quick Start

```typescript
import { PowerSun } from '@powersun/mcp-client';

// Public access (market data, estimates)
const ps = new PowerSun();
const prices = await ps.market.getPrices();
const estimate = await ps.market.estimateCost({
  txCount: 10,
  txType: 'trc20_transfer',
  durationMinutes: 60,
});

// Authenticated access (buy energy, check balance)
const client = new PowerSun({ apiKey: 'ps_your_key_here' });
const balance = await client.buyer.getBalance();
const order = await client.buyer.buyEnergy({
  targetAddress: 'TYourAddressHere...',
  txCount: 5,
  durationMinutes: 60,
});
```

## HTTP 402 Pay-per-use (No Registration)

```typescript
import { PowerSun, PaymentRequiredError } from '@powersun/mcp-client';

const ps = new PowerSun(); // no API key

try {
  await ps.buyer.buyEnergy({
    targetAddress: 'TYourAddressHere...',
    txCount: 1,
    durationMinutes: 5,
  });
} catch (err) {
  if (err instanceof PaymentRequiredError) {
    // Send TRX to the deposit address
    console.log('Deposit address:', err.payment.depositAddress);
    console.log('Amount (TRX):', err.payment.requiredAmountTrx);

    // Poll for payment confirmation
    const status = await ps.paymentStatus(err.payment.intentId);
    console.log('Payment status:', status.status);
  }
}
```

## Registration

```typescript
const ps = new PowerSun();

// Step 1: Get challenge
const { challengeId, challenge } = await ps.register('TYourAddress...');

// Step 2: Sign challenge with TronLink / tronWeb
const signature = await tronWeb.trx.signMessageV2(challenge);

// Step 3: Verify and get API key
const { apiKey } = await ps.verify(challengeId, 'TYourAddress...', signature);

// Step 4: Use authenticated client
const client = new PowerSun({ apiKey });
```

## Token Swap (SunSwap DEX)

```typescript
const client = new PowerSun({ apiKey: 'ps_your_key_here' });

// Get swap quote (TRX → USDT)
const quote = await client.swap.getQuote({
  fromToken: 'TRX',
  toToken: 'USDT',
  amountIn: '10000000', // 10 TRX in SUN
  slippageBps: 100,     // 1% slippage
});

console.log('Expected output:', quote.quote.expectedAmountOut);
console.log('Energy cost:', quote.energy.costTrx, 'TRX');

// Sign the unsigned TX with tronWeb
const signedTx = await tronWeb.trx.sign(quote.unsignedTx);

// Broadcast with automatic energy delegation
const result = await client.buyer.broadcast({ txData: signedTx });
```

## API Reference

### `new PowerSun(config?)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | — | API key (`ps_*` format) |
| `baseUrl` | `string` | `https://powersun.vip` | API base URL |
| `timeout` | `number` | `30000` | Request timeout (ms) |

### Market (public)

- `ps.market.getPrices()` — Price tiers for all durations
- `ps.market.estimateCost(params)` — Cost estimate
- `ps.market.getAvailableResources()` — Available energy/bandwidth
- `ps.market.getOverview()` — Full market snapshot

### Buyer (auth recommended)

- `ps.buyer.buyEnergy(params)` — Purchase energy (API key, 402, or x402)
- `ps.buyer.getBalance()` — Account balance
- `ps.buyer.getOrderStatus(orderId)` — Order details
- `ps.buyer.broadcast(params)` — Broadcast pre-signed tx with auto Energy (API key, x402, or 402 pay-per-use)

### Swap (auth recommended)

- `ps.swap.getQuote(params)` — Get swap quote with unsigned TX for SunSwap DEX (API key, x402, or 402)

### Registration (public)

- `ps.register(address)` — Start registration
- `ps.verify(challengeId, address, signature)` — Verify & get API key
- `ps.paymentStatus(intentId)` — Check 402 payment status

## Links

- **Platform:** [powersun.vip](https://powersun.vip)
- **MCP Server:** [powersun.vip/mcp](https://powersun.vip/mcp)
- **API Docs:** [powersun.vip/api-docs](https://powersun.vip/api-docs)

## License

MIT