@coinrithm/mcp-trading 0.7.2 → 0.7.4

package/README.md

@@ -1,238 +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 10 venues (Polymarket, Kalshi, Smarkets, Limitless,
-Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad), 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 ten venues: Polymarket, Kalshi, Smarkets, Limitless, Manifold,
-Metaculus, PredictIt, Rothera, Futuur, Myriad). 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, no explicit
-commission/slippage in v1, no futures funding/fees, 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/act.d.ts

@@ -1,4 +1,4 @@
-import { CoinRithmClient } from "./client.js";
+import { CoinRithmClient, ProvenanceReport } from "./client.js";
 import { ProposedAction, AgentTrace, ApiResult, Observation, QuoteEvidence } from "./types.js";
 export declare function fetchQuote(client: CoinRithmClient, action: ProposedAction, observation: Observation, trace?: AgentTrace): Promise<QuoteEvidence | undefined>;
-export declare function executeAction(client: CoinRithmClient, action: ProposedAction, observation: Observation, trace: AgentTrace, idempotencyKey: string): Promise<ApiResult>;
+export declare function executeAction(client: CoinRithmClient, action: ProposedAction, observation: Observation, trace: AgentTrace, idempotencyKey: string, provenance?: ProvenanceReport): Promise<ApiResult>;

package/dist/agent/act.js

@@ -3,7 +3,7 @@
 // idempotency key.
 import { asObj, asNum, asStr } from "./extract.js";
 function coinIdFor(observation, symbol) {
-    return observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined;
+    return (observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined);
 }
 function freshnessOf(block) {
     const fr = asObj(block.freshness);
@@ -17,7 +17,12 @@ export async function fetchQuote(client, action, observation, trace) {
         const coinId = coinIdFor(observation, action.symbol);
         if (!coinId)
             return { eligible: false, blockReasons: ["unresolved_symbol"] };
-        r = await client.futuresQuote({ coinId, side: action.side, leverage: action.leverage, marginMusd: action.marginMusd }, trace);
+        r = await client.futuresQuote({
+            coinId,
+            side: action.side,
+            leverage: action.leverage,
+            marginMusd: action.marginMusd,
+        }, trace);
     }
     else if (action.type === "spot_order") {
         const coinId = coinIdFor(observation, action.symbol);
@@ -48,9 +53,17 @@ export async function fetchQuote(client, action, observation, trace) {
         estimatedCostMusd: asNum(d.estimatedCostMusd), // spot gross notional
         // Freshness lives in the response's `observation` block (anti-look-ahead).
         freshness: freshnessOf(asObj(d.observation)),
+        // PM open-time quality-gate preview (additive; older backends omit it → the
+        // runner just doesn't early-skip and falls through to the normal path).
+        openBlocked: d.openBlocked === true,
+        openBlockReasons: d.openBlockReasons,
     };
 }
-export async function executeAction(client, action, observation, trace, idempotencyKey) {
+export async function executeAction(client, action, observation, trace, idempotencyKey, 
+// Optional SELF-REPORTED runner provenance, attached to a pm_open only (the one
+// durable-artifact write path here). Absent => the request is byte-identical to
+// pre-provenance behavior.
+provenance) {
     if (action.type === "futures_open") {
         const coinId = coinIdFor(observation, action.symbol);
         if (!coinId)
@@ -114,6 +127,14 @@ export async function executeAction(client, action, observation, trace, idempote
             outcomeExternalMarketId: action.outcomeExternalMarketId,
             stakeMusd: action.stakeMusd,
             idempotencyKey,
+            // The agent's OWN independent forecast (already clamped/omitted by the runner).
+            // Included ONLY when present, so an absent forecast leaves the request body
+            // byte-identical to pre-forecast behavior.
+            ...(action.forecastProbability != null
+                ? { forecastProbability: action.forecastProbability }
+                : {}),
+            // Attach runner provenance only when present (byte-identical to before when absent).
+            ...(provenance ? { provenance } : {}),
             agentTrace: trace,
         });
     }