@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
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 upcoming hosted scheduler source supports an opt-in whale_context
capability when pm is in scope. After the event-driven gate fires, the runner
adds a bounded public tape sample and up to two validated wallet movement
summaries to the model observation. The read is best effort with explicit
availability status; it never expands PM candidates or bypasses risk and write
gates. This is source awaiting hosted rollout and is not part of published
MCP 0.7.14.
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.
| 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
coinrithm-mcp
- Streamable HTTP (multi-user; no key in env — clients send their own):
| 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} |
In the current source (not yet in npm 0.7.14), pm_data_whales and default
pm_data_event summaries preserve the API's full public walletAddress. Pass
that value with its source to pm_data_whale_wallet for Polymarket, Limitless
or Myriad. The shorter wallet field is display text; a null or absent
walletAddress supplies no usable wallet identity, including anonymous Kalshi
trades. Wallet leaderboard rows use address for the same tool input.
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
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.