@coinrithm/mcp-trading 0.7.6 → 0.7.8

package/CHANGELOG.md

@@ -5,6 +5,140 @@ 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.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
+from a roadmap. Additive: no tool renamed or removed, and the API **contract
+stays 1.7.0** because nothing on the documented surface changed.
+
+**Model requests are now built from a declared capability table, not
+assumptions.** `providerCapabilities.ts` states, per model family, which
+parameter carries the completion budget, whether a non-default temperature is
+allowed, and what extra body fields the family needs. Two failures this fixes:
+
+- **OpenAI's current models rejected our requests outright.** `gpt-5*` and
+  `o*` refuse `max_tokens` and any non-default `temperature`; they take
+  `max_completion_tokens`. The family is detected by MODEL id, not just the
+  provider name, so an OpenAI-compatible gateway serving `gpt-5` gets the same
+  shape. If you brought your own OpenAI key, this is why it now works.
+- **NVIDIA Nemotron models emitted a think-chain where the JSON decision
+  belonged**, which failed every cycle. The `chat_template_kwargs.enable_thinking=false`
+  switch and the "detailed thinking off" system hint are now encoded as data
+  rather than re-learned by failing.
+
+**New: `probeDecisionContract()`.** An HTTP 200 is not proof a route can run an
+agent. Both production failure modes returned 200s: a think-chain in the JSON
+slot, and an empty completion because a reasoning model spent its whole budget
+before answering. The probe sends a canned mini-observation through the REAL
+decision parser at a >=1024 completion allowance and classifies the result as
+`http`, `empty` or `parse`. Use it before adopting any model id; provider
+catalogs list ids that 404 on invoke.
+
+**Provider trouble no longer disables an agent.** A permanent-looking model
+error (404/410/decommissioned) used to disable the agent after a threshold. On
+2026-08-26 NVIDIA end-of-lifed an entire model line and 35 agents died on that
+path. The runner now reports a hold and keeps retrying each cadence, recovering
+by itself when the provider does. Disables remain for what deserves them:
+revoked credentials, drawdown, kill-switch, user action.
+
+**Failures carry structured metadata.** A failed `decide()` now returns
+`status` and, when the provider sends one, `retryAfterMs` (parsed from
+`Retry-After` in both delta-seconds and HTTP-date form, capped at an hour), so
+a caller can tell a 429 from a 5xx without parsing strings. Error text is
+unchanged.
+
+**`ClientConfig.extraHeaders`.** Headers attached to every request, spread
+before auth so they can never clobber it. Self-host has nothing to put here;
+it exists so CoinRithm's own hosted scheduler can present its attestation
+channel.
+
+**Model names corrected throughout.** The retired Llama 3.x line is gone from
+the README, the runtime defaults and the `quant-reference` example, which is
+relocked onto `nvidia/nemotron-3-nano-30b-a3b`.
+
 ## 0.7.6
 
 Agent capability release: universe discovery, first-class behavioral guards,

package/README.md

@@ -5,7 +5,8 @@
 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.
+line, with a public **Agent Arena** leaderboard using a versioned,
+confidence-weighted realized-PnL methodology.
 
 **Plus a free prediction-market data surface — no key at all.** The same server
 ships ten keyless `pm_data_*` tools serving CoinRithm's public cross-venue
@@ -22,7 +23,7 @@ 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 Llama 3.1 8B**
+  or write one from scratch, and CoinRithm runs it **free on Nemotron 3 Nano 30B**
   (NVIDIA NIM) on an always-on scheduler. The fastest path to a live agent.
 - **Self-host — this package.** Bring your own model key and run the
   `observe→decide→validate→act` loop on your machine, or wire the MCP server
@@ -83,6 +84,33 @@ key upstream. The Authorization header is **optional** on the hosted endpoint
 the ten keyless `pm_data_*` market-data tools work anonymously; every other
 tool requires it. See [`DEPLOY.md`](./DEPLOY.md).
 
+## Bring your own model key
+
+The hosted Agent Studio runs your agent free on a shared pool of NVIDIA-hosted
+models. That pool is a **fixed budget shared by every hosted agent**, so the
+scheduler floors how often a shared agent may run, and the floor stretches as
+more agents join. Bringing your own model key removes that floor entirely:
+your quota is yours, so there is nothing for us to ration.
+
+| | Shared free pool | Your own key |
+| --- | --- | --- |
+| Models | the free hosted picks | any model your provider serves |
+| Interval | floored by fleet size | exactly what you configure |
+| Rerouting | we may serve a live alternate when a model is rate-limited | never rerouted, your route is pinned |
+| Cost | free | you pay your provider, not CoinRithm |
+
+Providers accepted: `nvidia`, `openai`, `groq`, `anthropic`, and any
+`openai-compatible` endpoint (https base URL required). The key is validated by
+a **live decision probe before the agent is accepted** — a model that cannot
+return a parseable decision is rejected at deploy time rather than failing
+every scheduled cycle. Keys are encrypted at rest and never logged or echoed.
+
+Self-hosting through this package works the same way: set the provider's env
+var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `NVIDIA_API_KEY`, `GROQ_API_KEY`
+or `MODEL_API_KEY`) and the runner builds the request in the shape that
+provider's model family actually accepts. A model key is **never** read from an
+agent file.
+
 ## Configure (stdio)
 
 | Env var | Required | Default | Notes |
@@ -278,13 +306,14 @@ 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
+Opted-in agents are publicly listed at
 [coinrithm.com](https://coinrithm.com/agentic-trading) — set `agentName` /
 `agentPublic` / `agentModel` on your key to join, then check your standing
-with `get_arena_leaderboard` / `get_arena_agent`. 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).
+with `get_arena_leaderboard` / `get_arena_agent`. Under `arena-ranking-v1`,
+five decided trades qualify an agent for normal ordering. Positive realized
+PnL is weighted by the 95% Wilson win-confidence lower bound; non-positive PnL
+is used directly. Agents below five remain listed after qualified agents, and
+fewer than 20 decided trades carries a separate small-sample warning. The API
+returns the full machine-readable `contract` with every board response.
 
 stdout is the MCP JSON-RPC channel; this server logs only to stderr.

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;

package/dist/agent/capitalSizing.js

@@ -0,0 +1,257 @@
+// Opt-in, deterministic PAPER sizing. No provider, price or database reads.
+import { asNum, asObj } from "./extract.js";
+import { spotBuyCost } from "./types.js";
+import { validateCapitalSizingPolicy } from "./skillValidator.js";
+export const CAPITAL_VALUATION_BASIS = "wallet_assets_spot_marked_futures_pm_at_collateral";
+// Conservative pre-quote runner estimate: 10bp each way, with the exit fee
+// charged on stop notional. Actual API fee evidence is checked after ONE quote.
+// This is not an exchange-fill, funding or stop-execution guarantee.
+export const CAPITAL_FEE_BUFFER_BPS = 10;
+const CENT_TOLERANCE = 0.011;
+const centsDown = (n) => Math.floor(n * 100) / 100;
+const positive = (n) => asNum(n) !== undefined && n > 0;
+const nonnegative = (n) => asNum(n) !== undefined && n >= 0;
+/** 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 function deriveCapitalBook(portfolio, wallet, futures, pm) {
+    const p = asObj(portfolio), w = asObj(wallet), eq = asObj(p.equity), cash = asObj(w.usdt);
+    const unavailable = (reason) => ({
+        status: "unavailable",
+        reason,
+    });
+    if (p.bookScope !== "api_key")
+        return unavailable("independent_agent_book_unproven");
+    if (!Number.isSafeInteger(p.walletId) ||
+        p.walletId <= 0 ||
+        p.walletId !== w.walletId)
+        return unavailable("portfolio_wallet_identity_mismatch");
+    if (eq.valuationBasis !== CAPITAL_VALUATION_BASIS || !positive(eq.totalUsd))
+        return unavailable("portfolio_valuation_unavailable");
+    if (eq.spotValuationComplete !== true)
+        return unavailable("held_spot_valuation_unproven");
+    const buckets = ["available", "frozen", "frozenPm", "frozenFutures"];
+    for (const key of buckets) {
+        if (!nonnegative(cash[key]) ||
+            !nonnegative(eq[key]) ||
+            Math.abs(cash[key] - eq[key]) > CENT_TOLERANCE)
+            return unavailable("cash_partitions_incomplete_or_changed");
+    }
+    const cashTotal = buckets.reduce((sum, k) => sum + cash[k], 0);
+    if (eq.totalUsd + CENT_TOLERANCE < cashTotal)
+        return unavailable("wallet_asset_value_incoherent");
+    let negativeMarks = 0;
+    for (const [raw, bucket, amountKey, markKeys] of [
+        [futures, "frozenFutures", "marginMusd", ["unrealizedPnlMusd"]],
+        [pm, "frozenPm", "stakeMusd", ["unrealizedPnl", "unrealizedPnlMusd"]],
+    ]) {
+        const rows = asObj(raw).positions;
+        if (!Array.isArray(rows)) {
+            // PM is not fetched for a futures-only legacy universe. Zero frozen PM
+            // proves no tied-up PM collateral; a nonzero bucket must have coverage.
+            if (bucket === "frozenPm" && raw === undefined && cash[bucket] === 0)
+                continue;
+            return unavailable("position_coverage_unavailable");
+        }
+        let held = 0;
+        for (const row of rows) {
+            const position = asObj(row);
+            if (typeof position.status !== "string")
+                return unavailable("position_status_unavailable");
+            if (position.status !== "open")
+                continue;
+            if (!Number.isSafeInteger(position.walletId) ||
+                position.walletId <= 0)
+                return unavailable("held_position_wallet_unavailable");
+            // The key-scoped API includes legacy/shared-book positions. Their
+            // liabilities settle to their originating wallet, not this active book.
+            // Do not filter the management observation or credit their close proceeds.
+            if (position.walletId !== p.walletId)
+                continue;
+            const amount = position[amountKey];
+            const mark = markKeys
+                .map((key) => asNum(position[key]))
+                .find((n) => n !== undefined);
+            if (!nonnegative(amount) || mark === undefined)
+                return unavailable("held_position_mark_unavailable");
+            held += amount;
+            negativeMarks += Math.min(0, mark);
+        }
+        if (Math.abs(held - cash[bucket]) > CENT_TOLERANCE)
+            return unavailable("held_collateral_coverage_mismatch");
+    }
+    const conservativeEquityMusd = eq.totalUsd + negativeMarks;
+    if (!positive(conservativeEquityMusd))
+        return unavailable("nonpositive_conservative_equity");
+    return {
+        status: "ready",
+        walletId: p.walletId,
+        conservativeEquityMusd,
+        cashAvailableMusd: Math.min(cash.available, eq.available),
+        committedCapitalMusd: Math.max(0, eq.totalUsd - cash.available),
+    };
+}
+export const usesCapitalSizing = (spec, mechanical = false) => spec.capitalSizing !== undefined &&
+    !mechanical &&
+    spec.model?.provider !== "mechanical";
+const increases = (a) => a.type === "futures_open" ||
+    a.type === "pm_open" ||
+    (a.type === "spot_order" && a.side === "buy");
+export function prepareCapitalAction(action, spec, observation, budget) {
+    if (!usesCapitalSizing(spec) || !increases(action))
+        return { action };
+    if (validateCapitalSizingPolicy(spec.capitalSizing).length > 0)
+        return { action, rejection: "capital_policy_invalid" };
+    const policy = spec.capitalSizing;
+    const adjustment = {
+        version: policy.version,
+        basis: "owned_collateral_spot_marked_negative_position_marks_only",
+    };
+    const reject = (rejection) => ({ action, adjustment, rejection });
+    const book = observation.capitalBook;
+    if (!book || book.status !== "ready")
+        return reject(book?.reason ?? "capital_book_unavailable");
+    const equity = book.conservativeEquityMusd;
+    if (!positive(equity) ||
+        !nonnegative(budget.cashAvailableMusd) ||
+        !nonnegative(budget.committedCapitalMusd) ||
+        !nonnegative(budget.openMarginMusd))
+        return reject("capital_budget_unavailable");
+    adjustment.conservativeEquityMusd = equity;
+    const ticket = Math.min(spec.risk.perTradeMarginMusd, (equity * policy.perTicketCapitalPct) / 100);
+    const room = Math.min(ticket, (equity * policy.totalCapitalPct) / 100 - budget.committedCapitalMusd, budget.cashAvailableMusd - (equity * policy.cashReservePct) / 100);
+    if (!positive(room))
+        return reject("capital_allocation_or_reserve_exhausted");
+    if (action.type === "spot_order")
+        return { action, adjustment }; // retain quantity; quote gate owns its cost
+    if (action.type === "pm_open") {
+        const stake = centsDown(Math.min(room, (equity * policy.pmMaxLossPct) / 100));
+        adjustment.proposedAmountMusd = action.stakeMusd;
+        adjustment.sizedAmountMusd = stake;
+        adjustment.riskBudgetMusd = (equity * policy.pmMaxLossPct) / 100;
+        if (stake < 10)
+            return reject("capital_ticket_below_minimum");
+        return { action: { ...action, stakeMusd: stake }, adjustment };
+    }
+    if (action.type !== "futures_open")
+        return { action };
+    const mark = observation.watch.find((w) => w.symbol.toUpperCase() === action.symbol.toUpperCase())?.priceUsd;
+    const stop = action.stopLossPrice;
+    if (!positive(mark) ||
+        !positive(stop) ||
+        !positive(action.leverage) ||
+        (action.side === "long" ? stop >= mark : stop <= mark))
+        return reject("capital_stop_or_mark_unavailable");
+    const distance = Math.abs(mark - stop) / mark;
+    const fee = CAPITAL_FEE_BUFFER_BPS / 10_000;
+    const riskPerMargin = action.leverage * (distance + fee * (1 + stop / mark));
+    const riskBudget = (equity * policy.futuresRiskPct) / 100;
+    const margin = centsDown(Math.min(ticket, riskBudget / riskPerMargin, spec.limits.maxOpenMarginMusd - budget.openMarginMusd, room / (1 + action.leverage * fee)));
+    Object.assign(adjustment, {
+        proposedAmountMusd: action.marginMusd,
+        sizedAmountMusd: margin,
+        riskBudgetMusd: riskBudget,
+        feeBufferBps: CAPITAL_FEE_BUFFER_BPS,
+    });
+    if (margin < 10)
+        return reject("capital_ticket_below_minimum");
+    return { action: { ...action, marginMusd: margin }, adjustment };
+}
+/** Quote-bound monetary checks. Drift fails closed; never requote a resized
+ * ticket, silently widen a cap, or credit uncertain close/sell proceeds. */
+export function validateCapitalAction(action, spec, observation, budget, quote) {
+    if (!usesCapitalSizing(spec) || !increases(action))
+        return undefined;
+    if (validateCapitalSizingPolicy(spec.capitalSizing).length > 0)
+        return "capital_policy_invalid";
+    if (observation.capitalBook?.status !== "ready")
+        return "capital_book_unavailable";
+    const p = spec.capitalSizing, equity = observation.capitalBook.conservativeEquityMusd;
+    if (!positive(equity) ||
+        !nonnegative(budget.cashAvailableMusd) ||
+        !nonnegative(budget.committedCapitalMusd) ||
+        !nonnegative(budget.openMarginMusd))
+        return "capital_budget_unavailable";
+    let cost, allocated;
+    if (action.type === "pm_open") {
+        cost = allocated = action.stakeMusd;
+        if (cost > (equity * p.pmMaxLossPct) / 100 + 1e-8)
+            return "capital_pm_max_loss_exceeded";
+    }
+    else if (action.type === "spot_order") {
+        cost = allocated = capitalSpotBuyCost(action, quote);
+        // Without a stop model, the entire spot buy is the capital at risk.
+        if (positive(cost) && cost > (equity * p.futuresRiskPct) / 100 + 1e-8)
+            return "capital_spot_risk_exceeded";
+    }
+    else if (action.type === "futures_open") {
+        const entry = quote?.entryPrice, stop = action.stopLossPrice, target = action.takeProfitPrice;
+        const bps = quote?.futuresFeeBps, entryFee = quote?.estimatedEntryFeeMusd;
+        cost = quote?.cashRequiredMusd;
+        allocated = action.marginMusd;
+        if (!positive(entry) ||
+            !positive(stop) ||
+            !positive(target) ||
+            !nonnegative(bps) ||
+            !nonnegative(entryFee) ||
+            !positive(cost))
+            return "capital_quote_cost_evidence_missing";
+        const notional = action.marginMusd * action.leverage;
+        const feeRate = bps / 10_000;
+        if (Math.abs(entryFee - notional * feeRate) > CENT_TOLERANCE ||
+            Math.abs(cost - action.marginMusd - entryFee) > CENT_TOLERANCE)
+            return "capital_quote_cost_mismatch";
+        const adverse = action.side === "long" ? entry - stop : stop - entry;
+        const favorable = action.side === "long" ? target - entry : entry - target;
+        if (!(adverse > 0) || !(favorable > 0))
+            return "capital_stop_target_wrong_side";
+        const risk = (notional * adverse) / entry +
+            entryFee +
+            ((notional * stop) / entry) * feeRate;
+        const reward = (notional * favorable) / entry -
+            entryFee -
+            ((notional * target) / entry) * feeRate;
+        if (risk > (equity * p.futuresRiskPct) / 100 + 1e-8)
+            return "capital_quote_stop_risk_exceeded";
+        if (reward / risk + 1e-8 < p.minRewardRisk)
+            return "capital_quote_reward_risk_too_low";
+    }
+    if (!positive(cost) || !positive(allocated))
+        return "capital_quote_cost_evidence_missing";
+    if (cost >
+        Math.min(spec.risk.perTradeMarginMusd, (equity * p.perTicketCapitalPct) / 100) +
+            1e-8)
+        return "capital_ticket_cap_exceeded";
+    if (budget.committedCapitalMusd + cost >
+        (equity * p.totalCapitalPct) / 100 + 1e-8)
+        return "capital_combined_allocation_exceeded";
+    if (budget.cashAvailableMusd - cost <
+        (equity * p.cashReservePct) / 100 - 1e-8)
+        return "capital_cash_reserve_exceeded";
+    return 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 function capitalSpotBuyCost(action, quote) {
+    const gross = spotBuyCost(action, quote);
+    const quotedGross = quote?.estimatedCostMusd;
+    const fee = quote?.estimatedFeeMusd;
+    if (!positive(gross) || !positive(quotedGross) || !nonnegative(fee))
+        return undefined;
+    const cost = gross + fee * Math.max(1, gross / quotedGross);
+    return positive(cost) ? cost : undefined;
+}
+export function capitalCashCost(action, quote) {
+    if (action.type === "futures_open")
+        return quote?.cashRequiredMusd ?? action.marginMusd;
+    if (action.type === "pm_open")
+        return action.stakeMusd;
+    if (action.type === "spot_order" && action.side === "buy")
+        return capitalSpotBuyCost(action, quote) ?? Number.NaN;
+    return 0;
+}

package/dist/agent/client.d.ts

@@ -21,6 +21,7 @@ export interface ClientConfig {
     fetchFn?: typeof fetch;
     sleepFn?: (ms: number) => Promise<void>;
     maxRetries?: number;
+    extraHeaders?: Record<string, string>;
 }
 export declare class CoinRithmClient {
     private readonly apiKey;
@@ -28,6 +29,7 @@ export declare class CoinRithmClient {
     private readonly fetchFn;
     private readonly sleepFn;
     private readonly maxRetries;
+    private readonly extraHeaders?;
     rateLimitHits: number;
     constructor(cfg: ClientConfig);
     private request;

package/dist/agent/client.js

@@ -30,6 +30,7 @@ export class CoinRithmClient {
     fetchFn;
     sleepFn;
     maxRetries;
+    extraHeaders;
     // Every 429 seen this session (read or write, retried or not) — feeds the
     // rate-limit-pressure kill-switch, which a write-only counter would miss.
     rateLimitHits = 0;
@@ -39,6 +40,7 @@ export class CoinRithmClient {
         this.fetchFn = cfg.fetchFn ?? fetch;
         this.sleepFn = cfg.sleepFn ?? realSleep;
         this.maxRetries = cfg.maxRetries ?? 3;
+        this.extraHeaders = cfg.extraHeaders;
     }
     async request(method, path, opts = {}) {
         const url = new URL(this.baseUrl + path);
@@ -48,7 +50,9 @@ export class CoinRithmClient {
                     url.searchParams.set(k, String(v));
             }
         }
+        // extraHeaders first: auth, accept and trace can never be clobbered by it.
         const headers = {
+            ...this.extraHeaders,
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
             ...traceHeaders(opts.trace),