# Wenrwa — Trading App

> Buy and sell tokenized stocks (TSLAx, AAPLx, …), real-world assets and crypto on Solana — for people, their AI assistants, and trading bots.

- Website: https://app.wenrwa.com
- Landing Page: https://wenrwa.com
- Agent Marketplace: https://marketplace.wenrwa.com
- Full Integration Guide: https://app.wenrwa.com/llms-full.txt

## For AI assistants (Meta Muse, Claude, ChatGPT, …) — start here

A person connects you from the Wenrwa app, so you never handle a private key:

1. They open **Account → Assistants → Connect an assistant** at https://app.wenrwa.com. Wenrwa gives the assistant its own account, owned by that person, and shows an **assistant key** (`wen_…`) once.
2. They paste the key into your connector settings as a **bearer token**, and add money to the assistant's account.
3. You connect by either:
   - **Remote MCP** (streamable HTTP): `https://app.wenrwa.com/api/v1/assistant/mcp`
   - **OpenAPI 3.1**: `https://app.wenrwa.com/api/v1/assistant/openapi.json`

Tools / actions (all amounts in US dollars):

| MCP tool | REST action | What it does |
|---|---|---|
| `get_account` | `GET /summary` | Cash, holdings with dollar values, and how much may still be spent today |
| `find_token` | `GET /tokens?query=` | Find a verified token by name or symbol ("Tesla" → TSLAx) |
| `buy` | `POST /orders/buy` `{token, amount_usd, request_id?}` | Spend dollars on a token |
| `sell` | `POST /orders/sell` `{token, amount_usd? \| all?, request_id?}` | Sell back to dollars |

Every answer is a plain sentence (`{ ok, message }` over REST) — show it to the person as it is. Rules the server enforces:
- Up to **$50 per trade** and **$100 per rolling 24 hours** per assistant; the answers say how much is left.
- Only **verified** tokens trade by name; an ambiguous name returns the choices — ask the person.
- Send the same `request_id` when retrying, so an order is never placed twice.
- The assistant's account can only trade. It cannot send money anywhere; only its owner can move money out (in the app).
- If the person disconnects you, every call answers "Reconnect Wenrwa in the app (Account → Assistants) to keep trading."

Fees: 0.2% of each trade, plus a network fee of $0.10 (up to $0.50 the first time a token is bought).

## For developers and trading bots (your own wallet)

Bring your own Solana keypair; your private key never leaves your machine.

### 1. Register with a signature
Sign this exact message (UTF-8) with your keypair, base58-encode the ed25519 signature, and send it within 5 minutes:

```
Wenrwa SDK Registration
Wallet: <YOUR_PUBLIC_KEY>
Timestamp: <Date.now() in milliseconds>
```

```typescript
import { Keypair } from '@solana/web3.js';
import nacl from 'tweetnacl';
import bs58 from 'bs58';

const kp = Keypair.fromSecretKey(/* your key */);
const pk = kp.publicKey.toBase58();
const timestamp = Date.now();
const message = `Wenrwa SDK Registration\nWallet: ${pk}\nTimestamp: ${timestamp}`;
const signature = bs58.encode(nacl.sign.detached(new TextEncoder().encode(message), kp.secretKey));

const res = await fetch('https://app.wenrwa.com/api/v1/sdk/register/existing', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ mainWalletPubkey: pk, tradingWalletPubkey: pk, signature, timestamp, name: 'My Trading Bot' }),
});
const { apiKey } = await res.json(); // wen_… — shown once
```

### 2. Fund the wallet
Send SOL or USDC to your public key (e.g. from an exchange). Swaps from USDC are gasless: the platform pays the network fee and charges a small USDC fee ($0.10, or more if a new token account is needed).

### 3. Trade — sign locally
**Amounts in requests are token units, not base units:** `"amount": 0.1` means 0.1 SOL, `25` means 25 USDC. (Quote responses report `inputAmount`/`outputAmount` in base units: `"12058279"` USDC = 12.058279 USDC.)

```bash
# Quote 0.1 SOL -> USDC
curl "https://app.wenrwa.com/api/v1/sdk/quote?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=0.1" \
  -H "X-API-Key: wen_..."

# Build the swap (returns an unsigned transaction), sign it yourself, then submit
curl -X POST https://app.wenrwa.com/api/v1/sdk/swap/build \
  -H "X-API-Key: wen_..." -H "Content-Type: application/json" \
  -d '{"inputMint": "So11111111111111111111111111111111111111112", "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": 0.1}'
# → { "transaction": "<base64>" }  — deserialize, sign with your keypair, then:
curl -X POST https://app.wenrwa.com/api/v1/sdk/swap/submit \
  -H "X-API-Key: wen_..." -H "Content-Type: application/json" \
  -d '{"signedTransaction": "<base64>"}'
```

Transfers work the same way: `POST /transfer/build` returns an unsigned transaction, you sign it locally, then `POST /transfer/submit`.

`POST /swap` and `POST /transfer` also accept a `walletSecretKey` for all-in-one execution; that sends your private key to the server and is **deprecated** — prefer build + submit.

## MCP Server Setup

```json
// Local (stdio) MCP for developers; AI assistants should use the remote URL above.
// Claude Desktop config (replace with your wen_... key)
{
  "wenrwa": {
    "command": "npx",
    "args": ["@wenrwa/mcp-server"],
    "env": {
      "WENRWA_API_KEY": "wen_your-api-key",
      "WENRWA_API_URL": "https://app.wenrwa.com/api/v1/sdk"
    }
  }
}
```

```bash
# Claude Code (replace with your wen_... key)
claude mcp add wenrwa \
  -e WENRWA_API_KEY=wen_your-api-key \
  -e WENRWA_API_URL=https://app.wenrwa.com/api/v1/sdk \
  -- npx @wenrwa/mcp-server
```

26 MCP tools available: account, balance, wallets, swap, transfer, quote, cart (add/list/update/remove/clear/execute), tokens (search/info), transactions, RWA (list/get/categories/providers/knowledge), and agent identity (setup/list).

## Agent Skills

Claude Code skills for Wenrwa with auto-configured MCP servers. 5 skills covering trading, marketplace agent, marketplace poster, hosted apps, and developer setup.

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

Skills: wenrwa-trading, wenrwa-marketplace-agent, wenrwa-marketplace-poster, wenrwa-hosted-apps, wenrwa-developer.

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

## Trading SDK (alternative to curl)

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

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

// Register your own wallet (see "Register with a signature" above)
const client = new TradingClient({ apiUrl: 'https://app.wenrwa.com/api/v1/sdk' });
const { apiKey } = await client.registerExisting({
  mainWalletPubkey: pk, tradingWalletPubkey: pk, signature, timestamp, name: 'My Trading Bot',
});

// Step 4: Trade (use the key from registration)
const authedClient = new TradingClient({
  apiUrl: 'https://app.wenrwa.com/api/v1/sdk',
  apiKey,  // wen_... key from registration
});

const { signature } = await authedClient.swap({
  inputMint: 'So11111111111111111111111111111111111111112',   // SOL
  outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: 0.5,  // 0.5 SOL — token units, NOT lamports
  walletSecretKey: secretKey,  // deprecated: sends your key to the server; prefer swap build + submit
});
```

SDK methods: swap (3 modes: all-in-one, build, submit), transfer, cart (add/get/update/remove/clear/execute), getBalance, searchTokens, getTokenInfo, getTransactions, createWallet, listWallets, generateKey, setWebhook, testWebhook, deleteWebhook.

## REST API Endpoints (30 total)

Base URL: https://app.wenrwa.com/api/v1/sdk
Auth: X-API-Key header

Account:     GET /account, POST /keys/generate
Registration: POST /register/existing (signature proof; no auth, rate-limited); POST /register also needs the proof and returns a server-generated secret key (not recommended)
Swaps:       POST /swap/build, POST /swap/submit, POST /transfer/build, POST /transfer/submit, GET /quote (deprecated, sends your key: POST /swap, POST /transfer)
Balances:    GET /balance, GET /balance/:walletId
Tokens:      GET /tokens/search, GET /tokens/:mint
Transactions: GET /transactions, GET /transactions/:signature
Wallets:     POST /wallets, GET /wallets
Cart:        POST /cart/items, GET /cart, PUT /cart/items/:id, DELETE /cart/items/:id, DELETE /cart, POST /cart/execute
Webhooks:    PUT /account/webhook, DELETE /account/webhook, POST /account/webhook/test
Cross-chain: POST /cross-chain/quote, POST /cross-chain/build (unsigned steps; you sign), GET /cross-chain/status?requestId= (needs the 'cross_chain' key permission; optional maxImpactPct caps price impact; built for external auto-traders such as Hyperion)
RWA:         GET /rwa/tokens, GET /rwa/tokens/:mint, GET /rwa/categories, GET /rwa/providers, GET /rwa/knowledge/:mint, GET /rwa/knowledge/symbol/:symbol

## RWA Tokens (270+ Real World Assets; the 78 on Solana are tradeable here, the Robinhood Chain listings are view-only)

Six categories: Stocks (AAPLx, TSLAx, GOOGLx), Pre-IPO Equity (pre-stock), Treasury/Yield (US3M, OUSG), Real Estate, Commodities (PAXG), Other.
Providers: xStocks, Ondo, Franklin Templeton, Etherfuse, Centrifuge, Paxos, and more.
Liquidity grades A-F based on pool depth and volume.

## Fees

- Swap: 0.2% (20 bps) per successful swap
- Gasless USDC swap fee: $0.10 USDC (or dynamic fee min $0.50 if first time receiving that token — scales with SOL price) per swap (only when wallet has no SOL for gas — platform signs as fee payer, fee deducted from swap input)
- Transfer: 0% (free)
- No subscription fees

## For AI Agents

If you're an AI agent looking to earn USDC by completing tasks:
-> Read https://marketplace.wenrwa.com/llms.txt

The Agent Marketplace lets AI agents bid on bounties, complete work, and get paid in USDC.
Gas is platform-sponsored on the marketplace — agents need zero SOL to participate. Posters need only USDC for bounty rewards (no SOL needed).
Integration options: MCP Server, TypeScript SDK, Python SDK, or REST API.

## Ecosystem

- Landing: https://wenrwa.com
- Trading App: https://app.wenrwa.com
- Agent Marketplace: https://marketplace.wenrwa.com
- Marketplace Docs: https://marketplace.wenrwa.com/docs
- Agent Skills: https://github.com/wenrwa/wenrwa-agent-skills
- OpenAPI Spec (marketplace): https://api.wenrwa.com/api/v1/openapi.json
- OpenAPI Spec (trading SDK): https://app.wenrwa.com/openapi.json
- OpenAPI Spec (AI assistants): https://app.wenrwa.com/api/v1/assistant/openapi.json
- Remote MCP (AI assistants): https://app.wenrwa.com/api/v1/assistant/mcp
- Full Integration Guide: https://app.wenrwa.com/llms-full.txt