@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 seventeen keyless pm_data_* tools serving CoinRithm's public cross-venue
dataset: odds, cross-venue matches with a size-weighted reference probability,
a whale-trade tape, market-wide volume statistics, outcome price history and
order books, and resolved, expiring and surprise markets. 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. instrument_markets (strike
ladders on a coin, TradFi ticker or index), tradfi_references,
crypto_price, get_crypto_movers, get_arena_leaderboard and
get_arena_agent also work anonymously, for 23 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.19
The local server starts without COINRITHM_API_KEY in data-only mode, so
npx -y @coinrithm/mcp-trading gives prediction-market and crypto data with
no account; keyed tools return a structured missing_api_key result until a
key is set. Upstream calls time out after 35 s (upstream_timeout). The
hosted server adds per-client limits (120 requests a minute, 64 in flight),
drains open requests on deploy and reports its version on /health. The
default surface stays at 41 tools. See CHANGELOG.md.
Version 0.7.17 kept the default tool surface at 41 tools. Two server-wide
opt-in flags add tools that stay off unless enabled: the
PM paper v2 tools for configured house keys and
the spot reference tool.
The runner adds an opt-in capitalSizing.highConviction tier, widens a
correct-side take-profit that falls inside the agent's own reward:risk floor
(capital-sizing agents only) and records the requested and applied targets.
The next prompt lists the previous decision's refused actions, each open
position's stop-loss side of the mark, and which watched coins can take a new
futures entry. Pending futures exits are recorded as pending, not as executed
or failed. See CHANGELOG.md.
Version 0.7.16 (published 2026-10-07) rejects explicitly incomplete provider
responses before execution, including valid-looking prefixes, and preserves
their token usage. It also added configurable universe and signal boundaries,
PM policies, objective guidance, separately timed market context and the
record/bench/label evaluation tools. Funding-by-venue context does not
change settlement; optional data retains source, coverage and timing limits.
Benchmarks preserve missing outcomes and bounded route diagnostics. They do not
establish a profitable strategy or a superior model. See the
runner documentation.
Version 0.7.15 preserves observed-price evidence in public market summaries
(hasObservedPrice and bounded sourceObservation, including both sides of
venue comparisons), keeps full public walletAddress values in whale summaries
for pm_data_whale_wallet follow-up, adds the opt-in whale_context runner
capability, and records explicit zero model/action evidence for cycles skipped
before inference. pm_data_canonical documents the new canonical consensus
and labelled consensusHistory. The hosted HTTP server recovers the
pasted-markdown descriptor link (GET/HEAD redirect to the descriptor; POST runs
MCP). Trading limits, risk gates and retry counts are 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
Get a crk_live_… key from CoinRithm → Settings → 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.
Full guide (env vars, fail-closed guarantees, folder layout):
docs/agent-runner.md.
The hosted scheduler 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 for non-mechanical providers. The read is best effort with explicit
availability status; it never expands PM candidates or bypasses risk and write
gates. Owners can enable it in Agent Studio under Risk & caps; existing agents
remain opted out unless their owners choose it. It ships in package version
0.7.15; earlier MCP 0.7.14 does not include it.
The CoinRithm hosted scheduler runs this same engine for you — see the
scheduler README for the built,
DB-driven runtime.
Two ways to run
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 seventeen pm_data_* tools, instrument_markets, tradfi_references,
crypto_price, get_crypto_movers, get_arena_leaderboard and
get_arena_agent 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.
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,
GEMINI_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)
Run
- stdio (for Claude Desktop / Claude Code / Cursor / most MCP hosts):
- Streamable HTTP (multi-user; no key in env — clients send their own):
Tools
From package version 0.7.15 (not 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 seventeen 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 size-weighted cross-venue consensus on matched questions, weighted by
open interest or else liquidity); 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 up to
five outcomes plus outcomeCount. For open events, outcomes without a result
or a closed, resolved or voided lifecycle state come first; for other
event statuses, provider-confirmed winners come first. Within each group,
outcomes with valid probabilities sort highest first, with ties retaining
their original order. Follow with
pm_data_event(source, slug) for bounded event evidence, then request detail: "full" only when the complete provider-rich record is necessary.
Bounded outcome summaries may include hasObservedPrice and
sourceObservation: hasObservedPrice:false means the provider supplied no
usable observed price input, while an omitted hasObservedPrice field is
unknown. sourceObservation:null means unavailable provenance, not proof that
the outcome has no price. Neither field claims live pricing, liquidity or
tradability. priceBasis (Polymarket and Kalshi open outcomes) says what the
probability is: book_mid, last_trade, or unquoted, which means never
traded with no usable book, so the number is not a price.
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).
pm_data_price_history and pm_data_orderbook read one outcome's native
history and live book (Polymarket and Kalshi; other venues return an empty
series or orderBook: null). Both use 0-1 fractions, not the 0-100 points of
event outcomes; the history is evenly sampled to maxPoints with the raw
pointCount, and the book keeps the best depth levels per side with the full
level counts. pm_data_resolved, pm_data_expiring and pm_data_surprises
page the resolved archive, soon-ending open events and the biggest resolved
upsets, each row reduced to the same compact event summary.
instrument_markets answers "what do prediction markets imply for this
price": the contracts written on a coin (by slug, such as bitcoin), a TradFi
ticker or an index, grouped by expiry and settlement source with one ladder per
venue series. Probabilities are venue prices in 0-100 points, each ladder names
its settlement source and how it relates to the reference price, and the
payload carries no live price. The default asks for 10 ladders and omits venue
outcome ids; detail: "full" returns the untouched record. tradfi_references
lists the TradFi reference catalog (median of derivatives-venue index prices in
USDT, recorded every 15 minutes), filtered and paged on the server, or returns
one ticker with venue constituents, fundamentals and sampled history.
crypto_price is the keyless price for one coin by slug (such as bitcoin):
price in the requested fiat and in USD, 24h change, high and low, market cap
and rank, volume, and the live-price as-of. priceStale: true marks a last
known price older than 72 hours and marketCapSuspect a market cap CoinRithm
does not trust; fiatApplied: false means an untracked currency code was
answered in USD. candles adds bars over a range (1H to 1Y), merged to at most
maxPoints; the rolling 24h volume field v is left out because it cannot be
merged.
¹ 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. pm_data_event
also returns a bounded summary by default; pass detail: "full" to preserve
the full event response body. Action 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:
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:
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-v2,
five decided trades qualify an agent for normal ordering. The score is
realized PnL plus open losses (open gains never count); a positive score is
weighted by the 95% Wilson win-confidence lower bound; a non-positive score
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.
Opt-in PM paper v2 tools
The default tool list is unchanged. Set COINRITHM_PM_PAPER_V2_TOOLS_ENABLED=true
only for a server intended to expose the separately authorized house pilot:
discover_pm_paper_v2_markets, open_pm_paper_v2, close_pm_paper_v2, and
get_pm_paper_v2_positions. With both opt-in flags on, the server registers
54 tools.
These tools are meant for keys that match a configured house; discovery
returns 403 house_opt_in_required for any other key. Discovery returns
Kalshi and Polymarket outcomes with their stored native identity
(nativeMarket.key) and scheduled native end, filtered to the house's
configured horizon, and reports exclusions in meta.boundedSelection. It is
candidate evidence only: the open reacquires identity, maturity, book and fees
and can still refuse.
The API validates each request's key against its configured house tuple; the
client cannot choose an accounting model or wallet. Opens cover Kalshi and
Polymarket only. An exact decimal maxCashBudget (10 to 1,000,000 mUSD)
includes entry fees and never substitutes for legacy stake. API-key opens must
send forecastProbability: the chance that the side you buy pays out, as a
percent above 1 and below 100 ("62.5"), or as a fraction above 0 and below 1
("0.625"). Exactly 1 is refused as ambiguous, as are 0 and 100; the
tool schema rejects these locally. The API refuses an open without it (forecast_required) or when it does not exceed the
fee-inclusive cost per share (entry_forecast_not_above_cost).
Idempotency keys use the pm-entry: and pm-exit: prefixes. A close may
return HTTP 202 (accepted, still pending); only executed: true confirms
completion. Reuse the same scoped idempotency key and body after uncertain
delivery. Disabling entry admission still permits prior-receipt reconciliation
and management of already-open paper exposure.
Opt-in spot reference tool
COINRITHM_SPOT_REFERENCE_TOOLS_ENABLED=true adds get_spot_reference on an
explicitly opted-in MCP server. It is off by default and independent of the PM
tool flag. The 49 default tools, hosted runner observations and existing agent
prompts stay unchanged. Enabling this server-wide flag advertises the tool to
every client of that server; keep it off on shared servers serving existing
agents unless those clients are intentionally opted in.
The tool accepts a coinId from resolve_symbol and optional agentTrace,
requires the caller's read scope and calls GET /api/agent/spot/reference/:coinId
without query parameters. It returns the server's complete reference response,
including unavailable reasons, stale fallback status and original timestamps.
The API's separate BINANCE_SPOT_REFERENCE_ENABLED flag controls stream reads;
disabled or missing stream data can still return a stored fallback.
Stream last-ticker price and rolling 24h quote volume are denominated in USDT;
the stored REST consensus fallback is USD. No conversion or consensus replacement
is implied. Check each branch's status and expiresAt; preferredSource is not
a freshness or execution guarantee. Emission, statistics-window close, receipt
and local price-change times are distinct; lastTradeAt is unknown. The result
does not supply executable depth, change paper fills or replace market context.
