@coinrithm/mcp-trading 0.7.7 → 0.7.9

package/CHANGELOG.md

@@ -5,6 +5,184 @@ ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (t
 self-host agent runner) — versioned together. The CoinRithm **API contract** is
 versioned separately (see `openapi.yaml` `info.version`, currently `1.7.0`).
 
+## 0.7.9
+
+This entry describes the package contents. Check npm for publication status;
+a source version or hosted deployment does not confirm npm delivery.
+
+Public market-data fidelity and runner reliability release. No MCP tool was
+renamed or removed, and the API **contract stays 1.7.0**.
+
+**PM evaluation budget.** Event-driven periodic prediction-market evaluations
+now respect `maxLlmCallsPerHour` after their cooldown elapses. Budget skips make
+no provider call and consume no call allowance. PM keeps its own cooldown;
+open-position management and explicit always-on behavior retain their existing
+exemptions. This runner gate is separate from hosted provider-capacity admission.
+
+**Retry-After parsing.** Missing, blank or malformed headers no longer become
+zero-delay retries. The runner API client uses its existing five-second fallback;
+explicit zero, numeric seconds and HTTP dates remain supported. Model-provider
+cooldowns share the parser and retain their existing one-hour cap.
+
+**API request deadlines.** Each runner API operation now has a 30-second total
+deadline covering response headers, body reads and all 429 retry waits. The
+same client serves the hosted scheduler. Embedded callers can set a finite
+`requestTimeoutMs` and supply an `AbortSignal`. A timeout or cancellation returns
+an uncertain transport result without automatically replaying a trading write.
+Timers and listeners are removed when the operation finishes.
+
+**State persistence.** Self-host state is serialized to a private temporary file
+and atomically renamed over the previous state. A failed serialization or rename
+leaves the prior state intact. This is atomic replacement, not a claim of durable
+storage across power loss.
+
+**Agent conversion.** `coinrithm-agent eject` preserves explicit `triggerPolicy`
+and `capitalSizing` blocks. Previously conversion could restore default hourly
+budgets and drop equity sizing.
+
+**Release verification.** All-source coverage gates, mandatory PostgreSQL CI,
+dependency updates and corrected client setup docs are included. See the
+[reliability record](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/RELIABILITY.md).
+
+**Confirmed-action journal.** Completed-action memory now requires an action
+to be both accepted and executed. Failed writes and uncertain transport results
+retain their attempt evidence without becoming completed moves in the next
+decision prompt. Dry-run proposals remain unexecuted.
+
+**Direct NVIDIA retry.** One complete HTTP 500/502/503/504 response can be
+retried once on the identical direct NVIDIA route within the original deadline.
+Both attempts are retained. This does not retry trading writes or change the
+hosted shared-pool routing policy.
+
+**Capital reconciliation.** Frozen-balance rounding residue down to -1e-8 is
+normalized only in the sizing calculation after the independent reads agree.
+Negative spendable cash still fails closed; wallet balances are not changed.
+
+**Private decision input evidence.** The bounded numeric projection includes
+nested indicator inputs and context movers, with legacy v1 records still readable.
+It does not retain hidden reasoning or raw model output.
+
+**Compact prediction-market evidence.** Discovery and compact event-detail
+responses now retain the API's `source.quoteScale`, `source.methodology` and
+`source.supportsMarketMetrics`, plus `spreadPoints`, `probabilityBook` and
+each retained outcome's `normalizedProbability`. Venue-native bid/ask quotes
+are never rescaled or interpreted from magnitude. Normalization remains the
+API's calculation over the original full book, not the truncated top-five
+outcome list. Existing payload bounds and explicit `detail: full` behavior
+are unchanged.
+
+**Settlement-time provenance.** Compact events retain `resolvedAtBasis` and
+`settlementWindowClosedAt`, keeping provider expiration distinct from an
+announced settlement time. Null and absent upstream evidence stay null and
+absent; the MCP does not infer missing values.
+
+**Candle semantics.** The `get_candles` description now states that these are
+sampled composite-price bars. Each bar's `v` is a mean rolling 24-hour
+quote-volume observation in USD, not volume traded during the candle, and
+must not be summed across bars.
+
+**HTTP completion diagnostics.** The hosted HTTP
+entry now has a bounded, stderr-only completion observer with final SDK-result
+and finish/abort accounting. Initialization, discovery, tool failures and
+successful delivery are distinct; unknown tool names are normalized. Records
+contain no arguments, bodies, credentials, caller/RPC IDs or caller-origin labels.
+Credential presence is not authentication. Durations describe the HTTP request,
+shared by batch members; server finish does not prove client receipt or use.
+Stdio, tools, authentication and dependency versions are unchanged. See
+`DEPLOY.md` for the measurement and retention limits. Hosted source/image
+`18a0bb6a8a0665e91cebc10225fec6f7ebcdaaf7` passed a bounded anonymous smoke on
+2026-09-13. Hosted verification and npm publication are separate release steps.
+
+**Deployment boundaries.** Hosted scheduler admission reasons are private
+scheduler telemetry, not a new SDK or MCP response field. The API's corrected
+comparison probabilities and enriched spread names use the existing response
+shape and reach current clients through fresh API reads. Outcome display names
+may change; use source/event/outcome identifiers for identity, never summed
+prices or matching labels alone. These fixes do not establish trading returns.
+
+## 0.7.8
+
+Runner decision-quality, evidence and paper-capital release. Additive: no MCP
+tool was renamed or removed, and the API **contract stays 1.7.0**. This release
+contains all package changes since published 0.7.7 (`gitHead` `80d0cae`), not
+just the previously listed thesis work.
+
+**Thesis exits.** Every opening action (`futures_open`, `spot_order`,
+`pm_open`) now carries a `thesis`: a one-sentence summary plus an
+`invalidation` with at least one machine-checkable condition (`priceBelow` /
+`priceAbove` for coins, `probabilityBelow` / `probabilityAbove` for prediction
+markets, a `maxHoldMinutes` time stop, and a free-text `catalyst` the model
+re-judges itself). The runner binds the thesis to the position the server
+returns, sanitized side-aware (a rising price never invalidates a long; a
+wrong-side level is dropped rather than re-signed; the time stop is clamped to
+60 minutes .. 30 days), persists it in the run state (`RunState.theses`, the
+same state file / `agent_state` JSON as before, no schema change) and
+re-evaluates it every cycle. A futures position whose price level or time stop
+is breached is closed by the runner before the model is asked anything, logged
+as a `thesis_invalidated` exit with its own idempotency key, after the
+kill-switch and drawdown checks and never instead of them. Prediction-market
+positions have no close endpoint, so a broken PM thesis is surfaced to the
+model instead (do not add, let it settle). The parser is tolerant (a malformed
+thesis never fails the open; a thesis copied onto a close is ignored) and the
+structured-output schema requires it, so schema-enforced hosted models always
+emit one.
+
+**Fundamentals in the observation.** Each watch entry now carries
+`fundamentals` sourced only from calls the runner already makes: `categories`,
+`marketCapRank` and `marketCapUsd` from the market context; `volume24hUsd` from
+the candles the `indicators` capability already fetches (live-probed
+2026-09-02: each bar's `v` is a rolling 24h volume, so the latest bar is the
+24h figure, never the sum); and up to three `headlines` with `publishedAt`
+timestamps from the one `news` call, attributed through the curated coin-news
+graph. Discovered PM markets carry `endDate` and `liquidityUsd`; open PM
+positions carry their title, side, entry and current probability and
+`openedAt`; open futures positions carry `openedAt`. The system prompt states
+the thesis contract, the runner-enforced exit and how to grade a trade on the
+fundamentals. Not carried, because no agent endpoint serves them: an "about"
+text per coin, a 24h probability change and a cross-venue divergence per PM
+market.
+
+**Fix:** the public movers feed serializes `change24h` / `currentPrice` as
+decimal strings; the universe-scan context rows read them strictly as numbers
+and shipped `undefined` for every mover.
+
+**Opt-in equity-based paper sizing.** A runner can size entries from a
+conservative fraction of its independently attributed paper book instead of a
+fixed stake/margin. The book is accepted only when wallet identity, cash
+partitions, held-position attribution and spot-mark coverage reconcile. Quotes
+then enforce per-entry, per-symbol, deployed-capital and daily-entry limits;
+fee buffers and the API's fee-inclusive quote evidence are included. Any
+missing or inconsistent evidence fails closed. Legacy positions on a different
+book remain visible for management but never inflate the current book's buying
+power.
+
+**Prediction-market decisions use executable economics.** PM opens now reject
+an invalid raw probability and a model forecast that does not clear the quoted
+entry price. Forecast edge is measured against the actual fee/slippage-adjusted
+fill, not the headline market probability. Quote-expiry outcomes are recorded
+separately from risk/balance rejection, and futures risk/reward validation uses
+fee-inclusive entry and stop economics.
+
+**Decision evidence is structured and bounded.** Cycles can expose a sanitized,
+partial private decision-input record: configuration and observation
+fingerprints, daily budget and guard state, plus bounded observation rows with
+explicit omission counts. It is not a prompt, transcript, raw model output or
+hidden reasoning record. The runner also reports quote/validation evidence for
+abstained, forecast-only and quote-expired PM opportunities. Hosted persistence
+and retention remain the caller's responsibility.
+
+**Runtime controls are more faithful.** The model sees the remaining daily
+entry/add budget rather than only static maxima. Entry caps still block new
+risk, while closes and other risk-reducing actions remain available. Direct
+provider HTTP 429 responses are capacity skips rather than model failures, so
+BYO agents do not build a failure streak during ordinary quota pressure.
+Structured-tool decisions remain required where the provider supports that
+contract.
+
+**Scorecard fix.** Maximum drawdown now measures decline from starting equity,
+so an immediate loss is no longer hidden by treating the first post-trade point
+as the high-water mark.
+
 ## 0.7.7
 
 Reliability release. Every change here came from a live production failure, not

package/README.md

@@ -4,16 +4,18 @@
 (Claude, GPT, Gemini, Llama…) a 50,000 mUSD virtual account and let it trade
 spot, futures, and prediction markets on
 [CoinRithm](https://coinrithm.com/agentic-trading). No real money, no exchange,
-no risk — a proving ground to show an agent works *before* anything is on the
-line, with a public **Agent Arena** leaderboard using a versioned,
-confidence-weighted realized-PnL methodology.
+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 ten keyless `pm_data_*` tools serving CoinRithm's public cross-venue
-dataset: live odds across 12 venues (Polymarket, Kalshi, Smarkets, Limitless,
-Manifold, Metaculus, PredictIt, Rothera, Futuur, Myriad, ForecastEx, Gemini), cross-venue matches with a
-liquidity-aware reference probability, a whale-trade tape, and market-wide
-volume stats ($90B+ all-time tracked). Point any MCP client at the hosted
+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 only needed for the trading tools.
 
@@ -23,8 +25,9 @@ Agents are **OKF bundles** — an open, model-agnostic folder of markdown + YAML
 
 - **Managed — nothing to install.** Build and deploy an agent in your browser
   with the **Agent Studio** (CoinRithm → My Agents → Studio): fork a house agent
-  or write one from scratch, and CoinRithm runs it **free on Nemotron 3 Nano 30B**
-  (NVIDIA NIM) on an always-on scheduler. The fastest path to a live agent.
+  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.
@@ -39,6 +42,17 @@ This package ships two binaries:
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
+## Version 0.7.9
+
+This version includes the market-data fidelity and runner reliability fixes
+listed in [CHANGELOG.md](./CHANGELOG.md). Check `npm view @coinrithm/mcp-trading
+version` for the latest published version. 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.
+
 ## Quick start
 
 ```bash
@@ -48,13 +62,15 @@ 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`.
+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
+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.
 
@@ -68,15 +84,15 @@ COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
 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,
+[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` |
+| 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
@@ -89,15 +105,16 @@ tool requires it. See [`DEPLOY.md`](./DEPLOY.md).
 The hosted Agent Studio runs your agent free on a shared pool of NVIDIA-hosted
 models. That pool is a **fixed budget shared by every hosted agent**, so the
 scheduler floors how often a shared agent may run, and the floor stretches as
-more agents join. Bringing your own model key removes that floor entirely:
-your quota is yours, so there is nothing for us to ration.
+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 | exactly what you configure |
-| Rerouting | we may serve a live alternate when a model is rate-limited | never rerouted, your route is pinned |
-| Cost | free | you pay your provider, not CoinRithm |
+|           | 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
@@ -113,11 +130,11 @@ 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 |
+| 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
 
@@ -136,46 +153,46 @@ agent file.
 
 ## Tools
 
-| Tool | Scope | Wraps |
-| --- | --- | --- |
-| `whoami` | any | `GET /api/agent/me` |
-| `get_portfolio` | read | `GET /api/agent/portfolio` |
-| `get_wallet` | read | `GET /api/agent/wallet` |
-| `resolve_symbol` | read | `GET /api/agent/resolve` |
-| `get_equity_curve` | read | `GET /api/agent/equity-curve` |
-| `get_my_trades` (venue) | read | `GET /api/agent/trades` |
-| `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
-| `get_candles` (coinId, range) | read | `GET /api/agent/market/:coinId/candles` |
-| `discover_pm_markets` | read | `GET /api/agent/pm/discover` |
-| `get_performance` | read | `GET /api/agent/performance` |
-| `get_agent_ledger` | read | `GET /api/agent/ledger` |
-| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
-| `export_run_evidence` | read | `GET /api/agent/ledger/export?runId=...` |
-| `get_arena_leaderboard` | read | `GET /api/arena` |
-| `get_arena_agent` (handle) | read | `GET /api/arena/:handle` |
-| `list_open_orders` | read | `GET /api/agent/orders/open` |
-| `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
-| `spot_quote` | read | `POST /api/agent/spot/quote` |
-| `futures_quote` | read | `POST /api/agent/futures/quote` |
-| `pm_quote` | read | `POST /api/agent/pm/quote` |
-| `place_spot_order` | trade:spot | `POST /api/agent/spot/order` |
-| `cancel_spot_order` | trade:spot | `POST /api/agent/spot/order/:id/cancel` |
-| `open_futures_position` | trade:futures | `POST /api/agent/futures/open` ¹ |
-| `set_futures_sl_tp` | trade:futures | `POST /api/agent/futures/sl-tp` ² |
-| `close_futures_position` | trade:futures | `POST /api/agent/futures/close` |
-| `open_pm_position` | trade:pm | `POST /api/agent/pm/open` ¹ |
-| `report_pm_opportunity` | read | `POST /api/agent/pm/opportunity` |
-| `pm_data_overview` | none (public) | compact `GET /api/prediction-markets/overview` |
-| `pm_data_sources` | none (public) | venue methodology, coverage, and comparable volume bases |
-| `pm_data_sources_health` | none (public) | per-venue freshness, lag, and degraded reasons |
-| `pm_data_events` | none (public) | compact `GET /api/prediction-markets/events` |
-| `pm_data_event` (source, slug, detail?) | none (public) | bounded event evidence by default; `detail: "full"` returns the untouched API record |
-| `pm_data_whales` (limit, default 10) | none (public) | compact `GET /api/prediction-markets/whales` |
-| `pm_data_disagreements` (limit, sort, sourceKind, ...) | none (public) | compact `GET /api/prediction-markets/matches/public` |
-| `pm_data_calibration` | none (public) | `GET /api/prediction-markets/calibration` |
-| `pm_data_canonical` (key?, limit, cursor) | none (public) | `GET /api/prediction-markets/canonical` (+ `/:key` detail) |
-| `pm_data_volume_history` | none (public) | `GET /api/prediction-markets/volume-history` |
-| `get_crypto_movers` (direction, limit) | none (public) | `GET /api/coins/top-{gainers,losers}` |
+| Tool                                                   | Scope         | Wraps                                                                                |
+| ------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------ |
+| `whoami`                                               | any           | `GET /api/agent/me`                                                                  |
+| `get_portfolio`                                        | read          | `GET /api/agent/portfolio`                                                           |
+| `get_wallet`                                           | read          | `GET /api/agent/wallet`                                                              |
+| `resolve_symbol`                                       | read          | `GET /api/agent/resolve`                                                             |
+| `get_equity_curve`                                     | read          | `GET /api/agent/equity-curve`                                                        |
+| `get_my_trades` (venue)                                | read          | `GET /api/agent/trades`                                                              |
+| `get_market_context` (coinId)                          | read          | `GET /api/agent/market/:coinId`                                                      |
+| `get_candles` (coinId, range)                          | read          | `GET /api/agent/market/:coinId/candles`                                              |
+| `discover_pm_markets`                                  | read          | `GET /api/agent/pm/discover`                                                         |
+| `get_performance`                                      | read          | `GET /api/agent/performance`                                                         |
+| `get_agent_ledger`                                     | read          | `GET /api/agent/ledger`                                                              |
+| `export_agent_ledger`                                  | read          | `GET /api/agent/ledger/export`                                                       |
+| `export_run_evidence`                                  | read          | `GET /api/agent/ledger/export?runId=...`                                             |
+| `get_arena_leaderboard`                                | read          | `GET /api/arena`                                                                     |
+| `get_arena_agent` (handle)                             | read          | `GET /api/arena/:handle`                                                             |
+| `list_open_orders`                                     | read          | `GET /api/agent/orders/open`                                                         |
+| `get_positions` (venue)                                | read          | `GET /api/agent/positions/{futures,pm}`                                              |
+| `spot_quote`                                           | read          | `POST /api/agent/spot/quote`                                                         |
+| `futures_quote`                                        | read          | `POST /api/agent/futures/quote`                                                      |
+| `pm_quote`                                             | read          | `POST /api/agent/pm/quote`                                                           |
+| `place_spot_order`                                     | trade:spot    | `POST /api/agent/spot/order`                                                         |
+| `cancel_spot_order`                                    | trade:spot    | `POST /api/agent/spot/order/:id/cancel`                                              |
+| `open_futures_position`                                | trade:futures | `POST /api/agent/futures/open` ¹                                                     |
+| `set_futures_sl_tp`                                    | trade:futures | `POST /api/agent/futures/sl-tp` ²                                                    |
+| `close_futures_position`                               | trade:futures | `POST /api/agent/futures/close`                                                      |
+| `open_pm_position`                                     | trade:pm      | `POST /api/agent/pm/open` ¹                                                          |
+| `report_pm_opportunity`                                | read          | `POST /api/agent/pm/opportunity`                                                     |
+| `pm_data_overview`                                     | none (public) | compact `GET /api/prediction-markets/overview`                                       |
+| `pm_data_sources`                                      | none (public) | venue methodology, coverage, and comparable volume bases                             |
+| `pm_data_sources_health`                               | none (public) | per-venue freshness, lag, and degraded reasons                                       |
+| `pm_data_events`                                       | none (public) | compact `GET /api/prediction-markets/events`                                         |
+| `pm_data_event` (source, slug, detail?)                | none (public) | bounded event evidence by default; `detail: "full"` returns the untouched API record |
+| `pm_data_whales` (limit, default 10)                   | none (public) | compact `GET /api/prediction-markets/whales`                                         |
+| `pm_data_disagreements` (limit, sort, sourceKind, ...) | none (public) | compact `GET /api/prediction-markets/matches/public`                                 |
+| `pm_data_calibration`                                  | none (public) | `GET /api/prediction-markets/calibration`                                            |
+| `pm_data_canonical` (key?, limit, cursor)              | none (public) | `GET /api/prediction-markets/canonical` (+ `/:key` detail)                           |
+| `pm_data_volume_history`                               | none (public) | `GET /api/prediction-markets/volume-history`                                         |
+| `get_crypto_movers` (direction, limit)                 | none (public) | `GET /api/coins/top-{gainers,losers}`                                                |
 
 `get_crypto_movers` is the universe scan: the biggest 24h movers across every
 coin CoinRithm tracks, so an agent can find candidates it was never configured

package/dist/agent/act.js

@@ -1,15 +1,11 @@
 // Act phase: fetch the quote evidence for an open (the runner does this, never
 // the model) and execute a validated action (futures / spot / PM) with an
 // idempotency key.
-import { asObj, asNum, asStr } from "./extract.js";
+import { asObj, asNum } from "./extract.js";
+import { freshnessOf } from "./pmContext.js";
 function coinIdFor(observation, symbol) {
     return (observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined);
 }
-function freshnessOf(block) {
-    const fr = asObj(block.freshness);
-    const status = asStr(fr.status);
-    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
-}
 // Read-only quote BEFORE any open. Returns ineligible (never throws) on error.
 export async function fetchQuote(client, action, observation, trace) {
     let r;
@@ -50,7 +46,24 @@ export async function fetchQuote(client, action, observation, trace) {
         entryPrice: asNum(d.entryPrice), // futures
         liquidationPrice: asNum(d.liquidationPrice), // futures
         executionPrice: asNum(d.executionPrice), // spot live fill price
+        entryProbability: asNum(d.entryProbability), // pm raw probability POINTS
+        ...(action.type === "pm_open"
+            ? {
+                stakeMusd: asNum(d.stakeMusd),
+                sharesEstimate: asNum(d.sharesEstimate),
+            }
+            : {}),
         estimatedCostMusd: asNum(d.estimatedCostMusd), // spot gross notional
+        ...(action.type === "spot_order"
+            ? { estimatedFeeMusd: asNum(d.estimatedFeeMusd) }
+            : {}),
+        ...(action.type === "futures_open"
+            ? {
+                futuresFeeBps: asNum(asObj(d.executionModel).feeBps),
+                estimatedEntryFeeMusd: asNum(asObj(d.executionModel).estimatedEntryFeeMusd),
+                cashRequiredMusd: asNum(d.cashRequiredMusd),
+            }
+            : {}),
         // 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

package/dist/agent/capitalSizing.d.ts

@@ -0,0 +1,32 @@
+import type { AgentSpec, CapitalBook, CapitalSizingAdjustment, Observation, ProposedAction, QuoteEvidence } from "./types.js";
+export declare const CAPITAL_VALUATION_BASIS = "wallet_assets_spot_marked_futures_pm_at_collateral";
+export declare const CAPITAL_FEE_BUFFER_BPS = 10;
+/** Reconcile the bounded open-position reads against the wallet's frozen
+ * buckets. A full page is not assumed complete: the collateral checksums must
+ * agree. No held mark, unknown status, missing bucket, or mismatched book can
+ * silently become zero exposure. Lists retain legacy positions on other books
+ * for management; only explicitly attributed current-book rows reconcile its
+ * cash and marks. Closed history never contributes unrealized. */
+export declare function deriveCapitalBook(portfolio: unknown, wallet: unknown, futures: unknown, pm: unknown): CapitalBook;
+export interface CapitalBudget {
+    cashAvailableMusd: number;
+    committedCapitalMusd: number;
+    openMarginMusd: number;
+}
+export declare const usesCapitalSizing: (spec: AgentSpec, mechanical?: boolean) => boolean;
+export declare function prepareCapitalAction(action: ProposedAction, spec: AgentSpec, observation: Observation, budget: CapitalBudget): {
+    action: ProposedAction;
+    adjustment?: CapitalSizingAdjustment;
+    rejection?: string;
+};
+/** Quote-bound monetary checks. Drift fails closed; never requote a resized
+ * ticket, silently widen a cap, or credit uncertain close/sell proceeds. */
+export declare function validateCapitalAction(action: ProposedAction, spec: AgentSpec, observation: Observation, budget: CapitalBudget, quote?: QuoteEvidence): string | undefined;
+/** Fee-inclusive opt-in reservation; the legacy gross helper stays unchanged.
+ * The API quotes a market fill even for a pending limit/stop order. Reserve at
+ * least that fee, scaled up if the proposed price requires more notional.
+ * This is conservative captured quote evidence, not a future fill guarantee. */
+export declare function capitalSpotBuyCost(action: Extract<ProposedAction, {
+    type: "spot_order";
+}>, quote?: QuoteEvidence): number | undefined;
+export declare function capitalCashCost(action: ProposedAction, quote?: QuoteEvidence): number;