@coinrithm/mcp-trading 0.3.0 → 0.5.0

package/dist/agent/setups.js

@@ -0,0 +1,133 @@
+// Deterministic setup scan — the first slice of the preflight gate.
+//
+// The problem it solves: cautious free-tier brains were skipping 100% of cycles
+// with "no clear setup" even while the tape moved 3-4%. The fix (drawn straight
+// from content-engine's gate design): do NOT make the model decide whether a setup
+// exists. Compute it deterministically from the indicators we already have, then
+// hand the flagged setups to the model so it decides HOW to act, not WHETHER
+// anything is happening. This flips the default from "no setup -> skip" to "here
+// is the structure -> trade it (in your style) or give a real reason not to".
+//
+// Pure + stateless: no I/O, no model. Strategy-neutral — it reports the structure
+// and the trend-following bias; a contrarian agent fades the same facts.
+// Thresholds tuned to FIRE readily on a normal moving market (the failure mode we
+// are fixing is under-firing). A genuinely flat tape still yields an empty list,
+// which is the correct "nothing to do" signal.
+const STRONG_MOVE_PCT = 2.0; // |24h %| that counts as a real directional push
+const LEAN_MOVE_PCT = 0.8; // smaller move that still confirms an EMA-stack trend
+const RSI_OVERSOLD = 35;
+const RSI_OVERBOUGHT = 68;
+const MIN_STRENGTH = 0.5; // below this we do not flag (avoid noise)
+function pct(n) {
+    return `${n >= 0 ? "+" : ""}${n.toFixed(1)}%`;
+}
+// Normalize a symbol to its base asset so a watch "BTC" matches an open position
+// "BTC-PERP" / "BTCUSDT" when checking whether we already hold it.
+export function baseSymbol(s) {
+    return (s ?? "")
+        .toUpperCase()
+        .replace(/[-/]?(PERP|USDT|USDC|USD)$/i, "")
+        .replace(/[^A-Z0-9]/g, "");
+}
+// Classify ONE coin into its setups. Usually one (the trend/breakout read), but a
+// TRENDING coin that is also RSI-extreme emits a SECOND, counter-trend "fade"
+// signal — the same structure is a momentum trade to a trend-follower and a
+// mean-reversion trade to a contrarian, so we surface both and let each agent pick
+// the one matching its style (fixes contrarians skipping "no setup fits me").
+function classify(w, openPositions) {
+    const ind = w.indicators;
+    if (!ind)
+        return [];
+    const ch = w.change24h ?? 0;
+    const rsi = ind.rsi14;
+    const up = ind.ema20AboveEma50 === true && ind.aboveEma20 === true;
+    const down = ind.ema20AboveEma50 === false && ind.aboveEma20 === false;
+    const oversold = rsi != null && rsi <= RSI_OVERSOLD;
+    const overbought = rsi != null && rsi >= RSI_OVERBOUGHT;
+    // Compact, factual note the model reads (no interpretation — just the structure).
+    const facts = [`${pct(ch)} 24h`];
+    if (up)
+        facts.push("price>EMA20>EMA50 (uptrend)");
+    else if (down)
+        facts.push("price<EMA20<EMA50 (downtrend)");
+    if (rsi != null)
+        facts.push(`RSI ${Math.round(rsi)}${oversold ? " oversold" : overbought ? " overbought" : ""}`);
+    if (ind.brokeRecentHigh === true)
+        facts.push("broke 20-bar high");
+    if (ind.brokeRecentLow === true)
+        facts.push("broke 20-bar low");
+    if (ind.atr14 != null && ind.asOfClose)
+        facts.push(`ATR ${((100 * ind.atr14) / ind.asOfClose).toFixed(1)}% (stop ~1.5xATR)`);
+    const note = facts.join(" · ");
+    const out = [];
+    // Primary trend-following / breakout read.
+    if (ind.brokeRecentHigh === true) {
+        out.push({ symbol: w.symbol, kind: "breakout", bias: "long", strength: 0.8, note });
+    }
+    else if (ind.brokeRecentLow === true) {
+        out.push({ symbol: w.symbol, kind: "breakdown", bias: "short", strength: 0.8, note });
+    }
+    else if (up && ch >= LEAN_MOVE_PCT) {
+        out.push({ symbol: w.symbol, kind: "uptrend", bias: "long", strength: ch >= STRONG_MOVE_PCT ? 0.75 : 0.6, note });
+    }
+    else if (down && ch <= -LEAN_MOVE_PCT) {
+        out.push({ symbol: w.symbol, kind: "downtrend", bias: "short", strength: ch <= -STRONG_MOVE_PCT ? 0.75 : 0.6, note });
+    }
+    else if (overbought) {
+        out.push({ symbol: w.symbol, kind: "stretched", bias: "fade-short", strength: 0.55, note });
+    }
+    else if (oversold) {
+        out.push({ symbol: w.symbol, kind: "stretched", bias: "fade-long", strength: 0.55, note });
+    }
+    else if (Math.abs(ch) >= STRONG_MOVE_PCT) {
+        // A strong move with no clean EMA stack — still tradeable momentum.
+        out.push({ symbol: w.symbol, kind: ch > 0 ? "uptrend" : "downtrend", bias: ch > 0 ? "long" : "short", strength: 0.55, note });
+    }
+    // Secondary COUNTER-TREND fade: a standing trend that is ALSO RSI-extreme is a
+    // mean-reversion candidate. Only add it when the primary was the trend itself
+    // (so we don't double-list a pure stretched read).
+    const primaryIsTrend = out[0] && (out[0].kind === "uptrend" || out[0].kind === "downtrend" || out[0].kind === "breakout" || out[0].kind === "breakdown");
+    if (primaryIsTrend && (oversold || overbought)) {
+        out.push({
+            symbol: w.symbol,
+            kind: "stretched",
+            bias: oversold ? "fade-long" : "fade-short",
+            strength: 0.6,
+            note: `${note} — counter-trend fade (mean-reversion: ${oversold ? "oversold within downtrend" : "overbought within uptrend"})`,
+        });
+    }
+    // Position awareness: if we already hold this symbol, tag every signal with the
+    // side held AND the position's win/loss state right in the note — so the model
+    // ADDS to a winner (only with free margin), trails, or cuts a loser, instead of
+    // pointlessly re-opening the same size into the margin cap (the open_margin_
+    // exceeds_cap churn). A winner with room is the one case a same-side "open" is OK
+    // (scaling in); otherwise it's manage-only.
+    const wb = baseSymbol(w.symbol);
+    const pos = wb ? openPositions.find((p) => baseSymbol(p.symbol) === wb) : undefined;
+    const held = pos && (pos.side === "long" || pos.side === "short") ? pos.side : undefined;
+    if (held) {
+        const u = pos?.unrealizedPnlMusd;
+        const tag = u == null
+            ? ` [HELD ${held} — manage, do NOT re-open]`
+            : u >= 0
+                ? ` [HELD ${held}, +${Math.round(u)}mUSD WINNER — ADD only if you have free margin (scale into strength), else trail the stop; never re-open the same size]`
+                : ` [HELD ${held}, ${Math.round(u)}mUSD loser — trail or cut; do NOT average down or re-open]`;
+        for (const s of out) {
+            s.held = held;
+            s.note = s.note + tag;
+        }
+    }
+    return out;
+}
+// Scan the whole watchlist, return the flagged setups strongest-first. An empty
+// list = a flat tape = a legitimate reason to skip new entries this cycle. Setups
+// on a symbol we already hold are tagged `held` (manage, don't re-open).
+export function scanSetups(watch, openPositions = []) {
+    const out = [];
+    for (const w of watch) {
+        for (const s of classify(w, openPositions))
+            if (s.strength >= MIN_STRENGTH)
+                out.push(s);
+    }
+    return out.sort((a, b) => b.strength - a.strength);
+}

package/dist/agent/skill.d.ts

@@ -1,4 +1,5 @@
 import { AgentSpec, ParsedSkill, ResolvedAgent, ResolveIssue } from "./types.js";
+export declare const UNLIMITED_TRADES_PER_DAY = 1000000;
 export declare function buildSpec(raw: Record<string, unknown>): AgentSpec;
 export declare function parseSkill(text: string): ParsedSkill;
 export declare function loadSkill(path: string): ParsedSkill;

package/dist/agent/skill.js

@@ -1,14 +1,20 @@
 import { readFileSync } from "node:fs";
 import { parseFrontmatter } from "./frontmatter.js";
-import { VENUES, PROVIDERS, ALLOWED_CAPABILITIES, } from "./types.js";
+import { VENUES, PROVIDERS, ALLOWED_CAPABILITIES, DEFAULT_TRIGGER_POLICY, } from "./types.js";
 import { resolveAgent, ResolveError } from "./resolve.js";
 import { strictLint } from "./strictLint.js";
 import { checkCapabilityDrift } from "./capabilityGuard.js";
 // Safe defaults for the OPTIONAL policy blocks. A minimal self-host skill
 // (name/description/spec/trigger/model/venues/risk) runs under these. Hosted
 // mode requires them to be explicit (see skillValidator).
+// A daily TRADE-COUNT cap of 0 (or absent) means UNLIMITED. We don't throttle how often
+// an agent trades — the risk caps (daily loss, open margin, leverage, stops) are the real
+// guardrails. "Unlimited" is normalised to a large finite value so cap-merge arithmetic
+// (most-restrictive-wins) and JSON serialisation stay simple.
+export const UNLIMITED_TRADES_PER_DAY = 1_000_000;
+const normalizeTradeCap = (v) => (v <= 0 ? UNLIMITED_TRADES_PER_DAY : v);
 const DEFAULT_LIMITS = {
-    maxTradesPerDay: 20,
+    maxTradesPerDay: UNLIMITED_TRADES_PER_DAY,
     maxWritesPerCycle: 2,
     maxDailyLossMusd: 5_000,
     maxOpenMarginMusd: 5_000,
@@ -67,6 +73,7 @@ export function buildSpec(raw) {
     const abst = obj(raw.abstention);
     const sync = obj(raw.sync);
     const ks = obj(raw.killSwitch);
+    const trig = obj(raw.triggerPolicy);
     const venues = strArr(raw.venues).filter((v) => VENUES.includes(v));
     return {
         name: typeof raw.name === "string" ? raw.name : "",
@@ -87,7 +94,7 @@ export function buildSpec(raw) {
             blocklist: strArr(risk.blocklist),
         },
         limits: {
-            maxTradesPerDay: num(limits.maxTradesPerDay, DEFAULT_LIMITS.maxTradesPerDay),
+            maxTradesPerDay: normalizeTradeCap(num(limits.maxTradesPerDay, DEFAULT_LIMITS.maxTradesPerDay)),
             maxWritesPerCycle: num(limits.maxWritesPerCycle, DEFAULT_LIMITS.maxWritesPerCycle),
             maxDailyLossMusd: num(limits.maxDailyLossMusd, DEFAULT_LIMITS.maxDailyLossMusd),
             maxOpenMarginMusd: num(limits.maxOpenMarginMusd, DEFAULT_LIMITS.maxOpenMarginMusd),
@@ -110,6 +117,17 @@ export function buildSpec(raw) {
         },
         objective: buildObjective(raw.objective),
         capabilities: strArr(raw.capabilities).filter((c) => ALLOWED_CAPABILITIES.includes(c)),
+        // OKF v2 (load-bearing): the gate reads this; omitted -> DEFAULT_TRIGGER_POLICY.
+        // This is the agent's INTENT — the platform deployment overlay may tighten it
+        // server-side, and it can never widen a hard cap (caps live in the runner).
+        triggerPolicy: {
+            mode: trig.mode === "always" ? "always" : DEFAULT_TRIGGER_POLICY.mode,
+            skipLlmWhenNoTrigger: bool(trig.skipLlmWhenNoTrigger, DEFAULT_TRIGGER_POLICY.skipLlmWhenNoTrigger),
+            alwaysManageOpenPositions: bool(trig.alwaysManageOpenPositions, DEFAULT_TRIGGER_POLICY.alwaysManageOpenPositions),
+            maxLlmCallsPerHour: num(trig.maxLlmCallsPerHour, DEFAULT_TRIGGER_POLICY.maxLlmCallsPerHour),
+            debounceMinutes: num(trig.debounceMinutes, DEFAULT_TRIGGER_POLICY.debounceMinutes),
+            pmEvalCooldownMinutes: num(trig.pmEvalCooldownMinutes, DEFAULT_TRIGGER_POLICY.pmEvalCooldownMinutes),
+        },
     };
 }
 export function parseSkill(text) {

package/dist/agent/skillValidator.js

@@ -2,6 +2,8 @@ import { fail, VENUES, PROVIDERS, SPEC_VERSION, OBJECTIVE_PRIMARIES, ALLOWED_CAP
 import { parseCadenceMs, scanForSecrets } from "./util.js";
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const isPosNum = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+// maxTradesPerDay accepts 0 as the explicit "unlimited daily trades" sentinel.
+const isNonNegNum = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
 export function validateSkill(parsed, mode = "self-host") {
     const raw = parsed.raw;
     const issues = [];
@@ -99,8 +101,8 @@ export function validateSkill(parsed, mode = "self-host") {
         }
         else {
             const l = raw.limits;
-            if (!isPosNum(l.maxTradesPerDay))
-                add("skill_limits_trades", "limits.maxTradesPerDay must be a positive number");
+            if (!isNonNegNum(l.maxTradesPerDay))
+                add("skill_limits_trades", "limits.maxTradesPerDay must be a number >= 0 (0 = unlimited daily trades)");
             if (!isPosNum(l.maxWritesPerCycle))
                 add("skill_limits_writes", "limits.maxWritesPerCycle must be a positive number");
             if (!isPosNum(l.maxDailyLossMusd))

package/dist/agent/state.js

@@ -77,11 +77,19 @@ export function accrueRealized(state, closedTrades) {
     if (state.realizedPnlMusd > state.peakRealizedMusd)
         state.peakRealizedMusd = state.realizedPnlMusd;
 }
+// A transient model-failure streak (free models occasionally time out/hang) must
+// never disable an agent on a hair-trigger, so the model-failure kill-switch is
+// floored at this many consecutive failures regardless of an agent's own (lower)
+// setting. The scheduler additionally auto-revives any model-failure disable.
+const MODEL_FAILURE_FLOOR = 10;
 // Returns a disable reason if any kill-switch condition is tripped, else null.
 export function checkKillSwitch(spec, state) {
     const ks = spec.killSwitch;
-    if (ks.maxConsecutiveModelFailures > 0 && state.consecutiveModelFailures >= ks.maxConsecutiveModelFailures) {
-        return `consecutive model failures ${state.consecutiveModelFailures} >= ${ks.maxConsecutiveModelFailures}`;
+    if (ks.maxConsecutiveModelFailures > 0) {
+        const threshold = Math.max(ks.maxConsecutiveModelFailures, MODEL_FAILURE_FLOOR);
+        if (state.consecutiveModelFailures >= threshold) {
+            return `consecutive model failures ${state.consecutiveModelFailures} >= ${threshold}`;
+        }
     }
     if (ks.maxConsecutiveRejects > 0 && state.consecutiveRejectCycles >= ks.maxConsecutiveRejects) {
         return `consecutive reject cycles ${state.consecutiveRejectCycles} >= ${ks.maxConsecutiveRejects}`;

package/dist/agent/templates.js

@@ -62,8 +62,10 @@ money. Edit this prose freely (any language) — it is your agent's borders.
    balances or what is already open.
 2. Scan the watchlist. A candidate is a coin whose short and medium momentum
    agree (both up, or both down) and is not already an open position.
-3. Pick at most one strongest candidate. If nothing is clean, skip — a skipped
-   cycle is cheaper than a forced trade.
+3. Pick the strongest candidate and commit when the read is clear — even a
+   moderate-confidence one — sized small with a stop. Skip only when the signals
+   contradict or the data is stale; a quiet tape where your edge is still real
+   is an act, not a skip.
 4. Quote before you open. Read the liquidation price and confirm it is sane. If
    the quote is not eligible, relay the reason and stop.
 5. Open small and protected: enter in the trend direction and set a stop-loss at
@@ -75,8 +77,10 @@ The hard caps (leverage, margin, watchlist) live in the config blocks above and
 are enforced by the runner — change them there, not in this prose.`;
 const PERSONA_STUB = `# Persona
 
-Patient and selective. Prefers to skip rather than force a marginal trade.
-States its reasoning plainly and never frames paper results as real-money advice.
+Decisive and in character. Acts on a clear read — even a moderate-confidence one
+— sized small and protected with a stop, and skips only when the read is
+contradictory or the data is stale. States its reasoning plainly in its own
+voice, and never frames paper results as real-money advice.
 `;
 export function buildAgentObject(name, preset) {
     const p = PRESETS[preset];

package/dist/agent/types.d.ts

@@ -4,7 +4,7 @@ export type Venue = "spot" | "futures" | "pm";
 export declare const VENUES: readonly Venue[];
 export declare const ACTION_TYPES: readonly ["futures_open", "futures_close", "futures_set_sltp", "spot_order", "spot_cancel", "pm_open"];
 export type ActionType = (typeof ACTION_TYPES)[number];
-export type ProviderName = "anthropic" | "openai" | "groq" | "nvidia" | "openai-compatible";
+export type ProviderName = "anthropic" | "openai" | "groq" | "nvidia" | "gemini" | "openai-compatible";
 export declare const PROVIDERS: readonly ProviderName[];
 export interface ModelConfig {
     provider: ProviderName;
@@ -15,6 +15,15 @@ export interface TriggerConfig {
     cadence: string;
     timezone?: string;
 }
+export interface TriggerPolicy {
+    mode: "event_driven" | "always";
+    skipLlmWhenNoTrigger: boolean;
+    alwaysManageOpenPositions: boolean;
+    maxLlmCallsPerHour: number;
+    debounceMinutes: number;
+    pmEvalCooldownMinutes: number;
+}
+export declare const DEFAULT_TRIGGER_POLICY: TriggerPolicy;
 export interface RiskConfig {
     maxLeverage: number;
     perTradeMarginMusd: number;
@@ -52,7 +61,7 @@ export interface ObjectiveConfig {
     secondary: string[];
     horizon?: string;
 }
-export declare const ALLOWED_CAPABILITIES: readonly ["websearch", "indicators"];
+export declare const ALLOWED_CAPABILITIES: readonly ["websearch", "indicators", "news"];
 export type Capability = (typeof ALLOWED_CAPABILITIES)[number];
 export interface AgentSpec {
     name: string;
@@ -68,6 +77,7 @@ export interface AgentSpec {
     killSwitch: KillSwitchConfig;
     objective?: ObjectiveConfig;
     capabilities: Capability[];
+    triggerPolicy?: TriggerPolicy;
 }
 export interface ParsedSkill {
     spec: AgentSpec;
@@ -93,6 +103,7 @@ export interface WatchEntry {
     change1h?: number;
     change24h?: number;
     change7d?: number;
+    sentimentBullishPct?: number;
     freshness?: Freshness;
     indicators?: IndicatorSet;
 }
@@ -103,8 +114,14 @@ export interface OpenPosition {
     symbol?: string;
     side?: string;
     status?: string;
+    leverage?: number;
     marginMusd?: number;
     unrealizedPnlMusd?: number;
+    entryPrice?: number;
+    markPrice?: number;
+    liquidationPrice?: number;
+    stopLossPrice?: number;
+    takeProfitPrice?: number;
 }
 export interface SpotOrder {
     id: number;
@@ -121,15 +138,44 @@ export interface PmPosition {
     slug?: string;
     outcomeExternalMarketId?: string;
     stakeMusd?: number;
+    unrealizedPnlMusd?: number;
+    status?: string;
+}
+export interface PmResolution {
+    id: number;
+    eventTitle?: string;
+    slug?: string;
+    side?: string;
     status?: string;
+    pnlMusd?: number;
+    stakeMusd?: number;
 }
 export interface PmMarket {
+    ref?: string;
     source: string;
     slug: string;
     outcomeExternalMarketId: string;
+    outcomeName?: string;
+    probability?: number;
     title?: string;
     freshness?: Freshness;
 }
+export interface SetupSignal {
+    symbol: string;
+    kind: "breakout" | "breakdown" | "uptrend" | "downtrend" | "stretched";
+    bias: "long" | "short" | "fade-long" | "fade-short";
+    strength: number;
+    note: string;
+    held?: "long" | "short";
+}
+export interface NewsItem {
+    title: string;
+    source?: string;
+    sentiment?: string;
+    importance?: number;
+    ageHours?: number;
+    coins?: string[];
+}
 export interface Observation {
     asOf: string;
     scopes: string[];
@@ -138,11 +184,18 @@ export interface Observation {
     openPositions: OpenPosition[];
     openOrders: SpotOrder[];
     pmPositions: PmPosition[];
+    pmResolutions: PmResolution[];
     pmMarkets: PmMarket[];
     watch: WatchEntry[];
+    setups: SetupSignal[];
+    marketMood?: {
+        fearGreed: number;
+        label: string;
+    };
     syncCursor: string | null;
     newClosedTrades: Array<Record<string, unknown>>;
     polledBeforeWrite: boolean;
+    news?: NewsItem[];
 }
 export type ProposedAction = {
     type: "futures_open";
@@ -180,6 +233,7 @@ export type ProposedAction = {
     orderId: number;
 } | {
     type: "pm_open";
+    ref?: string;
     source: string;
     slug: string;
     outcomeExternalMarketId: string;
@@ -199,6 +253,7 @@ export declare function spotBuyCost(action: Extract<ProposedAction, {
 export interface Decision {
     decision: "skip" | "act";
     reason?: string;
+    rationale?: string;
     confidence?: number;
     actions: ProposedAction[];
 }
@@ -228,6 +283,13 @@ export interface RunState {
     realizedPnlTodayMusd: number;
     consecutiveExecFailures: number;
     intentSeq: Record<string, number>;
+    llmCallTimestamps?: number[];
+    lastLlmCallAt?: number;
+    lastTriggerFingerprint?: string;
+    journal?: Array<{
+        at: string;
+        did: string;
+    }>;
 }
 export interface AgentTrace {
     runId?: string;
@@ -256,11 +318,22 @@ export interface PlannedAction {
 export interface CycleResult {
     decision: "skip" | "act";
     skipReason?: string;
+    rationale?: string;
+    confidence?: number;
+    rawModelOutput?: string;
     planned: PlannedAction[];
     modelFailed?: boolean;
     disabled?: boolean;
     disabledReason?: string;
     live: boolean;
+    triggerCodes?: string[];
+    llmCallMade?: boolean;
+    tokensIn?: number;
+    tokensOut?: number;
+    estimatedCostUsd?: number;
+    decisionType?: "act" | "skip" | "gate_skip" | "model_error";
+    writeAttempted?: number;
+    writeAccepted?: number;
 }
 export interface ResolveIssue {
     code: string;

package/dist/agent/types.js

@@ -25,8 +25,17 @@ export const PROVIDERS = [
     "openai",
     "groq",
     "nvidia",
+    "gemini",
     "openai-compatible",
 ];
+export const DEFAULT_TRIGGER_POLICY = {
+    mode: "event_driven",
+    skipLlmWhenNoTrigger: true,
+    alwaysManageOpenPositions: true,
+    maxLlmCallsPerHour: 0,
+    debounceMinutes: 0,
+    pmEvalCooldownMinutes: 10,
+};
 // What the agent declares it is optimizing for — so two similar-looking agents
 // are distinguishable and the scorecard/Arena can read intent.
 export const OBJECTIVE_PRIMARIES = [
@@ -40,7 +49,11 @@ export const OBJECTIVE_PRIMARIES = [
 // slice. `websearch` = external lookups (an injection surface + a cost — it can
 // inform reasoning but NEVER widen a cap, since caps live in the runner);
 // `indicators` = runner-computed RSI/MACD/etc. fed into the observation.
-export const ALLOWED_CAPABILITIES = ["websearch", "indicators"];
+export const ALLOWED_CAPABILITIES = [
+    "websearch",
+    "indicators",
+    "news",
+];
 export const ok = () => ({ valid: true });
 export const fail = (code, reason) => ({
     valid: false,

package/dist/agent/version.d.ts

@@ -5,7 +5,7 @@ export declare const COINRITHM_API: {
     readonly kind: "coinrithm-agent-api";
     readonly baseUrl: "https://api.coinrithm.com";
     readonly mcpUrl: "https://mcp.coinrithm.com/mcp";
-    readonly openapiVersion: "1.4.0";
+    readonly openapiVersion: "1.5.0";
     readonly mcpPackage: "@coinrithm/mcp-trading";
-    readonly mcpVersion: "0.3.0";
+    readonly mcpVersion: string;
 };

package/dist/agent/version.js

@@ -1,8 +1,16 @@
 // Versions stamped into manifest.lock.json so a resolved agent is reproducible
 // only against the exact compile that produced it.
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 export const RUNNER_VERSION = "0.1.0";
 export const RESOLVER_VERSION = "1";
 export const MANIFEST_SCHEMA = "coinrithm.manifest.v1";
+// The published package version, read from package.json at runtime (same
+// createRequire pattern as src/version.ts) so the API pin's mcpVersion can never
+// drift from the real published version again. package.json lives outside
+// rootDir=src; at runtime dist/agent/version.js resolves ../../package.json to
+// the package root in both the repo and the published tarball.
+const PACKAGE_VERSION = require("../../package.json").version;
 // The CoinRithm execution surface a generated agent talks to. Written into
 // functionality/coinrithm.yaml as a version PIN; the CLI warns when an agent's
 // pin lags this, but never blocks self-host use.
@@ -10,7 +18,9 @@ export const COINRITHM_API = {
     kind: "coinrithm-agent-api",
     baseUrl: "https://api.coinrithm.com",
     mcpUrl: "https://mcp.coinrithm.com/mcp",
-    openapiVersion: "1.4.0",
+    // The API CONTRACT version (openapi.yaml info.version). Versioned independently
+    // from the npm package below — hand-bump this when the OpenAPI contract changes.
+    openapiVersion: "1.5.0",
     mcpPackage: "@coinrithm/mcp-trading",
-    mcpVersion: "0.3.0",
+    mcpVersion: PACKAGE_VERSION,
 };

package/dist/client.d.ts

@@ -111,6 +111,7 @@ export declare class CoinRithmClient {
         source: string;
         slug: string;
         outcomeExternalMarketId: string;
+        side?: "yes" | "no";
         stakeMusd: number;
     } & {
         agentTrace?: AgentTrace;
@@ -155,6 +156,7 @@ export declare class CoinRithmClient {
         source: string;
         slug: string;
         outcomeExternalMarketId: string;
+        side?: "yes" | "no";
         stakeMusd: number;
         idempotencyKey: string;
     }>, apiKey?: string): Promise<ApiResult>;

package/dist/tools.js

@@ -6,7 +6,13 @@
 // isError results rather than thrown so the model can react.
 import { z } from "zod";
 import { bearerFromHeader } from "./client.js";
-const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice.";
+const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice. " +
+    "Paper fills apply a disclosed execution cost folded into realized PnL: " +
+    "spot/futures pay a taker fee (spot market orders also pay half-spread + " +
+    "slippage); PM fills at the ask with size-based slippage and a Polymarket-" +
+    "shaped taker fee, with entryProbability kept at the mid for calibration. " +
+    "See the executionModel in quote/trade results — a rehearsal cost, not an " +
+    "exchange fill guarantee.";
 const API_RESULT_OUTPUT_SCHEMA = {
     httpStatus: z
         .number()
@@ -569,7 +575,9 @@ export function registerTools(server, client) {
             "estimate, max payout, eligibility, freshness, and decisionSupport " +
             "(market quality/liquidity/volume/spread tiers + flags) so you can " +
             "quote and gauge tradability in one call. Never mutates state. " +
-            "stakeMusd must be > 0 (min to open is 10). " +
+            "stakeMusd must be > 0 (min to open is 10). Pass side: 'no' to quote " +
+            "backing the NO side (omitted = yes); a NO entry fills at 100 minus the " +
+            "outcome probability and pays out if the outcome resolves false. " +
             PAPER_NOTE,
         inputSchema: {
             source: z.string().describe("Source slug (e.g. kalshi, polymarket)."),
@@ -577,12 +585,18 @@ export function registerTools(server, client) {
             outcomeExternalMarketId: z
                 .string()
                 .describe("Case-sensitive outcome / market id."),
+            side: z
+                .enum(["yes", "no"])
+                .optional()
+                .describe("Which side of the binary outcome to back. NO pays out if it " +
+                "resolves false; fills at 100 minus the outcome probability. " +
+                "Omitted = yes."),
             stakeMusd: z.number().positive().describe("mUSD to stake (> 0)."),
             agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Prediction-market quote"),
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, agentTrace }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, stakeMusd, agentTrace }, requestKey(extra))));
+    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, agentTrace }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, side, stakeMusd, agentTrace }, requestKey(extra))));
     server.registerTool("spot_quote", {
         title: "Spot quote",
         description: "Read-only spot MARKET quote: live execution price, estimated cost " +
@@ -800,7 +814,9 @@ export function registerTools(server, client) {
         description: "Open a mock prediction-market position (binary outcomes only). Requires " +
             "the trade:pm scope. Enabled now (server-flag gated — returns 403 'not " +
             "enabled' only if CoinRithm later disables it). idempotencyKey is " +
-            "REQUIRED. stakeMusd >= 10. Quote first and CONFIRM with the user. " +
+            "REQUIRED. stakeMusd >= 10. Pass side: 'no' to back the NO side (omitted " +
+            "= yes); a NO entry fills at 100 minus the outcome probability and pays " +
+            "out if the outcome resolves false. Quote first and CONFIRM with the user. " +
             PAPER_NOTE,
         inputSchema: {
             source: z
@@ -810,6 +826,12 @@ export function registerTools(server, client) {
             outcomeExternalMarketId: z
                 .string()
                 .describe("Case-sensitive outcome or market id returned by discovery."),
+            side: z
+                .enum(["yes", "no"])
+                .optional()
+                .describe("Which side of the binary outcome to back. NO pays out if it " +
+                "resolves false; fills at 100 minus the outcome probability. " +
+                "Omitted = yes."),
             stakeMusd: z.number().min(10).describe("mUSD stake (>= 10)."),
             idempotencyKey: z
                 .string()
@@ -821,10 +843,11 @@ export function registerTools(server, client) {
         annotations: mutatingAnnotations("Open prediction-market position", {
             idempotent: true,
         }),
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey, agentTrace, }, extra) => present(await client.openPmPosition({
+    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, idempotencyKey, agentTrace, }, extra) => present(await client.openPmPosition({
         source,
         slug,
         outcomeExternalMarketId,
+        side,
         stakeMusd,
         idempotencyKey,
         agentTrace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "CoinRithm paper-trading toolkit: an MCP server (coinrithm-mcp) AND a self-host agent runner (coinrithm-agent) for spot, futures, and prediction markets with a user-minted API key.",
   "type": "module",