npm - @coinrithm/mcp-trading - Versions diffs - 0.7.3 → 0.7.4 - Mend

@coinrithm/mcp-trading 0.7.3 → 0.7.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md CHANGED Viewed

@@ -1,240 +1,277 @@
-# @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 four keyless `pm_data_*` tools serving CoinRithm's public cross-venue
-dataset: live odds across 11 venues (Polymarket, Kalshi, Smarkets, Limitless,
-Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx), 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 four 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) | `GET /api/prediction-markets/overview` |
-| `pm_data_events` | none (public) | `GET /api/prediction-markets/events` |
-| `pm_data_event` (source, slug) | none (public) | `GET /api/prediction-markets/events/:source/:slug` |
-| `pm_data_whales` | none (public) | `GET /api/prediction-markets/whales` |
-The four `pm_data_*` tools wrap CoinRithm's free public cross-venue dataset
-(all 11 venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold,
-Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx). 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.
-Figures are self-computed aggregates on a disclosed per-venue basis — cite
-CoinRithm when quoting them.
-¹ 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 raw HTTP status + JSON body so the model sees real
-server responses (including `{ error, blockReasons }` on blocked entries).
-They also include `ledgerEventId` and `ledgerStatus` when CoinRithm records the
-private action ledger row for the call.
-## 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 ranked by realized paper PnL.
+**Plus a free prediction-market data surface — no key at all.** The same server
+ships four keyless `pm_data_*` tools serving CoinRithm's public cross-venue
+dataset: live odds across 11 venues (Polymarket, Kalshi, Smarkets, Limitless,
+Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx), 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 four 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_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 eight `pm_data_*` tools wrap CoinRithm's free public cross-venue dataset
+(all 11 venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold,
+Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx). 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.

package/dist/agent/cli.js CHANGED Viewed

@@ -43,12 +43,16 @@ function pinWarnings(path) {
         if (!existsSync(pin))
             return [];
         const parsed = parseYaml(readFileSync(pin, "utf8"));
-        const v = parsed?.api?.openapiVersion;
-        if (v && v !== COINRITHM_API.openapiVersion) {
-            return [
-                `⚠ functionality/coinrithm.yaml pins API ${v}; current is ${COINRITHM_API.openapiVersion} (warning only, not a block)`,
-            ];
+        const warnings = [];
+        const openapi = parsed?.api?.openapiVersion;
+        if (openapi && openapi !== COINRITHM_API.openapiVersion) {
+            warnings.push(`⚠ functionality/coinrithm.yaml pins API ${openapi}; current is ${COINRITHM_API.openapiVersion} (warning only, not a block)`);
         }
+        const mcp = parsed?.api?.mcpVersion;
+        if (mcp && mcp !== COINRITHM_API.mcpVersion) {
+            warnings.push(`⚠ functionality/coinrithm.yaml pins MCP ${mcp}; current is ${COINRITHM_API.mcpVersion} (warning only, not a block)`);
+        }
+        return warnings;
     }
     catch {
         /* ignore */

package/dist/agent/observe.d.ts CHANGED Viewed

@@ -4,4 +4,8 @@ export interface ObserveOutput {
     observation: Observation;
     skip?: string;
 }
+export declare function isCalibrationChurnMarket(market: {
+    slug?: string;
+    title?: string;
+}): boolean;
 export declare function observe(client: CoinRithmClient, spec: AgentSpec, state: RunState, trace?: AgentTrace): Promise<ObserveOutput>;

package/dist/agent/observe.js CHANGED Viewed

@@ -28,6 +28,16 @@ const PM_COIN_NAMES = {
     UNI: "Uniswap",
     SUI: "Sui",
 };
+// Repeated micro-contracts are useful for execution smoke tests but are a poor
+// calibration universe: outcomes overlap heavily, resolve too quickly to admit
+// meaningful independent research, and drown the public scorecard in Bitcoin
+// coin flips. Non-mechanical calibration agents receive a deeper discovery
+// page with these rows removed. Mechanical baselines intentionally keep the
+// unmodified universe so their reference contract remains reproducible.
+const PM_CALIBRATION_CHURN_RE = /(updown|up-or-down|-5-?min|-5m-|-15m|15m(?:-|$)|(?:5|15)\s+min(?:ute)?s?|-1h-|hourly|-daily-|\bdaily\b|what-price-will[^\n]*(?:today|tomorrow)|-above-on-|-price-on-|this[ -]week|of[ -]the[ -]week|-weekly-)/i;
+export function isCalibrationChurnMarket(market) {
+    return PM_CALIBRATION_CHURN_RE.test(`${market.slug ?? ""} ${market.title ?? ""}`);
+}
 // Fetch candles for one coin and reduce them to a compact indicator bundle.
 // Tolerant by design: any failure (HTTP error, malformed/sparse candles) returns
 // null so the cycle proceeds with price-only context rather than skipping.
@@ -289,6 +299,9 @@ export async function observe(client, spec, state, trace) {
     let pmResolutions = [];
     let pmMarkets = [];
     if (wantPm) {
+        const curatedCalibrationBoard = spec.objective?.primary === "calibration" &&
+            spec.model?.provider !== "mechanical";
+        const primaryDiscoveryLimit = curatedCalibrationBoard ? 30 : 12;
         // Bias PM discovery toward CRYPTO markets the agent has a price view on — the
         // only PM edge a price agent reliably has (probed 2026-06-24: the default board
         // is World Cup / elections / F1, which an agent has no edge on). The discover
@@ -299,7 +312,7 @@ export async function observe(client, spec, state, trace) {
         const pmQuery = PM_COIN_NAMES[topCoin] ?? spec.risk.watchlist[0] ?? "Bitcoin";
         const [pmPosR, pmDiscFirst] = await Promise.all([
             client.pmPositions(undefined, trace),
-            client.discoverPmMarkets({ q: pmQuery, limit: 12 }, trace),
+            client.discoverPmMarkets({ q: pmQuery, limit: primaryDiscoveryLimit }, trace),
         ]);
         let pmDiscR = pmDiscFirst;
         const firstCount = pmDiscR.ok
@@ -378,6 +391,9 @@ export async function observe(client, spec, state, trace) {
             // quoteable id NESTED at outcomes[].externalMarketId — expandPmMarkets turns
             // that into one row per quoteable outcome (eligible + not-held filtered).
             let mergedRows = expandPmMarkets(pmDiscR.data, heldPmKeys);
+            if (curatedCalibrationBoard) {
+                mergedRows = mergedRows.filter((market) => !isCalibrationChurnMarket(market));
+            }
             // ── Crypto-targeted secondary discover (pm_ref hallucination fix) ────────
             // The prompt tells the model its SHARPEST PM edge is the crypto price view it
             // JUST formed — but that is only actionable if the board actually LISTS a
@@ -409,10 +425,13 @@ export async function observe(client, spec, state, trace) {
                     // rows that actually reference the targeted coin (a fuzzy backend match
                     // can't dilute the board with off-topic events).
                     const primaryEventKeys = new Set(mergedRows.map((m) => `${m.source}|${m.slug}`));
-                    const secRows = expandPmMarkets(secR.data, heldPmKeys)
+                    let secRows = expandPmMarkets(secR.data, heldPmKeys)
                         .filter((m) => titleMentionsCoin(m.title, topAnalyzed))
-                        .filter((m) => !primaryEventKeys.has(`${m.source}|${m.slug}`))
-                        .slice(0, 4);
+                        .filter((m) => !primaryEventKeys.has(`${m.source}|${m.slug}`));
+                    if (curatedCalibrationBoard) {
+                        secRows = secRows.filter((market) => !isCalibrationChurnMarket(market));
+                    }
+                    secRows = secRows.slice(0, 4);
                     // Reserve slots for the targeted rows so the 12-cap can't slice off the
                     // very markets the secondary fetch exists to surface. Primary rows keep
                     // priority; the targeted rows are appended.