@coinrithm/mcp-trading 0.7.16 → 0.7.17

package/README.md

@@ -1,415 +1,486 @@
-# @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,
-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. `get_crypto_movers`,
-`get_arena_leaderboard` and `get_arena_agent` also work anonymously,
-for **15 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](#agent-runner-coinrithm-agent) below.
-
-> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
-
-## Version 0.7.16 (unpublished)
-
-The runner rejects explicitly incomplete provider responses before execution,
-including valid-looking prefixes, and preserves their token usage. Bounded
-shape diagnostics still reject string-valued actions. These guards do not raise
-completion limits, repair model proposals or change customer strategies.
-
-This release also includes 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 changelog and
-[runner documentation](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md).
-
-The preceding published version, 0.7.15, includes the following capabilities.
-
-It 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](./CHANGELOG.md).
-Check `npm view @coinrithm/mcp-trading version` and the
-[release status](https://github.com/CoinRithm/coinrithm-agent-trading#version-clarity)
-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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md#binding-entry-conditions-and-strategy-prose)
-for the exact opt-in policy and persistence contract.
-
-## 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? 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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/RELIABILITY.md).
-
-## 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 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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/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 twelve `pm_data_*` tools, `get_crypto_movers`, `get_arena_leaderboard` and
-`get_arena_agent` work anonymously. Account and trading tools require 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 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):
-  ```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_news` (coins, limit?, hours?, minImportance?)     | read          | `GET /api/agent/news`                                                                |
-| `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`                                | none (public) | `GET /api/arena`                                                                     |
-| `get_arena_agent` (handle)                             | none (public) | `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}`                                                |
-
-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 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 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).
-
-¹ 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](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 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](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.
+# @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,
+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. `get_crypto_movers`,
+`get_arena_leaderboard` and `get_arena_agent` also work anonymously,
+for **15 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](#agent-runner-coinrithm-agent) below.
+
+> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
+
+## Version 0.7.17
+
+The default tool surface is unchanged at 41 tools. Two server-wide opt-in
+flags add tools that stay off unless enabled: the
+[PM paper v2 tools](#opt-in-pm-paper-v2-tools) for configured house keys and
+the [spot reference tool](#opt-in-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](./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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md).
+
+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](./CHANGELOG.md).
+Check `npm view @coinrithm/mcp-trading version` and the
+[release status](https://github.com/CoinRithm/coinrithm-agent-trading#version-clarity)
+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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md#binding-entry-conditions-and-strategy-prose)
+for the exact opt-in policy and persistence contract.
+
+## 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 → Settings → API Keys. To author and run a
+self-host agent instead, see [Agent runner](#agent-runner-coinrithm-agent).
+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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/RELIABILITY.md).
+
+## 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 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](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/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 twelve `pm_data_*` tools, `get_crypto_movers`, `get_arena_leaderboard` and
+`get_arena_agent` work anonymously. Account and trading tools require 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 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`,
+`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)
+
+| Env var                                  | Required         | Default                     | Notes                                                                                     |
+| ---------------------------------------- | ---------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
+| `COINRITHM_API_KEY`                      | yes (stdio only) | —                           | A `crk_live_…` key from CoinRithm → Settings → 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                                                                           |
+| `COINRITHM_PM_PAPER_V2_TOOLS_ENABLED`    | no               | off                         | `true` adds the [PM paper v2 tools](#opt-in-pm-paper-v2-tools) for configured house keys. |
+| `COINRITHM_SPOT_REFERENCE_TOOLS_ENABLED` | no               | off                         | `true` adds [`get_spot_reference`](#opt-in-spot-reference-tool).                          |
+
+## 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_news` (coins, limit?, hours?, minImportance?)     | read          | `GET /api/agent/news`                                                                |
+| `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`                                | none (public) | `GET /api/arena`                                                                     |
+| `get_arena_agent` (handle)                             | none (public) | `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}`                                                |
+
+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 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 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).
+
+¹ 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](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 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](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.
+
+### 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
+46 tools.
+
+| Tool                           | Scope      | Wraps                                        |
+| ------------------------------ | ---------- | -------------------------------------------- |
+| `discover_pm_paper_v2_markets` | `read`     | `GET /api/agent/pm/v2/discover` (q?, limit?) |
+| `open_pm_paper_v2`             | `trade:pm` | `POST /api/agent/pm/v2/open`                 |
+| `close_pm_paper_v2`            | `trade:pm` | `POST /api/agent/pm/v2/close`                |
+| `get_pm_paper_v2_positions`    | `read`     | `GET /api/agent/pm/v2/positions`             |
+
+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 41 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.