@coinrithm/mcp-trading 0.7.14 → 0.7.15

package/dist/agent/client.d.ts

@@ -40,13 +40,26 @@ export declare class CoinRithmClient {
     rateLimitHits: number;
     constructor(cfg: ClientConfig);
     private request;
+    private publicRequest;
+    credentialFingerprint(): string;
     me(trace?: AgentTrace): Promise<ApiResult>;
+    performance(trace?: AgentTrace, options?: {
+        timeoutMs?: number;
+        maxRetries?: number;
+    }): Promise<ApiResult>;
     portfolio(trace?: AgentTrace): Promise<ApiResult>;
     wallet(query?: {
         coinId?: string;
     }, trace?: AgentTrace): Promise<ApiResult>;
     resolve(q: string, trace?: AgentTrace): Promise<ApiResult>;
     cryptoMovers(direction: "gainers" | "losers", limit: number, trace?: AgentTrace): Promise<ApiResult>;
+    getPublicPmWhales(options?: {
+        timeoutMs?: number;
+        limit?: number;
+    }): Promise<ApiResult>;
+    getPublicPmWhaleWallet(source: string, wallet: string, options?: {
+        timeoutMs?: number;
+    }): Promise<ApiResult>;
     market(coinId: string, trace?: AgentTrace): Promise<ApiResult>;
     candles(coinId: string, range: string, trace?: AgentTrace): Promise<ApiResult>;
     trades(query?: {

package/dist/agent/client.js

@@ -4,6 +4,7 @@
 // from an agent file). 429 backs off on Retry-After; 401/403/409/422 are
 // FAIL-CLOSED cycle outcomes (returned, not retried). fetch + sleep are
 // injectable so tests run with no network and no real waits.
+import { createHash } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
 import { retryAfterSeconds } from "../retryAfter.js";
 export const DEFAULT_BASE_URL = "https://api.coinrithm.com";
@@ -54,6 +55,16 @@ export class CoinRithmClient {
         this.extraHeaders = cfg.extraHeaders;
     }
     async request(method, path, opts = {}) {
+        const requestTimeoutMs = opts.timeoutMs !== undefined &&
+            Number.isSafeInteger(opts.timeoutMs) &&
+            opts.timeoutMs >= 1
+            ? Math.min(opts.timeoutMs, this.requestTimeoutMs)
+            : this.requestTimeoutMs;
+        const maxRetries = opts.maxRetries !== undefined &&
+            Number.isSafeInteger(opts.maxRetries) &&
+            opts.maxRetries >= 0
+            ? Math.min(opts.maxRetries, this.maxRetries)
+            : this.maxRetries;
         const url = new URL(this.baseUrl + path);
         if (opts.query) {
             for (const [k, v] of Object.entries(opts.query)) {
@@ -76,7 +87,7 @@ export class CoinRithmClient {
         const timer = setTimeout(() => {
             timedOut = true;
             controller.abort(new Error("API request deadline exceeded"));
-        }, this.requestTimeoutMs);
+        }, requestTimeoutMs);
         this.signal?.addEventListener("abort", cancel, { once: true });
         if (this.signal?.aborted)
             cancel();
@@ -102,12 +113,12 @@ export class CoinRithmClient {
                 const retryAfter = retryAfterSeconds(res.headers.get("retry-after"));
                 if (res.status === 429)
                     this.rateLimitHits += 1;
-                if (res.status === 429 && attempt < this.maxRetries) {
+                if (res.status === 429 && attempt < maxRetries) {
                     // Release this response before waiting so retries do not retain sockets.
                     void res.body?.cancel().catch(() => { });
                     const delayMs = (retryAfter ?? 5) * 1000;
                     // Never shorten a provider's Retry-After or overflow a Node timer.
-                    if (delayMs >= this.requestTimeoutMs)
+                    if (delayMs >= requestTimeoutMs)
                         await aborted;
                     else if (this.sleepFn)
                         await this.sleepFn(delayMs);
@@ -151,7 +162,7 @@ export class CoinRithmClient {
                             ? "request_aborted"
                             : "network_error",
                     message: timedOut
-                        ? `API request exceeded ${this.requestTimeoutMs}ms deadline`
+                        ? `API request exceeded ${requestTimeoutMs}ms deadline`
                         : controller.signal.aborted
                             ? "API request cancelled"
                             : err instanceof Error
@@ -166,10 +177,96 @@ export class CoinRithmClient {
             controller.signal.removeEventListener("abort", rejectAborted);
         }
     }
+    // Keyless, bounded reads against the public PM surface. These deliberately
+    // bypass the authenticated request path so a runner key cannot leak into a
+    // public context lookup. No retries are added here; the enrichment is
+    // optional and its deadline includes response-body consumption.
+    async publicRequest(path, query, timeoutMs = 5_000) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null && value !== "")
+                url.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        if (this.signal?.aborted) {
+            return { ok: false, status: 0, data: { error: "network_error" } };
+        }
+        const cancel = () => controller.abort();
+        this.signal?.addEventListener("abort", cancel, { once: true });
+        const deadlineMs = Math.min(timeoutMs, this.requestTimeoutMs);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, deadlineMs);
+        let rejectAborted;
+        const aborted = new Promise((_, reject) => {
+            rejectAborted = () => reject(new Error("public request aborted"));
+            controller.signal.addEventListener("abort", rejectAborted, {
+                once: true,
+            });
+        });
+        if (this.signal?.aborted)
+            cancel();
+        try {
+            const perform = async () => {
+                const res = await this.fetchFn(url.toString(), {
+                    method: "GET",
+                    headers: { Accept: "application/json" },
+                    signal: controller.signal,
+                });
+                const text = await res.text();
+                let data = text;
+                if (text) {
+                    try {
+                        data = JSON.parse(text);
+                    }
+                    catch {
+                        /* leave as text */
+                    }
+                }
+                return { ok: res.ok, status: res.status, data };
+            };
+            return await Promise.race([perform(), aborted]);
+        }
+        catch {
+            return {
+                ok: false,
+                status: 0,
+                data: {
+                    error: timedOut ? "timeout" : "network_error",
+                },
+            };
+        }
+        finally {
+            clearTimeout(timer);
+            controller.signal.removeEventListener("abort", rejectAborted);
+            this.signal?.removeEventListener("abort", cancel);
+        }
+    }
+    // A stable, non-reversible identity for this credential and API base, for
+    // per-agent in-memory caches that must outlive one client instance (the
+    // hosted scheduler builds a new client every cycle). Never the key itself.
+    credentialFingerprint() {
+        return createHash("sha256")
+            .update(`${this.baseUrl}\n${this.apiKey}`, "utf8")
+            .digest("hex")
+            .slice(0, 32);
+    }
     // ── reads ──────────────────────────────────────────────────────────────────
     me(trace) {
         return this.request("GET", "/api/agent/me", { trace });
     }
+    // GET /api/agent/performance: the calling key's own realized performance.
+    // Newer backends add an optional `pmCalibration` block (the key's settled PM
+    // forecast record), parsed defensively in observe.
+    performance(trace, options) {
+        return this.request("GET", "/api/agent/performance", {
+            trace,
+            timeoutMs: options?.timeoutMs,
+            maxRetries: options?.maxRetries,
+        });
+    }
     portfolio(trace) {
         return this.request("GET", "/api/agent/portfolio", { trace });
     }
@@ -186,6 +283,12 @@ export class CoinRithmClient {
             ? "/api/coins/top-losers"
             : "/api/coins/top-gainers", { query: { limit }, trace });
     }
+    getPublicPmWhales(options) {
+        return this.publicRequest("/api/prediction-markets/whales", { limit: options?.limit }, options?.timeoutMs);
+    }
+    getPublicPmWhaleWallet(source, wallet, options) {
+        return this.publicRequest(`/api/prediction-markets/whales/wallets/${encodeURIComponent(source)}/${encodeURIComponent(wallet)}`, undefined, options?.timeoutMs);
+    }
     market(coinId, trace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { trace });
     }

package/dist/agent/decisionReceipt.d.ts

@@ -8,7 +8,7 @@ interface Row {
 }
 export interface DecisionInputRecord {
     version: "coinrithm.decision-input.v1";
-    projectionVersion?: "coinrithm.decision-input-projection.v2";
+    projectionVersion?: "coinrithm.decision-input-projection.v2" | "coinrithm.decision-input-projection.v3";
     visibility: "private";
     completeness: "partial";
     phase: DecisionInputPhase;
@@ -21,6 +21,10 @@ export interface DecisionInputRecord {
     dailyRiskBudget: DailyRiskBudget | null;
     guardState: Record<string, number | boolean | null>;
     account: Record<string, number | boolean | string | null> | null;
+    marketMood?: {
+        fearGreed: number | null;
+        fetchedAt: string | null;
+    } | null;
     lists: Record<string, Row[]>;
     counts: Record<string, {
         source: number;

package/dist/agent/decisionReceipt.js

@@ -22,6 +22,20 @@ const fingerprint = (value) => typeof value === "string" && /^sha256:[a-f0-9]{64
     ? value
     : null;
 const numeric = (raw, keys) => Object.fromEntries(keys.map((key) => [key, num(raw[key])]));
+const count = (value) => Number.isSafeInteger(value) && value >= 0
+    ? value
+    : null;
+const fearGreed = (value) => {
+    const v = num(value);
+    return v !== null && v >= 0 && v <= 100 ? v : null;
+};
+const PROJECTION_V3 = "coinrithm.decision-input-projection.v3";
+// Watch-row fields that exist only from projection v3 on.
+const SENTIMENT_V3_KEYS = [
+    "sentimentTotalVotes",
+    "sentimentDayUtc",
+    "sentimentUpdatedAt",
+];
 const freshness = (value) => {
     const raw = obj(parseFreshness({ freshness: value }));
     return {
@@ -49,7 +63,7 @@ export function buildDecisionInputRecord(input) {
     const budget = buildDailyRiskBudget(input.spec, input.state);
     const record = {
         version: "coinrithm.decision-input.v1",
-        projectionVersion: "coinrithm.decision-input-projection.v2",
+        projectionVersion: PROJECTION_V3,
         visibility: "private",
         completeness: "partial",
         phase: input.phase,
@@ -115,6 +129,12 @@ export function buildDecisionInputRecord(input) {
         equityMusd: num(obs.equityMusd),
         polledBeforeWrite: bool(obs.polledBeforeWrite),
     };
+    record.marketMood = obs.marketMood
+        ? {
+            fearGreed: fearGreed(obs.marketMood.fearGreed),
+            fetchedAt: sourceTimestamp(obs.marketMood.fetchedAt) ?? null,
+        }
+        : null;
     const add = (name, items, project) => {
         const all = arr(items);
         // Bound work/space independently of the upstream list limit. Preserve order,
@@ -137,6 +157,10 @@ export function buildDecisionInputRecord(input) {
             "change7d",
             "sentimentBullishPct",
         ]),
+        // The sample and its own clocks; null = unknown, never "fresh".
+        sentimentTotalVotes: count(r.sentimentTotalVotes),
+        sentimentDayUtc: sourceTimestamp(r.sentimentDayUtc) ?? null,
+        sentimentUpdatedAt: sourceTimestamp(r.sentimentUpdatedAt) ?? null,
         freshness: freshness(r.freshness),
         ...(r.indicatorContext
             ? {
@@ -357,6 +381,7 @@ const LIST_KEYS = {
         "change24h",
         "change7d",
         "sentimentBullishPct",
+        ...SENTIMENT_V3_KEYS,
         "freshness",
         "indicators",
         "indicatorContext",
@@ -467,8 +492,16 @@ function validRow(value, keys) {
             return true;
         if (NESTED_KEYS[key])
             return validRow(v, NESTED_KEYS[key]);
-        if (key === "asOf" || key === "assessedAt" || key === "openedAt")
+        if ([
+            "asOf",
+            "assessedAt",
+            "openedAt",
+            "sentimentDayUtc",
+            "sentimentUpdatedAt",
+        ].includes(key))
             return sourceTimestamp(v) === v;
+        if (key === "sentimentTotalVotes")
+            return count(v) !== null;
         if (key === "basis")
             return code(v, FRESHNESS_BASES) !== null;
         if (key === "range")
@@ -565,13 +598,29 @@ export function sanitizeDecisionInputRecord(value) {
             "dailyRiskBudget",
             "guardState",
             "account",
+            "marketMood",
             "lists",
             "counts",
             "omissions",
         ]))
             return undefined;
         if (r.projectionVersion !== undefined &&
-            r.projectionVersion !== "coinrithm.decision-input-projection.v2")
+            r.projectionVersion !== "coinrithm.decision-input-projection.v2" &&
+            r.projectionVersion !== PROJECTION_V3)
+            return undefined;
+        // An older record must never carry, or be mistaken for, v3 fields.
+        const v3 = r.projectionVersion === PROJECTION_V3;
+        if (!v3 &&
+            (r.marketMood !== undefined ||
+                arr(obj(r.lists).watch).some((row) => SENTIMENT_V3_KEYS.some((k) => k in obj(row)))))
+            return undefined;
+        if (r.marketMood !== undefined &&
+            r.marketMood !== null &&
+            (!keysOnly(r.marketMood, ["fearGreed", "fetchedAt"]) ||
+                (r.marketMood.fearGreed !== null &&
+                    fearGreed(r.marketMood.fearGreed) === null) ||
+                (r.marketMood.fetchedAt !== null &&
+                    sourceTimestamp(r.marketMood.fetchedAt) !== r.marketMood.fetchedAt)))
             return undefined;
         if (r.version !== "coinrithm.decision-input.v1" ||
             r.visibility !== "private" ||

package/dist/agent/futuresEligibility.d.ts

@@ -0,0 +1,36 @@
+import type { Observation, ProposedAction } from "./types.js";
+export type FuturesEntryEligibilityStatus = "eligible" | "reference_stale" | "reference_unavailable";
+export interface FuturesEntryEligibility {
+    status: FuturesEntryEligibilityStatus;
+    /** Whether the server gate currently requires a reference for NEW opens. */
+    referenceRequired: boolean;
+    venue: string | null;
+    symbol: string | null;
+    referenceFetchedAt: string | null;
+    maxReferenceAgeHours: number;
+    evaluatedAt: string;
+}
+/**
+ * Strict parse of the market context field against its contract (backend-v2
+ * #106). Anything missing or malformed (an older API, a partial response, an
+ * unknown status, a non-boolean referenceRequired, a missing or invalid
+ * evaluatedAt, a non-positive or non-finite maxReferenceAgeHours, or a present
+ * but invalid referenceFetchedAt) is `undefined` = UNKNOWN. Unknown never
+ * blocks: the runner keeps today's behaviour and the server gate decides.
+ */
+export declare function futuresEntryEligibilityOf(marketContext: unknown): FuturesEntryEligibility | undefined;
+export interface FuturesEntryPreflightRejection {
+    code: "futures_reference_unavailable" | "futures_reference_stale";
+    reason: string;
+}
+/**
+ * Pre-quote check for a NEW futures open. Returns a rejection only when the
+ * observation EXPLICITLY reports that the server gate requires a reference and
+ * has none (or only a stale one) for this coin. Everything else passes:
+ * - non-futures_open actions (spot, PM, futures_close / futures_set_sltp);
+ * - any open futures position on the same coin (the open is an add or position
+ *   management, which the server never refuses for the reference);
+ * - unknown eligibility (field absent on an older API);
+ * - referenceRequired false.
+ */
+export declare function futuresEntryPreflight(action: ProposedAction, observation: Observation): FuturesEntryPreflightRejection | null;

package/dist/agent/futuresEligibility.js

@@ -0,0 +1,90 @@
+// Futures entry eligibility (API >= backend-v2 #106): GET /api/agent/market/{coinId}
+// carries `futuresEntryEligibility`, what the server entry gate's own
+// perpetual-reference rule says about a NEW futures open on the coin. Before it,
+// universe_scan surfaced coins with no supported perpetual reference (tokenized
+// ETFs such as SLVON/NAKA) and the runner spent a futures quote only to be
+// refused with perpetual_reference_unavailable (J-74). The server gate stays
+// authoritative: eligibility can change between observation and execution.
+import { asObj, asStr } from "./extract.js";
+import { baseSymbol } from "./setups.js";
+const STATUSES = [
+    "eligible",
+    "reference_stale",
+    "reference_unavailable",
+];
+// A zoned ISO 8601 date-time (the contract's `format: date-time`):
+// YYYY-MM-DDTHH:MM[:SS[.fraction]] with Z or a +/-HH:MM offset. Date-only,
+// zone-less and bare numbers ("0") are rejected even though Date.parse
+// accepts them.
+const ZONED_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+const isIsoDate = (v) => typeof v === "string" &&
+    ZONED_DATE_TIME.test(v) &&
+    Number.isFinite(Date.parse(v));
+/**
+ * Strict parse of the market context field against its contract (backend-v2
+ * #106). Anything missing or malformed (an older API, a partial response, an
+ * unknown status, a non-boolean referenceRequired, a missing or invalid
+ * evaluatedAt, a non-positive or non-finite maxReferenceAgeHours, or a present
+ * but invalid referenceFetchedAt) is `undefined` = UNKNOWN. Unknown never
+ * blocks: the runner keeps today's behaviour and the server gate decides.
+ */
+export function futuresEntryEligibilityOf(marketContext) {
+    const raw = asObj(asObj(marketContext).futuresEntryEligibility);
+    const status = asStr(raw.status);
+    if (!status || !STATUSES.includes(status))
+        return undefined;
+    if (typeof raw.referenceRequired !== "boolean")
+        return undefined;
+    const hours = raw.maxReferenceAgeHours;
+    if (typeof hours !== "number" || !Number.isFinite(hours) || hours <= 0)
+        return undefined;
+    if (!isIsoDate(raw.evaluatedAt))
+        return undefined;
+    const fetchedAt = raw.referenceFetchedAt;
+    if (fetchedAt != null && !isIsoDate(fetchedAt))
+        return undefined;
+    return {
+        status,
+        referenceRequired: raw.referenceRequired,
+        venue: asStr(raw.venue) ?? null,
+        symbol: asStr(raw.symbol) ?? null,
+        referenceFetchedAt: fetchedAt ?? null,
+        maxReferenceAgeHours: hours,
+        evaluatedAt: raw.evaluatedAt,
+    };
+}
+/**
+ * Pre-quote check for a NEW futures open. Returns a rejection only when the
+ * observation EXPLICITLY reports that the server gate requires a reference and
+ * has none (or only a stale one) for this coin. Everything else passes:
+ * - non-futures_open actions (spot, PM, futures_close / futures_set_sltp);
+ * - any open futures position on the same coin (the open is an add or position
+ *   management, which the server never refuses for the reference);
+ * - unknown eligibility (field absent on an older API);
+ * - referenceRequired false.
+ */
+export function futuresEntryPreflight(action, observation) {
+    if (action.type !== "futures_open")
+        return null;
+    const base = baseSymbol(action.symbol);
+    const holdsCoin = (observation.openPositions ?? []).some((p) => p.venue === "futures" &&
+        (p.status ?? "open") === "open" &&
+        baseSymbol(p.symbol) === base);
+    if (holdsCoin)
+        return null;
+    const entry = observation.watch.find((w) => baseSymbol(w.symbol) === base);
+    const e = entry?.futuresEntryEligibility;
+    if (!e || !e.referenceRequired || e.status === "eligible")
+        return null;
+    const when = ` at ${e.evaluatedAt}`;
+    if (e.status === "reference_stale") {
+        return {
+            code: "futures_reference_stale",
+            reason: `${action.symbol}: the perpetual reference${e.venue ? ` (${e.venue})` : ""} is stale or unusable for a NEW futures open${when} (too old, or its refresh time is missing, invalid or in the future); the server would refuse it (perpetual_reference_stale). Trade another coin or wait for a fresh reference.`,
+        };
+    }
+    return {
+        code: "futures_reference_unavailable",
+        reason: `${action.symbol}: CoinRithm has no supported perpetual reference for this coin${when}, so the server refuses a NEW futures open (perpetual_reference_unavailable). Use spot for it, or another coin for futures.`,
+    };
+}

package/dist/agent/observe.d.ts

@@ -1,9 +1,17 @@
 import { CoinRithmClient } from "./client.js";
-import { AgentSpec, RunState, Observation, AgentTrace } from "./types.js";
+import { AgentSpec, RunState, Observation, AgentTrace, PmCalibration, WhaleContext } from "./types.js";
 export interface ObserveOutput {
     observation: Observation;
     skip?: string;
 }
+/**
+ * Add bounded public whale context after the deterministic gate. This is
+ * deliberately separate from observe(): a skipped or mechanical cycle never
+ * pays for the public reads, and this context cannot widen candidate selection.
+ */
+export declare function enrichWhaleContext(client: CoinRithmClient, observation: Observation): Promise<WhaleContext>;
+export declare function clearPmCalibrationCache(): void;
+export declare function readPmCalibration(client: CoinRithmClient, trace?: AgentTrace, nowMs?: number): Promise<PmCalibration | undefined>;
 export declare function isCalibrationChurnMarket(market: {
     slug?: string;
     title?: string;