# Wenrwa Trading Platform — Full Integration Guide

> AI-powered Solana trading with automated strategies, 90+ real world assets (RWA), and programmatic SDK access.

- Trading App: https://app.wenrwa.com
- API Base URL: https://app.wenrwa.com/api/v1/sdk
- Agent Marketplace: https://marketplace.wenrwa.com
- MCP Package: @wenrwa/mcp-server (npm)
- Trading SDK: @wenrwa/trading-sdk (npm)
- Summary: https://app.wenrwa.com/llms.txt
- Marketplace Docs: https://marketplace.wenrwa.com/llms.txt

---

## Agent Quickstart

Follow these four steps to go from zero to trading programmatically.

### Step 1: Create a Solana Wallet

Every participant needs a Solana wallet (keypair = private key + public address).

```typescript
// TypeScript — generate and save a keypair
import { Keypair } from '@solana/web3.js';
import fs from 'fs';

const keypair = Keypair.generate();
console.log('Public key:', keypair.publicKey.toBase58());

// Save the secret key to a file (keep this safe!)
fs.writeFileSync(
  'agent-keypair.json',
  JSON.stringify(Array.from(keypair.secretKey))
);
```

```python
# Python — generate and save a keypair
from solders.keypair import Keypair
import json

keypair = Keypair()
print('Public key:', str(keypair.pubkey()))

with open('agent-keypair.json', 'w') as f:
    json.dump(list(bytes(keypair)), f)
```

```bash
# Or use the Solana CLI
solana-keygen new --outfile agent-keypair.json
solana address -k agent-keypair.json
```

Important:
- Store agent-keypair.json securely — anyone with this file controls the wallet
- Never commit it to git. Add it to .gitignore
- For production, use environment variables or a secrets manager

### Step 2: Fund Your Wallet

You need SOL or USDC to start trading. **USDC swaps are gasless** — no SOL required. The platform wallet signs as the Solana transaction fee payer. A dynamic USDC convenience fee applies ($0.10 if you already hold the output token, or a dynamic fee based on current SOL price — minimum $0.50 — if first time receiving that token).

| Method | Fee | Best for |
|--------|-----|----------|
| Transfer from an exchange (Coinbase, Binance, Kraken) | 0.1-0.5% | Cheapest option — most developers already have exchange accounts |
| Transfer from another wallet (Phantom, Solflare) | Network fee only | Moving funds between your own wallets |
| Onramper widget (browser) | 1-4.5% | First-time users at app.wenrwa.com — supports cards, bank transfers, Apple Pay |
| MoonPay Agents CLI (programmatic) | 1-4.5% | Autonomous agents: `npm i -g @moonpay/cli && mp buy --token SOL --amount 100 --wallet <addr> --email <email>` |

- **Devnet (testing):** `solana airdrop 1 --url devnet` — free, no KYC
- **MoonPay Agents note:** A human must complete one-time KYC, then the agent can buy crypto programmatically via CLI. See https://agents.moonpay.com
- Once registered (Step 3), you can also swap SOL for USDC or any other token via the SDK

### Step 3: Register & Get an API Key

**Option A: New wallet (recommended)** — The platform generates a fresh trading wallet for you:

```bash
# curl (no auth header needed — rate-limited by IP)
curl -X POST https://app.wenrwa.com/api/v1/sdk/register \
  -H "Content-Type: application/json" \
  -d '{"mainWalletPubkey": "YOUR_SOLANA_PUBLIC_KEY", "name": "My Trading Bot"}'
```
```json
{
  "success": true,
  "apiKey": "wen_a1b2c3d4...",
  "publicKey": "TradingWalletPubKey...",
  "secretKey": "base64-trading-wallet-secret-key",
  "tradingWalletId": 1
}
```
Save `apiKey` AND `secretKey` — both are only shown once.
- `apiKey` (`wen_...`) — use as `X-API-Key` header for all subsequent requests
- `secretKey` — your trading wallet's private key, needed for signing swaps and transfers

```typescript
// Same thing via SDK
import { TradingClient } from '@wenrwa/trading-sdk';

const client = new TradingClient({ apiUrl: 'https://app.wenrwa.com/api/v1' });

const { apiKey, publicKey, secretKey } = await client.register({
  mainWalletPubkey: 'YourSolanaPublicKey...',
  name: 'My Trading Bot',
});
// Save apiKey and secretKey — they're only shown once!
```

```python
# Python — using requests
import requests

resp = requests.post('https://app.wenrwa.com/api/v1/sdk/register', json={
    'mainWalletPubkey': 'YOUR_SOLANA_PUBLIC_KEY',
    'name': 'My Trading Bot',
})
data = resp.json()
api_key = data['apiKey']       # wen_... — save this
secret_key = data['secretKey'] # trading wallet private key — save this
```

**Option B: Existing wallet** — Bring your own funded wallet and prove ownership:

```bash
curl -X POST https://app.wenrwa.com/api/v1/sdk/register/existing \
  -H "Content-Type: application/json" \
  -d '{"mainWalletPubkey": "YOUR_MAIN_WALLET", "tradingWalletPubkey": "YOUR_TRADING_WALLET", "signature": "...", "timestamp": 1708000000}'
```
The `signature` must sign: `"Wenrwa SDK Registration\nWallet: <pubkey>\nTimestamp: <ts>"` with your trading wallet's private key. You keep your own `secretKey` since you already have the wallet.

**Option C:** Generate keys from the Wenrwa app's Account Settings page (browser).

### Step 4: Start Trading

```typescript
const authedClient = new TradingClient({
  apiUrl: 'https://app.wenrwa.com/api/v1',
  apiKey,       // wen_... key from Step 3 registration
});

// Swap 0.1 SOL -> USDC
const swap = await authedClient.swap({
  inputMint: 'So11111111111111111111111111111111111111112',
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: '100000000',
  walletSecretKey: secretKey,
});
console.log('Swapped! Tx:', swap.signature);

// Check balances
const balance = await authedClient.getBalance();
console.log(balance.balances);
```

---

## Four Integration Methods

Wenrwa provides four ways to trade programmatically. All use the same backend and the same API key.

1. Agent Skills — wenrwa-agent-skills — 5 Claude Code skills with auto-configured MCP servers
2. MCP Server — Connect Claude or any MCP-compatible AI agent to 26 trading tools
3. Trading SDK — @wenrwa/trading-sdk TypeScript package with zero runtime dependencies
4. REST API — Standard HTTP endpoints at /api/v1/sdk/* with API key auth

---

## MCP Server Setup

The MCP server lets Claude and AI agents call Wenrwa trading tools directly. It exposes 26 tools for swapping, transfers, cart/batch operations, wallet management, RWA token discovery, and agent identity management.

### Claude Desktop

Add this to your Claude Desktop MCP server configuration:

```json
// Replace with your wen_... key from Step 3
{
  "wenrwa": {
    "command": "npx",
    "args": ["@wenrwa/mcp-server"],
    "env": {
      "WENRWA_API_KEY": "wen_your-api-key-from-step-3",
      "WENRWA_API_URL": "https://app.wenrwa.com/api/v1/sdk"
    }
  }
}
```

### Claude Code

```bash
# Replace with your wen_... key from Step 3
claude mcp add wenrwa \
  -e WENRWA_API_KEY=wen_your-api-key-from-step-3 \
  -e WENRWA_API_URL=https://app.wenrwa.com/api/v1/sdk \
  -- npx @wenrwa/mcp-server
```

### Environment Variables

- WENRWA_API_KEY (required) — Your `wen_...` API key from Step 3 registration
- WENRWA_API_URL (optional) — API base URL, defaults to https://app.wenrwa.com/api/v1/sdk

### MCP Tool Reference — 26 Tools

Account & Wallet Tools:
- wenrwa_account — Get account info, API key details, wallet, permissions
- wenrwa_get_balance — Get token balances for the default trading wallet
- wenrwa_get_balance_by_wallet — Get token balances for a specific wallet by ID (walletId: number)
- wenrwa_create_wallet — Create a new trading wallet (name: string, optional)
- wenrwa_list_wallets — List all trading wallets for the current account
- wenrwa_get_transactions — Get transaction history (limit, offset: number, optional)

Token Tools:
- wenrwa_search_tokens — Search tokens by symbol or name (query: string)
- wenrwa_get_token_info — Get detailed token info by mint address (mint: string)

Swap Tools:
- wenrwa_get_quote — Get a swap quote without executing (inputMint, outputMint, amount; slippageBps optional)
- wenrwa_swap — Execute a one-step swap (inputMint, outputMint, amount, walletSecretKey; slippageBps optional, default 50)
- wenrwa_swap_build — Build unsigned swap transaction (inputMint, outputMint, amount; slippageBps optional)
- wenrwa_swap_submit — Submit a signed swap transaction (signedTransaction: base64 string)
- wenrwa_transfer — Send tokens to another wallet (mint, recipientAddress, amount, walletSecretKey)

Cart Tools (Batch Swaps):
- wenrwa_cart_add — Add a swap to the cart (inputMint, outputMint, amount; slippageBps optional)
- wenrwa_cart_list — List all pending cart items
- wenrwa_cart_update — Update a cart item (itemId; inputMint, outputMint, amount, slippageBps optional)
- wenrwa_cart_remove — Remove a single item from the cart (itemId: number)
- wenrwa_cart_clear — Remove all pending items from the cart
- wenrwa_cart_execute — Execute all cart items as batch (walletSecretKey; continueOnError: boolean optional)

RWA (Real World Asset) Tools:
- wenrwa_rwa_list_tokens — List/filter RWA tokens (category, provider, minLiquidity, search, sortBy, sortOrder — all optional)
- wenrwa_rwa_get_token — Get detailed info for a single RWA token (mint: string)
- wenrwa_rwa_categories — List RWA categories with token counts
- wenrwa_rwa_providers — List RWA providers/issuers with token counts
- wenrwa_rwa_knowledge — Get knowledge entry: risks, fees, trading hours, redemption (mint or symbol)

Agent Identity Tools:
- wenrwa_setup — Set up a Wenrwa agent identity: generates Solana keypair, registers with SDK API, saves credentials to disk (name: string, keypairPath: string optional, apiUrl: string optional)
- wenrwa_list_agents — List all Wenrwa agent identities on this machine with optional wallet balances (includeBalances: boolean optional)

All MCP tools accept token symbols ("SOL", "USDC") or raw mint addresses interchangeably.

---

## Trading SDK Reference

Install:

```bash
npm install @wenrwa/trading-sdk
```

Constructor:

```typescript
import { TradingClient } from '@wenrwa/trading-sdk';

const client = new TradingClient({
  apiUrl: 'https://app.wenrwa.com/api/v1',  // Required
  apiKey: apiKey,                            // wen_... key from Step 3 registration
});
```

### Swap — Three Modes

```typescript
// All-in-one: build + sign + submit (simplest)
const result = await client.swap({
  inputMint: 'SOL-mint-address',
  outputMint: 'USDC-mint-address',
  amount: '100000000',          // 0.1 SOL in lamports
  walletSecretKey: secretKey,   // from Step 3 registration
  slippageBps: 50,              // Optional (0.5%)
});
// Returns: { signature, status, inputAmount, outputAmount, feeAmount }

// Build-only: get unsigned transaction for external signing
const built = await client.buildSwap({
  inputMint: '...', outputMint: '...', amount: '100000000',
});
// Returns: { transaction, quote, lastValidBlockHeight }

// Submit a pre-signed transaction
const submitted = await client.submitSwap({
  signedTransaction: '...',     // Base64-encoded signed transaction
});
```

### Transfer

```typescript
const result = await client.transfer({
  mint: 'USDC-mint-address',
  recipientAddress: 'RecipientWallet...',
  amount: '1000000',            // 1 USDC (6 decimals)
  walletSecretKey: secretKey,   // from Step 3 registration
});
// Returns: { signature, status, amountSent, feeAmount }
```

### Cart / Batch Swaps

```typescript
// Add items to cart
await client.addCartItem({
  inputMint: 'SOL-mint', outputMint: 'USDC-mint',
  amount: '100000000', slippageBps: 50,
});
await client.addCartItem({
  inputMint: 'SOL-mint', outputMint: 'BONK-mint',
  amount: '50000000',
});

// View, update, remove
const cart = await client.getCart();
await client.updateCartItem(cart.items[0].id, { amount: '200000000' });
await client.removeCartItem(cart.items[1].id);

// Execute all cart items
const results = await client.executeCart({
  walletSecretKey: secretKey,   // from Step 3 registration
  continueOnError: true,        // Continue if one swap fails
});
// Returns: { results: [...], totalExecuted, totalSucceeded, totalFailed }

// Or clear the whole cart
await client.clearCart();
```

### Balance & Tokens

```typescript
// Check balances
const balance = await client.getBalance();
// Returns: { walletPubkey, balances: [{ symbol, uiAmount, ... }] }

// Balance for a specific wallet
const balance2 = await client.getBalanceByWalletId(2);

// Search tokens
const results = await client.searchTokens('USDC');

// Token info by mint
const info = await client.getTokenInfo('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');

// Transaction history
const txs = await client.getTransactions({ limit: 20, offset: 0 });

// Get status of a specific transaction by signature
const status = await client.getTransactionStatus('5x2YrL...');
// Returns: { signature, status, inputMint, outputMint, amount, ... }
```

### Wallets

```typescript
// Create additional trading wallet
const wallet = await client.createWallet({ name: 'Arbitrage Bot' });
// Returns: { publicKey, secretKey, tradingWalletId }

// List all wallets
const wallets = await client.listWallets();
// Returns: { wallets: [{ tradingWalletId, publicKey, name, type }] }

// Generate a new API key (from an existing authenticated session)
const { apiKey } = await client.generateKey();
// Returns: { apiKey } — save it, only shown once
```

### Webhooks

```typescript
// Set webhook URL
const { webhookUrl, webhookSecret } = await client.setWebhook({
  url: 'https://my-server.com/webhook',
});

// Test it
await client.testWebhook();

// Remove it
await client.deleteWebhook();
```

Webhook events (POST with JSON body):
- transaction.confirmed — A swap or transfer completed successfully
- transaction.failed — A swap or transfer failed
- test — Test event from testWebhook()

Verify webhook authenticity using the webhookSecret returned from setWebhook().

---

## Complete REST API Endpoints

All SDK-authenticated endpoints are at https://app.wenrwa.com/api/v1/sdk/
Authenticate with the X-API-Key header.

### Examples

```bash
# Get balance (use wen_... API key from Step 3)
curl -H "X-API-Key: wen_a1b2c3d4..." \
  https://app.wenrwa.com/api/v1/sdk/balance

# Search tokens
curl -H "X-API-Key: wen_a1b2c3d4..." \
  "https://app.wenrwa.com/api/v1/sdk/tokens/search?query=USDC"

# Execute a swap (walletSecretKey is the secretKey from Step 3 registration)
curl -X POST -H "X-API-Key: wen_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"inputMint":"So11111111111111111111111111111111111111112","outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"100000000","walletSecretKey":"YOUR_SECRET_KEY_FROM_STEP_3"}' \
  https://app.wenrwa.com/api/v1/sdk/swap
```

### All 30 Endpoints

Account & Auth:
  GET    /account                    — Account info, permissions, wallet addresses
  POST   /register                   — Register new wallet, get API key (no auth required)
  POST   /register/existing          — Register existing wallet with signature (no auth required)
  POST   /keys/generate              — Generate a new API key (requires existing API key auth)

Swaps:
  POST   /swap                       — Execute one-step swap
  POST   /swap/build                 — Build unsigned swap transaction
  POST   /swap/submit                — Submit signed swap transaction
  POST   /transfer                   — Transfer tokens to another wallet
  GET    /quote                      — Get swap quote without executing

Balances & Tokens:
  GET    /balance                    — Get default wallet balances
  GET    /balance/:walletId          — Get specific wallet balances by ID
  GET    /tokens/search              — Search tokens by name or symbol
  GET    /tokens/:mint               — Get token info by mint address
  GET    /transactions               — List transaction history (limit, offset)
  GET    /transactions/:signature    — Get status of a specific transaction

Wallets:
  POST   /wallets                    — Create a new trading wallet
  GET    /wallets                    — List all trading wallets

Cart (Batch Swaps):
  POST   /cart/items                 — Add item to cart
  GET    /cart                       — List cart items
  PUT    /cart/items/:id             — Update cart item
  DELETE /cart/items/:id             — Remove cart item
  DELETE /cart                       — Clear entire cart
  POST   /cart/execute               — Execute all cart items as batch

Webhooks:
  PUT    /account/webhook            — Set webhook URL
  DELETE /account/webhook            — Remove webhook
  POST   /account/webhook/test       — Send test webhook event

RWA (Real World Assets):
  GET    /rwa/tokens                 — List/filter RWA tokens
  GET    /rwa/tokens/:mint           — Get single RWA token details
  GET    /rwa/categories             — List RWA categories with counts
  GET    /rwa/providers              — List RWA providers with counts
  GET    /rwa/knowledge/:mint        — Get RWA knowledge entry by mint
  GET    /rwa/knowledge/symbol/:symbol — Get RWA knowledge entry by symbol

---

## Authentication

All authenticated endpoints require the X-API-Key header with the `wen_...` key from Step 3 registration:

```
X-API-Key: wen_a1b2c3d4...
```

Registration endpoints (`POST /register` and `POST /register/existing`) do not require an API key — they are how you GET an API key. They are IP rate-limited.

### API Key Permissions

Each API key has scoped permissions:
- swap — Required for swap, swap/build, swap/submit
- transfer — Required for transfer
- balance — Required for balance endpoints
- quote — Required for quote
- cart — Required for all cart/* endpoints
- wallet — Required for create/list wallets

Token search, token info, account info, transaction history, and all RWA tools are available to any valid API key without additional permissions.

---

## Idempotency

Pass an Idempotency-Key header (or idempotencyKey body param) with a unique string per operation to safely retry failed requests without risking duplicate swaps or transfers.

```bash
curl -X POST -H "X-API-Key: wen_a1b2c3d4..." \
  -H "Idempotency-Key: unique-uuid-per-request" \
  -H "Content-Type: application/json" \
  -d '{"inputMint":"So11111111111111111111111111111111111111112","outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"100000000","walletSecretKey":"YOUR_SECRET_KEY_FROM_STEP_3"}' \
  https://app.wenrwa.com/api/v1/sdk/swap
```

```typescript
const result = await client.swap({
  inputMint: 'So11111111111111111111111111111111111111112',
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: '100000000',
  walletSecretKey: secretKey,  // from Step 3 registration
  idempotencyKey: 'my-unique-key-123',
});
```

---

## Fee Structure

- Swap fee: 0.2% (20 basis points) per successful swap, including each swap in a batch cart execution
- Gasless USDC fee: dynamic USDC per swap when wallet has no SOL for gas ($0.10 if output token account exists, dynamic fee min $0.50 if it must be created — scales with SOL price to cover ATA rent; platform signs as fee payer; fee deducted from USDC swap input; only applies to USDC input swaps where user has insufficient SOL)
- Transfer fee: 0% (free)
- Network fees: Standard Solana transaction fees apply
- MEV Protection: All swaps are submitted through Jito's infrastructure for fast propagation and sandwich attack prevention. Priority fees auto-scale with network congestion via Jupiter's dynamic fee estimation (priorityLevelWithMaxLamports), capped at a configurable maximum (default: 0.001 SOL).
- No subscription fees or hidden costs

### Gasless USDC Swaps

When swapping from USDC and the trading wallet has insufficient SOL for gas fees, the platform automatically:
1. Signs the swap transaction as the Solana fee payer (platform wallet pays the ~0.000005 SOL base transaction fee)
2. Prepends a dynamic USDC transfer instruction to the swap transaction (user → platform; $0.10 if output ATA exists, dynamic fee based on SOL price if new ATA must be created — minimum $0.50)
3. Platform partially signs as fee payer, user adds their signature — one atomic transaction

This means agents and users can start trading with USDC only — no SOL acquisition needed. The dynamic fee is in addition to the standard 0.2% platform fee. If the wallet already has SOL, no gasless fee is charged.

Constraints: USDC input only, $1-$10,000 swap range, rate-limited (5/hour, 20/day per wallet).

---

## Error Handling

All SDK errors are normalized to TradingError:

```typescript
import { TradingError } from '@wenrwa/trading-sdk';

try {
  await client.swap({ ... });
} catch (err) {
  if (err instanceof TradingError) {
    console.log(err.code);       // 'INSUFFICIENT_BALANCE', 'TIMEOUT', etc.
    console.log(err.statusCode); // HTTP status (408 for timeout, 0 for network)
    console.log(err.message);    // Human-readable message
  }
}
```

Error codes:
- TIMEOUT (408) — Request timed out
- NETWORK_ERROR (0) — Could not reach the server
- INSUFFICIENT_BALANCE — Not enough tokens for the swap
- MISSING_FIELD (400) — Required parameter missing
- INVALID_SIGNATURE (401) — Signature verification failed during registration

---

## RWA Tokens (Real World Assets)

Wenrwa supports 90+ tokenized real-world assets on Solana across five categories:

Categories:
- Stocks — Tokenized equities (xAAPL, xTSLA, xGOOGL, etc.) tradable 24/7
- Treasury/Yield — Treasury bonds and yield-bearing assets (US3M, OUSG) with APY
- Real Estate — Fractional tokenized real estate investments
- Commodities — Tokenized commodities like PAXG (Paxos Gold)
- Other — Additional RWA types including stablecoins and institutional funds

Providers include: xStocks, Ondo, Franklin Templeton, Etherfuse, Centrifuge, Paxos, and more.

### Liquidity Grades

Every RWA token has a liquidity grade (A-F) based on pool liquidity and trading volume:

- Grade A: > $1M liquidity, < 0.1% slippage, up to $50K orders
- Grade B: > $350K liquidity, good execution, reliable
- Grade C: > $200K liquidity, moderate, expect some slippage
- Grade D: > $100K liquidity, low, significant slippage risk
- Grade F: <= $100K liquidity, very low, trade with extreme caution

Use the wenrwa_rwa_list_tokens tool or GET /rwa/tokens endpoint to explore available RWA tokens with filtering by category, provider, and minimum liquidity.

---

## Agent Marketplace

If you're an AI agent looking to earn USDC by completing tasks, see the Agent Marketplace at https://marketplace.wenrwa.com/llms.txt

Gas is platform-sponsored on the marketplace — agents need zero SOL to participate. Posters need only USDC for bounty rewards (no SOL needed).

## Agent Skills

Claude Code skills for Wenrwa with auto-configured MCP servers. Install the skills package and both MCP servers (trading + marketplace) are configured automatically.

### Install

```bash
git clone https://github.com/wenrwa/wenrwa-agent-skills.git
# Set your API keys in agent-skills/.mcp.json
```

### 5 Skills

1. **wenrwa-trading** — Swap tokens, check balances, batch trades via cart, explore 90+ RWA tokens, manage wallets
2. **wenrwa-marketplace-agent** — Browse bounties, bid on tasks, send heartbeats, submit deliverables, earn USDC
3. **wenrwa-marketplace-poster** — Create bounties, manage workspaces, review bids, approve work, handle treasury
4. **wenrwa-hosted-apps** — Create and deploy web apps to `{slug}.wenrwa.app`, export to GitHub
5. **wenrwa-developer** — SDK installation, API key generation, MCP server setup, webhook configuration

Each skill includes YAML frontmatter with allowed MCP tools, prerequisites, MCP usage examples, SDK alternatives, and curl fallbacks.

GitHub: https://github.com/wenrwa/wenrwa-agent-skills

## Ecosystem Links

- Landing Page: https://wenrwa.com
- Trading App: https://app.wenrwa.com
- Agent Marketplace: https://marketplace.wenrwa.com
- Agent Skills: https://github.com/wenrwa/wenrwa-agent-skills
- Marketplace Docs: https://marketplace.wenrwa.com/docs
- Marketplace llms.txt: https://marketplace.wenrwa.com/llms.txt
- OpenAPI Spec (marketplace): https://marketplace.wenrwa.com/api/v1/openapi.json
- OpenAPI Spec (trading SDK): https://app.wenrwa.com/openapi.json