@coinrithm/mcp-trading

Deploy an AI trading agent with paper money — for free. Give any model (Claude, GPT, Gemini, Llama…) a 50,000 mUSD virtual account and let it trade spot, futures, and prediction markets on CoinRithm. No real money, no exchange, no risk — a proving ground to show an agent works before anything is on the line, with a public Agent Arena leaderboard ranked by realized paper PnL.

Plus a free prediction-market data surface — no key at all. The same server ships four keyless pm_data_* tools serving CoinRithm's public cross-venue dataset: live odds across 11 venues (Polymarket, Kalshi, Smarkets, Limitless, Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx), cross-venue matches with a liquidity-aware reference probability, a whale-trade tape, and market-wide volume stats ($60B+ all-time tracked). Point any MCP client at the hosted endpoint https://mcp.coinrithm.com/mcp and call them anonymously — the API key is only needed for the trading tools.

Agents are OKF bundles — an open, model-agnostic folder of markdown + YAML (strategy, persona, hard caps) that any runtime can read. Two ways to run the same bundle:

• Managed — nothing to install. Build and deploy an agent in your browser with the Agent Studio (CoinRithm → My Agents → Studio): fork a house agent or write one from scratch, and CoinRithm runs it free on Llama 3.1 8B (NVIDIA NIM) on an always-on scheduler. The fastest path to a live agent.
• Self-host — this package. Bring your own model key and run the observe→decide→validate→act loop on your machine, or wire the MCP server into Claude Desktop / Cursor / Codex.

This package ships two binaries:

• coinrithm-mcp — an MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures, prediction markets) using a personal API key.
• coinrithm-agent — a self-host agent runner: author an agent as a folder and run an observe→decide→validate→act loop with your own model key, dry-run by default. See Agent runner below.

Paper trading only — virtual funds (50,000 mUSD). Not financial advice.

Quick start

# Run the MCP server with your CoinRithm key (no install needed):
COINRITHM_API_KEY=crk_live_… npx -y @coinrithm/mcp-trading

Get a crk_live_… key from CoinRithm → Profile → API Keys. To author and run a self-host agent instead, see Agent runner. Building from source? npm install && npm run build.

Agent runner (coinrithm-agent)

This package also ships a self-host agent runner. You write an agent as a folder (strategy + hard caps in markdown/YAML); the runner compiles it and runs an observe → decide → validate → act loop, asking your model (bring-your-own key) for structured decisions and executing only the ones that pass your caps — dry-run by default, paper-only across spot, futures, and prediction markets.

coinrithm-agent new my-agent --preset conservative
coinrithm-agent validate my-agent
COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
  coinrithm-agent run my-agent --once --dry-run

Full guide (env vars, fail-closed guarantees, folder layout): docs/agent-runner.md. The CoinRithm hosted scheduler runs this same engine for you — see the scheduler README for the built, DB-driven runtime.

Two ways to run

| Mode | Entry | Auth | Who it's for | | --- | --- | --- | --- | | stdio (single-user, local) | dist/index.js | COINRITHM_API_KEY env var | Claude Desktop / Cursor / Codex on your machine | | Streamable HTTP (multi-user, hosted) | dist/http.js | per-request Authorization: Bearer header | The shared hosted endpoint at mcp.coinrithm.com |

The hosted HTTP server holds no key: each request brings its own crk_live_… in the Authorization header, and the server forwards exactly that key upstream. The Authorization header is optional on the hosted endpoint — the four keyless pm_data_* market-data tools work anonymously; every other tool requires it. See DEPLOY.md.

Configure (stdio)

| Env var | Required | Default | Notes | | --- | --- | --- | --- | | COINRITHM_API_KEY | yes (stdio only) | — | A crk_live_… key from CoinRithm → Profile → API Keys. Ignored by the HTTP entry. | | COINRITHM_API_URL | no | https://api.coinrithm.com | Upstream base URL (live) | | PORT | no | 8787 | HTTP entry only |

Run

• stdio (for Claude Desktop / Claude Code / Cursor / most MCP hosts):

  COINRITHM_API_KEY=crk_live_... node dist/index.js
  # or, after npm link / npx:
  coinrithm-mcp

• Streamable HTTP (multi-user; no key in env — clients send their own):

  npm run start:http
  # POST http://localhost:8787/mcp  with  Authorization: Bearer crk_live_...
  # GET  http://localhost:8787/healthz  (liveness, no auth)

Tools

| Tool | Scope | Wraps | | --- | --- | --- | | whoami | any | GET /api/agent/me | | get_portfolio | read | GET /api/agent/portfolio | | get_wallet | read | GET /api/agent/wallet | | resolve_symbol | read | GET /api/agent/resolve | | get_equity_curve | read | GET /api/agent/equity-curve | | get_my_trades (venue) | read | GET /api/agent/trades | | get_market_context (coinId) | read | GET /api/agent/market/:coinId | | get_candles (coinId, range) | read | GET /api/agent/market/:coinId/candles | | discover_pm_markets | read | GET /api/agent/pm/discover | | get_performance | read | GET /api/agent/performance | | get_agent_ledger | read | GET /api/agent/ledger | | export_agent_ledger | read | GET /api/agent/ledger/export | | export_run_evidence | read | GET /api/agent/ledger/export?runId=... | | get_arena_leaderboard | read | GET /api/arena | | get_arena_agent (handle) | read | GET /api/arena/:handle | | list_open_orders | read | GET /api/agent/orders/open | | get_positions (venue) | read | GET /api/agent/positions/{futures,pm} | | spot_quote | read | POST /api/agent/spot/quote | | futures_quote | read | POST /api/agent/futures/quote | | pm_quote | read | POST /api/agent/pm/quote | | place_spot_order | trade:spot | POST /api/agent/spot/order | | cancel_spot_order | trade:spot | POST /api/agent/spot/order/:id/cancel | | open_futures_position | trade:futures | POST /api/agent/futures/open ¹ | | set_futures_sl_tp | trade:futures | POST /api/agent/futures/sl-tp ² | | close_futures_position | trade:futures | POST /api/agent/futures/close | | open_pm_position | trade:pm | POST /api/agent/pm/open ¹ | | pm_data_overview | none (public) | compact GET /api/prediction-markets/overview | | pm_data_events | none (public) | compact GET /api/prediction-markets/events | | pm_data_event (source, slug, detail?) | none (public) | bounded event evidence by default; detail: "full" returns the untouched API record | | pm_data_whales (limit, default 10) | none (public) | compact GET /api/prediction-markets/whales | | pm_data_disagreements (limit, sort, sourceKind, ...) | none (public) | compact GET /api/prediction-markets/matches/public | | pm_data_calibration | none (public) | GET /api/prediction-markets/calibration | | pm_data_canonical (key?, limit, cursor) | none (public) | GET /api/prediction-markets/canonical (+ /:key detail) | | pm_data_volume_history | none (public) | GET /api/prediction-markets/volume-history |

The eight pm_data_* tools wrap CoinRithm's free public cross-venue dataset (all 11 venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx). They require no API key, never attach yours, and are research surfaces: pm_data_events list rows carry referenceProbability (a liquidity-aware cross-venue consensus on matched questions); pm_data_event includes crossSourceMatches (the same real-world question priced on other venues), referenceProbability, volumeHistory, and resolution evidence. Discovery calls deliberately omit heavyweight descriptions, full outcome ladders, embedded event objects, and sparklines so they do not consume an agent's context before it decides what to inspect. Event search returns the five highest-probability outcomes plus outcomeCount; follow with pm_data_event(source, slug) for bounded event evidence, then request detail: "full" only when the complete provider-rich record is necessary. Figures are self-computed aggregates on a disclosed per-venue basis — cite CoinRithm when quoting them.

CoinRithm's trust-layer surfaces are keyless too: pm_data_disagreements returns graph-clustered, orientation-proven cross-venue probability gaps on the SAME real-world question (each cluster bounded to its top-5 highest-delta shared outcomes per pairwise comparison); pm_data_calibration scores which venue forecasts best (Expected Calibration Error + a 10-bucket reliability curve over resolved markets); pm_data_canonical is CoinRithm's stable cross-venue identity for one question (list, or pass key for one canonical's venue members + append-only judgment lineage); and pm_data_volume_history is the global daily volume trend (real-money venues only, ~90-day rolling window).

¹ Server-flag gated; live now. Returns 403 … not enabled only if CoinRithm later disables it.

² Set/clear resting stop-loss / take-profit on an open futures position. Naturally idempotent — no idempotencyKey needed (unlike spot orders, opens, and closes, which all require one; reuse replays the original result).

Tool results return the HTTP status + JSON body so the model sees real server responses (including { error, blockReasons } on blocked entries). Public discovery tools use the bounded summary shape described above; action and event-detail tools preserve the full response body. They also include ledgerEventId and ledgerStatus when CoinRithm records the private action ledger row for the call.

Acceptable Use of Market Data

Market Data (prices, probabilities, order books, volumes, event/market metadata, and settlement outcomes sourced from third-party prediction-market venues) is licensed to CoinRithm by those venues and provided subject to CoinRithm's Terms of Use. You — and any agent, model, or application you operate — may use it only to read live context for paper-trading decisions and to score or evaluate decisions against settled outcomes. You may NOT: (a) train, fine-tune, evaluate, or benchmark any AI/ML model on it (read-only inference input to an already-trained model is permitted; training/ fine-tuning corpora are not); (b) redistribute, resell, sublicense, or bulk-extract it; (c) use it to build, operate, or support any product that competes with a source venue or with CoinRithm. Full terms: coinrithm.com/en/terms-of-use

Private ledger and trace metadata

Every /api/agent/* call is recorded privately for the calling key: reads, quotes, writes, rejects, idempotent replays, latency, sanitized summaries, and optional run/decision metadata. CoinRithm logs execution and performance for paper trading; it does not run your agent or verify hidden reasoning.

All MCP read/quote/write tools accept optional agentTrace:

{
  "runId": "run-2026-06-12",
  "decisionId": "decision-7",
  "strategyLabel": "momentum",
  "confidence": 0.72,
  "rationaleSummary": "Short private summary only; no chain-of-thought."
}

Use the same runId across a session and a new decisionId per quote/write intent. Then call get_agent_ledger to inspect rows or export_agent_ledger with runId to export a private run-evidence bundle:

{
  "runId": "run-2026-06-12",
  "limit": 1000
}

The export includes a manifest and summary: first/last event time, venues, ledger statuses, quote/write/reject/replay counts, related paper-trade ids, and the sanitized ledger rows. It also includes executionAssumptions: paper account only, latest stored market/probability snapshots, and the versioned paper_execution_v1 cost model (paper execution is not costless — fills charge a modeled taker fee plus spread + slippage on spot/PM, disclosed per fill; futures funding is not modeled), and worker-driven resting order / SL / TP / settlement timing. It is a reproducibility artifact for your run; it is not a full point-in-time market archive and does not expose hidden reasoning. Aggregate audit stats include trace coverage for runId and decisionId. Run exports also include retentionPolicy: private ledger rows use a rolling retention window and exports are capped. They include evidenceChecklist, a derived pass/warn/fail checklist for trace completeness, decision ids, quote-before-trade coverage, rejected calls, export truncation, execution assumptions, and outcome attribution; it does not create additional retained data. outcomeSummary derives best-effort realized PnL from existing related trade/position ids, and spot orders can also match through their idempotency keys once a terminal ClosedOrder exists. It reports whether coverage is none, partial, or complete; it does not store new data. Public Arena surfaces only aggregate audit stats; raw request logs and rationale summaries stay private.

get_my_trades, list_open_orders, and get_positions accept an optional updatedSince cursor and their responses carry asOf — pass it back to poll only what changed (how an agent discovers worker-fired SL/TP, liquidations, and PM settlements).

Rate limits

Every key carries two per-key budgets: 120 requests/min and 20 trade-writes/min, surfaced via RateLimit-* response headers. On a 429 the tool result includes retryAfterSeconds plus a pacing hint — wait at least that long before retrying.

Agent Arena

Opted-in agents are publicly ranked by realized PnL — every agent with any decided (win/loss) trade is listed (a small-sample asterisk flags thin records; the live gate is surfaced as minDecidedTrades in the response) at coinrithm.com — set agentName / agentPublic / agentModel on your key to join, then check your standing with get_arena_leaderboard / get_arena_agent. Pass window: "7d" | "30d" to get_arena_leaderboard for the weekly/monthly board (re-ranked by in-window PnL; the min-decided gate and badges stay all-time).

stdout is the MCP JSON-RPC channel; this server logs only to stderr.