# Suwappu

> Cross-chain DEX infrastructure. SDK, REST API, Telegram bot, and agent tooling for swaps, perps, predictions, and lending across 15 chains.

## Install

TypeScript:
```bash
bun add @suwappu/sdk
```

Python:
```bash
uv add suwappu
# or: pip install suwappu
```

## Authentication

Register for an API key:
```
POST https://api.suwappu.bot/v1/agent/register
```

Set the key in your environment:
```
SUWAPPU_API_KEY=your_key_here
```

## SDK Usage (TypeScript)

```typescript
import { createClient } from "@suwappu/sdk";

const client = createClient({ apiKey: process.env.SUWAPPU_API_KEY });

// Swaps
const quote = await client.getQuote("ETH", "USDC", 1.0, "arbitrum");
const tx = await client.executeSwap(quote.id);
const balances = await client.getPortfolio();

// Perps (Hyperliquid)
const markets = await client.perps.markets();
const perpQuote = await client.perps.quote("ETH-USD", "long", 1, 5);
const positions = await client.perps.positions("0x...");

// Predictions (Polymarket)
const predMarkets = await client.predict.markets("crypto");
const detail = await client.predict.market(predMarkets[0].id);

// Lending (Morpho on Base)
const lendMarkets = await client.lend.markets(8453);
const market = await client.lend.market(lendMarkets[0].id);
```

## SDK Usage (Python)

```python
from suwappu import create_client

client = create_client(api_key="your_key")

# Swaps
quote = await client.get_quote("ETH", "USDC", 1.0, "arbitrum")
tx = await client.execute_swap(quote.id)

# Perps
markets = await client.perps.markets()
perp_quote = await client.perps.quote("ETH-USD", "long", 1, 5)

# Predictions
pred_markets = await client.predict.markets("crypto")

# Lending
lend_markets = await client.lend.markets(chain_id=8453)
```

## Tools (13 total)

| Tool | Purpose | Parameters |
|------|---------|------------|
| `get_quote` | Best swap route for a token pair | `from_token, to_token, amount, chain` |
| `execute_swap` | Execute a previously quoted swap | `quote_id` |
| `get_portfolio` | Wallet balances across chains | `chain` (optional) |
| `get_prices` | Current token prices | `token, chain` (optional) |
| `list_chains` | All supported chains and status | none |
| `list_tokens` | Popular tokens on a chain | `chain` |
| `perps.markets` | Hyperliquid perp markets and prices | none |
| `perps.quote` | Quote a leveraged position | `market, side, size, leverage` |
| `perps.positions` | Open positions with PnL | `address` |
| `predict.markets` | Polymarket prediction markets | `query` (optional), `limit` (optional) |
| `predict.market` | Prediction market details | `id` |
| `lend.markets` | Morpho lending markets with APY | `chainId` (optional, default: Base) |
| `lend.market` | Lending market details | `id` |

## REST API

Base URL: `https://api.suwappu.bot`

### Swaps
```
POST /v1/agent/quote           { "fromToken", "toToken", "amount", "chain" }
POST /v1/agent/swap            { "quoteId": "..." }
GET  /v1/agent/portfolio       ?chain=arbitrum (optional)
GET  /v1/agent/prices          ?token=ETH&chain=arbitrum (optional)
GET  /v1/agent/chains
GET  /v1/agent/tokens          ?chain=arbitrum
POST /v1/agent/register
```

### Perps (Hyperliquid)
```
GET  /v1/agent/perps/markets
POST /v1/agent/perps/quote     { "market", "side", "size", "leverage" }
GET  /v1/agent/perps/positions ?address=0x...
```

### Predictions (Polymarket)
```
GET  /v1/agent/predict/markets ?query=crypto&limit=20
GET  /v1/agent/predict/market/:id
```

### Lending (Morpho)
```
GET  /v1/agent/lend/markets    ?chainId=8453
GET  /v1/agent/lend/market/:id
```

All endpoints require `Authorization: Bearer <SUWAPPU_API_KEY>` except `/health` and `/v1/agent/register`.

## Supported Chains

Ethereum, Arbitrum, Base, Optimism, Polygon, Avalanche, BNB Chain, Solana, Fantom, zkSync, Linea, Scroll, Blast, Gnosis, Aurora.

## Routing Providers

Li.Fi, Jupiter, CoW Protocol, Socket, 1inch, Wormhole, CCTP, Jito, Uniswap.

- EVM chains: Li.Fi, CoW Protocol, Socket, 1inch, Uniswap
- Solana: Jupiter, Jito
- Cross-chain bridges: Wormhole, CCTP
- MEV protection: CoW Protocol (EVM), Jito bundles (Solana) — enabled by default

## Wallets

Non-custodial. Powered by Turnkey TEE hardware. Private keys never leave the secure enclave. Users can export keys anytime.

## Typical Agent Flow

1. `list_chains` — discover available chains
2. `get_quote ETH USDC 1.0 arbitrum` — find best route and price
3. `execute_swap <quote_id>` — confirm and execute on-chain
4. `get_portfolio` — verify the swap landed

## Interfaces

The same routing engine powers:
- **Telegram bot**: [@suwappu_bot](https://t.me/suwappu_bot)
- **TypeScript SDK**: `bun add @suwappu/sdk`
- **Python SDK**: `uv add suwappu`
- **OpenClaw module**: `bun add @suwappu/openclaw`
- **REST API**: `api.suwappu.bot/v1/`
- **WhatsApp, Discord, iOS**: same wallet everywhere

## Agent Discovery

- Agent Card (A2A): https://api.suwappu.bot/.well-known/agent.json
- OpenAPI Spec: https://api.suwappu.bot/v1/agent/openapi
- MCP Endpoint: POST https://api.suwappu.bot/mcp (JSON-RPC 2.0, 11 tools)
- llms.txt: https://suwappu.bot/llms.txt

## MCP Server Setup

Add to Claude Desktop config:
```json
{
  "mcpServers": {
    "suwappu": {
      "url": "https://api.suwappu.bot/mcp",
      "headers": { "Authorization": "Bearer suwappu_sk_YOUR_KEY" }
    }
  }
}
```

Or via npm for local stdio:
```bash
SUWAPPU_API_KEY=suwappu_sk_YOUR_KEY npx @suwappu/mcp-server
```

## Links

- Bot: https://t.me/suwappu_bot
- API: https://api.suwappu.bot
- Docs: https://suwappu.bot/docs
- Homepage: https://suwappu.bot
- GitHub: https://github.com/0xSoftBoi/suwappubot