# ClawSwap API

ClawSwap is an AI agent-first cross-chain swap platform enabling bidirectional token swaps between Solana and Base.

## What ClawSwap Does

Execute cross-chain token swaps between Solana and Base in both directions:
- Solana → Base: Swap tokens from Solana to Base (requires $0.50 USDC x402 payment)
- Base → Solana: Swap tokens from Base to Solana (FREE, no x402 payment required)

## Key Features

- **Zero Gas for Users**: Server sponsors all Solana gas fees (users reimburse ~$0.001 USDC via swap tx)
- **No ETH Needed**: Users pay Base gas directly (~$0.001 ETH), no upfront ETH required
- **Fast Settlement**: Average 30 seconds for cross-chain finality
- **x402 Payment Model**: Pay-per-use, no subscriptions ($0.50 for Solana→Base, FREE for Base→Solana)
- **Type-Safe SDK**: TypeScript SDK available at npm: @clawswap/sdk
- **OpenAPI 3.0**: Full API specification for auto-generating clients

## API Base URL

https://api.clawswap.dev

## Quick Start for AI Agents

### 1. Get a Quote (Free)
```bash
curl -X POST https://api.clawswap.dev/api/swap/quote \
  -H "Content-Type: application/json" \
  -d '{
    "sourceChainId": "solana",
    "destinationChainId": "base",
    "sourceTokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "destinationTokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000000",
    "senderAddress": "YOUR_SOLANA_WALLET",
    "recipientAddress": "YOUR_BASE_WALLET"
  }'
```

### 2. Execute Swap (x402 Payment for Solana→Base Only)
For Solana→Base swaps, use @x402/fetch to handle the $0.50 USDC payment automatically.
For Base→Solana swaps, use regular fetch (no payment required).

### 3. Poll Status (Free)
```bash
curl https://api.clawswap.dev/api/swap/{orderId}/status
```

## Core Endpoints

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| /api/chains | GET | None | List supported chains (Solana, Base) |
| /api/tokens/{chain} | GET | None | List available tokens for a chain |
| /api/swap/quote | POST | None | Get swap quote with fee breakdown |
| /api/swap/execute | POST | x402 (Solana-source only) | Execute cross-chain swap |
| /api/swap/{id}/status | GET | None | Poll swap status |

## Supported Chains

- **Solana** (mainnet-beta)
- **Base** (mainnet)

## Common Token Addresses

### Solana
- USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
- USDT: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
- SOL/WSOL: So11111111111111111111111111111111111111112

### Base
- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Use `/api/tokens/{chain}` for the complete, up-to-date token list.

## Fee Structure

### Solana → Base
- x402 protocol fee: $0.50 USDC (on Solana)
- Gas reimbursement: ~$0.001 USDC (included in swap transaction)
- Bridge fee: ~$0.03-0.05 (deducted from amount)
- **Total: ~$0.53-0.55**

### Base → Solana
- x402 protocol fee: **FREE**
- User pays Base gas: ~$0.001 ETH (paid directly on Base)
- Bridge fee: ~$0.03-0.05 (deducted from amount)
- **Total: ~$0.03-0.05 + gas**

## Important Notes for Agents

1. **x402 Payment**: Only required for Solana→Base swaps. Use @x402/fetch wrapper for automatic payment handling.
2. **Base→Solana is FREE**: No x402 payment needed, just regular HTTP fetch.
3. **Quote Expiry**: Quotes are valid for 30 seconds. The execute endpoint fetches a fresh quote internally, so no expiry concerns.
4. **Status Polling**: Poll every 5 seconds. Average settlement time is 30 seconds.
5. **Gas Field (Base→Solana)**: Always pass the `gas` field from the API response to avoid intermittent failures.
6. **Response Format Difference**:
   - Solana→Base returns `transaction` (singular, base64 string)
   - Base→Solana returns `transactions` (plural, array of EVM transactions)

## Status Values

- `pending` - Order created, waiting for source transaction
- `created` - Source transaction submitted
- `fulfilled` - Swap completed successfully ✓
- `completed` - All confirmations done ✓
- `cancelled` - Order cancelled or refunded
- `failed` - Swap failed

## Integration Options

1. **TypeScript SDK** (Recommended): npm install @clawswap/sdk
   - Type safety, convenience wrappers, automatic retry logic
   - NPM: https://www.npmjs.com/package/@clawswap/sdk
   - GitHub: https://github.com/Wartech9/clawswap-sdk

2. **Direct REST API**: Use standard fetch/axios with @x402/fetch for payments
   - Full control, framework-agnostic
   - See examples: https://clawswap.dev/docs/api

3. **MCP Server** (Coming Soon): For Claude Desktop integration
   - @clawswap/mcp-server (in development)

## Resources

- **Documentation**: https://clawswap.dev/docs
- **API Reference**: https://api.clawswap.dev/docs
- **OpenAPI Spec**: https://api.clawswap.dev/api/openapi
- **SDK Guide**: https://clawswap.dev/docs/sdk
- **API Integration Guide**: https://clawswap.dev/docs/api
- **Agent Integration**: https://clawswap.dev/docs/agents
- **GitHub**: https://github.com/Wartech9/clawswap-sdk
- **Support**: https://github.com/Wartech9/clawswap-sdk/issues

## Example: Natural Language to API

User: "Swap 10 USDC from Solana to Base"

Agent Actions:
1. Call /api/swap/quote to get expected output and fees
2. Use @x402/fetch to call /api/swap/execute (handles $0.50 payment)
3. Sign the returned transaction with user's Solana wallet
4. Submit to Solana network
5. Poll /api/swap/{orderId}/status every 5 seconds until completed
6. Inform user of destination transaction hash

## Discovery

ClawSwap is designed for AI agent discovery through:
- This llms.txt file (AI-readable service description)
- OpenAPI 3.0 specification (machine-readable API contract)
- x402 Bazaar service registry (coming soon)
- AgentKit plugin registry (coming soon)

---

Last Updated: 2026-02-20
Version: 0.1.0