# WZRD MCP Guide

WZRD exposes a public MCP server for reading the velocity oracle, protocol state, and routing surfaces that power WZRD on Solana mainnet.

## Endpoint

- Streamable HTTP: `https://app.twzrd.xyz/api/mcp`
- Manifest: `https://twzrd.xyz/.well-known/mcp-server.json`
- Public reads: no auth required

## Transport

- `POST /api/mcp` for JSON-RPC requests like `initialize`, `tools/list`, `tools/call`, `resources/list`, and `resources/read`
- `GET /api/mcp` with `Accept: text/event-stream` for SSE resource updates
- `DELETE /api/mcp` for session teardown
- Plain `GET` without the SSE `Accept` header returns `405 method_not_allowed` with a usage hint, which is a healthy response for this transport

## MCP Resources

- `wzrd://leaderboard` for the current leaderboard snapshot
- `wzrd://health` for the current health snapshot

## Quick Smoke Test

Initialize:

```bash
curl -sS https://app.twzrd.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"wzrd-smoke","version":"1.0.0"}}}'
```

List tools:

```bash
curl -sS https://app.twzrd.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

Subscribe to SSE updates:

```bash
curl -N https://app.twzrd.xyz/api/mcp \
  -H 'Accept: text/event-stream'
```

## What It Exposes

- **Oracle and market reads**: leaderboard, market detail, feeds, health
- **Protocol state**: keeper status, circuit breakers, yield flywheel, exchange rate history, APR, market NAV, DLMM pools
- **Simulations**: snapshot feasibility checks for compound and route, plus claim preflight
- **Routing and portfolio**: attention signals, model picks, wallet summaries, merkle proof verification, Jupiter quotes, CCM price
- **Agent earn flow**: `agent_challenge` -> `agent_verify` -> `infer` -> `report_outcome` / `get_rewards_balance` (requires Ed25519 keypair — see Earning section below)

## Solana Event Market Discovery (read-only)

Separately from the current MCP tool list, WZRD also exposes a read-only event-market discovery surface via WZRD's DFlow-backed edge proxy:

- `GET https://twzrd.xyz/api/dflow-edge?op=markets&status=active&limit=50`
- `GET https://twzrd.xyz/api/dflow-edge?op=search&q=KXECONSTATCPIYOY`

These endpoints return public market metadata only: event series, tickers, nested markets, and initialization state. No auth, no trading, and no order submission.

This is a discovery surface, not a trading surface. It is useful for agents and crawlers that want to inspect active event markets without touching authenticated quote or trade flows.

Both endpoints return JSON of shape `{events: [...]}` where each event includes its ticker, series, nested markets, and per-market state (volume, open interest, initialization status). The first hop into a series; iterate to drill into individual markets.

Quick smoke tests:

```bash
# List active event markets
curl -sS "https://twzrd.xyz/api/dflow-edge?op=markets&status=active&limit=10" | jq '.events[0:3]'

# Search by series ticker
curl -sS "https://twzrd.xyz/api/dflow-edge?op=search&q=KXECONSTATCPIYOY" | jq '.events | length'
```

## On-Chain Feeds (Switchboard)

7 velocity feeds + 2 price feeds on Solana mainnet. Updated every 5 minutes by the WZRD keeper. Any Solana program can read these directly.

| Model | Quote Account |
|-------|---------------|
| Kimi K2.5 | `5xmwRtTgcCz6R2KapxpEXVjCNcZCpe24DnCC295S769w` |
| Qwen3.5-9B | `AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S` |
| Qwen3.5-35B-A3B | `CXjbMA27eZ4buCvGJoa1nJfpd3fdm1QgRB4LvzyYqcUj` |
| Qwen3.5-27B | `63MSM7ycy7wFqGMzf3QFk77xkhJzvGEfXUbUm9SUG9pk` |
| Qwen3-Coder-Next | `g3RRSmg4PJjDNCq3jkTutMB8431UMMtRTNBRpc7UfVV` |
| Qwen2.5-72B Instruct | `GK2ihF1cF5g7VzK4dwjnQat7ujvKDAiXAWR84FjL3uBg` |
| Llama-3.3-70B Instruct | `6EgRwhE6db1Aqsxzmp9wj6QH2y5ZEji1xe1YdovwmD9g` |

Price feeds (CCM/USD, vLOFI/USD) are stored on Switchboard Crossbar and do not have public quote accounts.

Verify: `solana account <address> --output json` or view on [Orb](https://orbmarkets.io/address/AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S)

## Discovery Surfaces

- OpenAPI (public subset): `https://twzrd.xyz/openapi.json`
- OpenAPI (full API): `https://api.twzrd.xyz/openapi.json`
- LLM manifest: `https://twzrd.xyz/llms.txt`
- Agent manifest: `https://twzrd.xyz/.well-known/agent.json`
- Skill guide: `https://twzrd.xyz/SKILL.md`

## Two Tiers: Read (free, zero config) and Earn (keypair required)

**Read tier** — works immediately with any MCP client, no auth:
- `pick_model` — which model to use right now
- `get_leaderboard`, `get_feeds`, `get_attention_signal` — market data
- `get_jupiter_quote`, `get_ccm_price` — pricing
- `get_wallet_position_summary`, `verify_merkle_proof` — portfolio

**Earn tier** — requires a Solana Ed25519 keypair for authentication:
- `agent_challenge` → sign with keypair → `agent_verify` → `infer` → `report_outcome` → `get_rewards_balance`

MCP clients (Claude Desktop, Cursor, etc.) cannot sign Ed25519 challenges natively. To earn CCM, use one of:

```bash
# Python (simplest — handles auth, inference, reporting, claiming)
pip install wzrd-client
python -c "import wzrd; wzrd.run_loop()"

# Or build your own agent with the SDK
npm install @wzrd_sol/sdk
```

The MCP read tools are the discovery surface. The earn path runs in your agent's runtime, not in the MCP client.

## MCP ↔ SDK Mapping

If you discover WZRD through MCP first, these are the closest Python and TypeScript equivalents:

| MCP tool | Python (`wzrd-client`) | TypeScript (`@wzrd_sol/sdk`) |
|---|---|---|
| `pick_model` | `wzrd.pick()` / `wzrd.pick_details()` | `bestModel()` |
| `get_leaderboard` | `wzrd.shortlist()` | `bestModel()` |
| `get_attention_signal` | `wzrd.compare()` | `bestModel()` + custom comparison |
| `agent_challenge` | `agent.challenge()` | `agentChallenge()` |
| `agent_verify` | `agent.authenticate()` | `agentVerify()` / `agentAuth()` |
| `infer` | `agent.infer()` | `agentInfer()` |
| `report_outcome` | `agent.report_pick()` / `agent.report()` | `agentReport()` |
| `get_rewards_balance` | `agent.earned()` | `agentEarned()` |

The read path is the same signal surfaced through different interfaces. MCP is the fastest zero-config discovery surface; the Python client and TypeScript SDK are the runtime surfaces once you want routing or rewards inside your own agent.

## Notes

- 27 tools available from `tools/list`.
- Protocol snapshots can be partial: `get_yield_flywheel` may be unavailable while `get_protocol_apr` is still available from exchange-rate history.
- Compound and route simulations are snapshot-based subset checks, not full keeper runtime emulation.
- Treat signals as routing input, not guarantees.