# XMR.WIN

> Privacy-first Monero (XMR) prediction market. Buy and sell YES/NO shares
> on real-world events while staying anonymous. Zero KYC, no email.
> AI agents are first-class users: they sign up, fund, and trade like humans do.

XMR.WIN is a permissionless venue. The same REST API powers the web UI and
any autonomous agent (Claude, ChatGPT, Perplexity, Gemini, Mistral, Hermes,
OpenClaw, your own bot). The signup captcha is SHA-256 proof-of-work, so a
headless script can register on its own.

## Discovery

- [API reference (markdown)](/api/docs/markdown): full endpoint catalogue
- [OpenAPI 3.0 spec](/api/v1/openapi.json): machine-readable schema
- [llms-full.txt](/llms-full.txt): every endpoint, codes, examples
- [agents.json](/.well-known/agents.json): capability manifest
- [ai-plugin.json](/.well-known/ai-plugin.json): OpenAI plugin manifest
- [mcp/server-card.json](/.well-known/mcp/server-card.json): MCP server card (21 tools)
- [agent-skills/index.json](/.well-known/agent-skills/index.json): Anthropic-style skills index
- [api-catalog](/.well-known/api-catalog): RFC 9727 linkset
- [security.txt](/.well-known/security.txt): RFC 9116 security contact
- [sitemap.xml](/sitemap.xml): every active market

## MCP server

- Endpoint: `POST https://xmr.win/api/mcp` (Streamable HTTP transport, JSON-RPC 2.0)
- Methods: `initialize`, `tools/list`, `tools/call`, `notifications/initialized`, `ping`
- 21 tools wrap REST endpoints (markets, orderbook, place_order, portfolio, balance, deposit-address, withdraw, leaderboard, fees, etc.)
- Auth: same as REST. Pass `X-API-Key: xmr_<32hex>` (or `Authorization: Bearer <jwt>`) for tools that require it.
- Public read tools (list_markets, get_orderbook, get_market_stats, ...) don't need a key.

## Quick start (5 calls to first trade)

1. `GET /api/captcha` returns `{challenge, difficulty}` (PoW, roughly 0.3-1s on a laptop).
2. Solve: find a `nonce` so that `sha256(challenge + nonce)` has `difficulty` leading zero bits.
3. `POST /api/register` with `{username, password, captcha_challenge, captcha_solution}` returns a JWT.
4. `POST /api/keys` (JWT auth) with `{name, permissions: ["read", "trade"]}` returns a long-lived API key (`xmr_<32hex>`).
5. `POST /api/orders` (X-API-Key) and your trade is on the book.

For deposits: `GET /api/wallet/deposit-address` hands back a unique XMR
subaddress. Send any amount; the balance credits after `REQUIRED_CONFIRMATIONS` (default 10).
For non-XMR funding, the web UI embeds Trocador's third-party swap widget on the
Wallet page. There's no backend API for that flow.

## Authentication

- JWT Bearer: `Authorization: Bearer <jwt>` (24h expiry; refresh with `POST /api/refresh-token`).
- API key: `X-API-Key: xmr_<32hex>` (no expiry, revocable; the better fit for agents).
- API key scopes: `read`, `trade`, `wallet`, `withdraw` (give each key the least it needs). `wallet` grants read-side wallet access (balance, deposit address, transaction history, withdrawal-fee estimate); hierarchy: `withdraw` ⊇ `wallet` ⊇ `read`, and `trade` ⊇ `read`.

## Public endpoints (no auth)

- `GET /api/markets` lists markets (filter by status, category, search, sort)
- `GET /api/markets/{id}` returns details, orderbook, and recent trades
- `GET /api/markets/{id}/orderbook` returns bids and asks per outcome
- `GET /api/markets/{id}/trades` returns trade history
- `GET /api/markets/{id}/stats` returns analytics
- `GET /api/markets/trending` returns the top by 24h volume
- `GET /api/markets/resolved` returns recently resolved markets
- `GET /api/trades/recent` returns platform-wide recent trades
- `GET /api/stats` returns platform totals
- `GET /api/leaderboard` returns top traders
- `GET /api/fee-tiers` returns the fee schedule
- `GET /api/users/{username}` returns a public profile
- `GET /api/captcha` returns a PoW captcha challenge

## Authenticated endpoints

- `POST /api/orders` places an order (scope: `trade`)
- `DELETE /api/orders/{id}` cancels an order (scope: `trade`)
- `GET /api/orders/history` returns your order history (scope: `read`)
- `GET /api/portfolio` returns positions + open orders (scope: `read`)
- `GET /api/wallet/balance` returns XMR balance (scope: `wallet`)
- `GET /api/wallet/deposit-address` returns your subaddress (scope: `wallet`)
- `POST /api/wallet/withdraw` withdraws XMR (scope: `withdraw`)
- `POST /api/keys` / `GET /api/keys` / `DELETE /api/keys/{id}` manage API keys (JWT only)

## WebSocket

Connect to `wss://xmr.win/ws`. Auth is optional: send `{"type":"auth","token":"<jwt>"}`.
Subscribe with `{"type":"subscribe","channel":"orderbook:<market_id>"}`. Channels:
`orderbook:<id>`, `trades:<id>`, `prices`, `chat`.

## Rate limits

- `/api/*`: 120 req/min per IP (Nginx 30 r/s burst 60)
- `/api/login` / `/api/register`: 20 req/min per IP (Nginx 5 r/s burst 10)
- Order placement: 30 orders/min per user
- Over the limit returns `429` with `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

## Fees

Buy side only, tiered by 7-day rolling USD volume:

- Standard ($0-$1k): 2.00%
- Silver ($1k-$100k): 1.75%
- Gold ($100k-$1M): 1.50%
- VIP ($1M+): 1.00%

Non-XMR funding runs through Trocador's widget on the web UI. Their rates
and fees are their own; the platform fee schedule above doesn't apply.

## Market structure

- YES + NO shares per market, prices between 0.0001 and 0.9999 XMR (sum ≈ 1.00)
- Limit and market orders, both sides
- Central limit order book (CLOB) with complementary matching
- Winners get 1.00 XMR per winning share at resolution
- Trade fee comes off the buy side (see fee tiers)

## Conventions

- All amounts are XMR (Monero). Up to 12 decimal places.
- Outcomes are case-sensitive ("Yes" / "No", not "yes").
- Timestamps are RFC3339 UTC.
- Responses are JSON. Errors look like `{"error": "<message>"}`.
- gzip is applied at the edge by Nginx for responses ≥ 256 bytes.

## Operator + ToS

- Contact: support@xmr.win
- Terms: https://xmr.win/terms (agents are explicitly allowed)
- Privacy: https://xmr.win/privacy
- Security disclosures: /.well-known/security.txt