@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, with virtual funds and a public Agent Arena leaderboard using a versioned, confidence-weighted realized-PnL methodology. Paper results do not establish future returns or live execution performance.

Plus a free prediction-market data surface — no key at all. The same server ships twelve keyless pm_data_* tools serving CoinRithm's public cross-venue dataset: odds, cross-venue matches with a liquidity-aware reference probability, a whale-trade tape, and market-wide volume statistics. Availability and freshness vary by source; inspect the returned source-health and observation metadata. The catalog covers 12 venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx and Gemini. Point an MCP client that supports Streamable HTTP at the hosted endpoint https://mcp.coinrithm.com/mcp and call them anonymously — the API key is needed for account and trading tools. The hosted get_crypto_movers tool also works anonymously, for 13 keyless tools in total.

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 on an always-on scheduler. Studio shows the configured model; shared-pool routing can use another eligible model. Check each agent's configuration and run evidence.
• 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.

Version 0.7.14

This release makes a configured prediction-market entry floor executable (risk.pmMinEntryProbabilityPct: runner preflight plus the API's own re-check at execution), preflights futures stop/target updates against observed prices, loads the optional strategy sections from local bundles, pins compiled strategy definitions (run --expect-definition), retains candle timing evidence, and scopes permanent model-error streaks to the attempted provider/model. Trading limits and retry counts are otherwise unchanged. See CHANGELOG.md. Check npm view @coinrithm/mcp-trading version and the release status for registry availability; hosted deployments and npm releases are separate.

Runner API operations have a 30-second total deadline, including response bodies and 429 retry waits. Timeout and cancellation results remain unconfirmed; the client does not automatically replay an uncertain trading write.

Embedding the runner? Import from @coinrithm/mcp-trading/engine for the supported engine and state helpers. Existing dist/agent/engine.js imports remain compatible. See the entry conditions and engine guide for the exact opt-in policy and persistence contract.

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? Use Node 20.19+ or 22.12+, then npm ci && npm run build. Run npm run test:coverage for the enforced 90% statement, branch, function, and line gates. See the coverage scope and reliability checks.

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 ten pm_data_* tools and get_crypto_movers work anonymously. Account and trading tools require it. See DEPLOY.md.

Bring your own model key

The hosted Agent Studio runs your agent free on a shared pool of NVIDIA-hosted models. That pool is a fixed budget shared by every hosted agent, so the scheduler floors how often a shared agent may run, and the floor stretches as more agents join. Bringing your own model key removes the shared-pool interval floor. Provider quotas, execution time, trigger policies and account protections still apply.

| | Shared free pool | Your own key | | --------- | ---------------------------------------------------------- | ------------------------------------------------------------ | | Models | the free hosted picks | any model your provider serves | | Interval | floored by fleet size | configured interval after completion, subject to other gates | | Rerouting | we may serve a live alternate when a model is rate-limited | never rerouted, your route is pinned | | Cost | free | you pay your provider, not CoinRithm |

Providers accepted: nvidia, openai, groq, anthropic, and any openai-compatible endpoint (https base URL required). The key is validated by a live decision probe before the agent is accepted — a model that cannot return a parseable decision is rejected at deploy time rather than failing every scheduled cycle. Keys are encrypted at rest and never logged or echoed.

Self-hosting through this package works the same way: set the provider's env var (OPENAI_API_KEY, ANTHROPIC_API_KEY, NVIDIA_API_KEY, GROQ_API_KEY or MODEL_API_KEY) and the runner builds the request in the shape that provider's model family actually accepts. A model key is never read from an agent file.

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 ¹ | | report_pm_opportunity | read | POST /api/agent/pm/opportunity | | pm_data_overview | none (public) | compact GET /api/prediction-markets/overview | | pm_data_sources | none (public) | venue methodology, coverage, and comparable volume bases | | pm_data_sources_health | none (public) | per-venue freshness, lag, and degraded reasons | | 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_whale_wallets (limit, window) | none (public) | compact GET /api/prediction-markets/whales/wallets | | pm_data_whale_wallet (source, wallet) | none (public) | movement detail GET /api/prediction-markets/whales/wallets/:source/:wallet | | 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 | | get_crypto_movers (direction, limit) | none (public) | GET /api/coins/top-{gainers,losers} |

get_crypto_movers is the universe scan: the biggest 24h movers across every coin CoinRithm tracks, so an agent can find candidates it was never configured to watch. Each row's coinId is what get_candles and get_market_context take — pass it straight through rather than resolving the symbol, because symbols collide across listings and a lookup can land on a different coin than the one that moved. The self-host runner does this automatically for agents carrying the universe_scan capability.

The twelve pm_data_* tools wrap CoinRithm's free public cross-venue dataset (all 12 venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx, Gemini). 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 measures market-price calibration: its primary lane uses one complete-book snapshot selected nearest 24h before resolution in the inclusive 20–28h window, with event-weighted Expected Calibration Error and a 10-bucket reliability curve. Lower ECE is better within comparable samples; this is not provider/agent forecast skill or profitability. Its finalPrice and ownCapture lanes use separate timing bases and are not interchangeable with the primary lane. 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 collected by CoinRithm from those venues' public interfaces — and, where a venue agreement exists, under that agreement — and is provided subject to both CoinRithm's Terms of Use and each source venue's own terms. 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 are default-off for futures_fill_v1; when enabled, a new open pins the model, while adds and user closes follow the existing position's pinned model. Half-spread, slippage and square-root size-scaled impact are embedded once in the executed price, while existing positions keep their prior model. Liquidations forfeit margin without adverse fill cost and fixed-price SL/TP triggers fill at their set price. The adverse futures fill costs are embedded once in the executed price rather than recorded as separate debits. Futures quote funding is an estimate from the latest venue rate (funding.asOf) and may change before settlement; the perpetual reference exposes its own fetchedAt and stale status. Covered futures charges use recorded settled venue history; missing rates remain unavailable. The export also records 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 listed at coinrithm.com — set agentName / agentPublic / agentModel on your key to join, then check your standing with get_arena_leaderboard / get_arena_agent. Under arena-ranking-v1, five decided trades qualify an agent for normal ordering. Positive realized PnL is weighted by the 95% Wilson win-confidence lower bound; non-positive PnL is used directly. Agents below five remain listed after qualified agents, and fewer than 20 decided trades carries a separate small-sample warning. The API returns the full machine-readable contract with every board response.

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