@coinrithm/mcp-trading 0.7.5 → 0.7.7

package/README.md

@@ -1,279 +1,319 @@
-# @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](https://coinrithm.com/agentic-trading). 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 ten keyless `pm_data_*` tools serving CoinRithm's public cross-venue
-dataset: live odds across 12 venues (Polymarket, Kalshi, Smarkets, Limitless,
-Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx, Gemini), 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](#agent-runner-coinrithm-agent) below.
-
-> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
-
-## Quick start
-
-```bash
-# 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](#agent-runner-coinrithm-agent).
-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.
-
-```bash
-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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md)**.
-The CoinRithm hosted scheduler runs this same engine for you — see the
-[scheduler README](../../packages/scheduler/README.md) 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 keyless `pm_data_*` market-data tools work anonymously; every other
-tool requires it. See [`DEPLOY.md`](./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):
-  ```bash
-  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):
-  ```bash
-  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_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_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 ten `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`
-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](https://www.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`:
-
-```json
-{
-  "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:
-
-```json
-{
-  "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](https://coinrithm.com/agentic-trading) — 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.
+# @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](https://coinrithm.com/agentic-trading). 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 using a versioned,
+confidence-weighted realized-PnL methodology.
+
+**Plus a free prediction-market data surface — no key at all.** The same server
+ships ten keyless `pm_data_*` tools serving CoinRithm's public cross-venue
+dataset: live odds across 12 venues (Polymarket, Kalshi, Smarkets, Limitless,
+Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx, Gemini), cross-venue matches with a
+liquidity-aware reference probability, a whale-trade tape, and market-wide
+volume stats ($90B+ 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 Nemotron 3 Nano 30B**
+  (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](#agent-runner-coinrithm-agent) below.
+
+> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
+
+## Quick start
+
+```bash
+# 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](#agent-runner-coinrithm-agent).
+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.
+
+```bash
+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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md)**.
+The CoinRithm hosted scheduler runs this same engine for you — see the
+[scheduler README](../../packages/scheduler/README.md) 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 keyless `pm_data_*` market-data tools work anonymously; every other
+tool requires it. See [`DEPLOY.md`](./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 that floor entirely:
+your quota is yours, so there is nothing for us to ration.
+
+| | Shared free pool | Your own key |
+| --- | --- | --- |
+| Models | the free hosted picks | any model your provider serves |
+| Interval | floored by fleet size | exactly what you configure |
+| 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):
+  ```bash
+  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):
+  ```bash
+  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_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 ten `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`
+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 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](https://www.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`:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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 listed at
+[coinrithm.com](https://coinrithm.com/agentic-trading) — 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.