@coinrithm/mcp-trading 0.7.14 → 0.7.16

package/dist/agent/universe.js

@@ -0,0 +1,215 @@
+// Agent market BOUNDARIES (owner 2026-10-07, Telegram 56641/56644). Instead of
+// a fixed coin list, a bundle declares where its agent may look:
+//
+//   universe:
+//     rank: { min: 1, max: 100 }      # market-cap rank band
+//     minVolume24hUsd: 1000000        # liquidity floor
+//     excludeStablecoins: true
+//     includeSectors: [defi, ai]      # curated ids, GET /api/agent/universe/sectors
+//     excludeSectors: [meme]
+//     sort: abs_change_24h            # what "an opportunity" means first
+//     resolveTop: 6                   # rows resolved into full watch entries
+//
+// Each cycle observe() asks GET /api/agent/universe for the rows inside those
+// boundaries, resolves the top few into full watch entries (marked
+// `discovered: true`) and passes the rest as compact context. The validator's
+// tradable set is watch membership, so a discovered row is tradable for that
+// cycle and every cap still applies; the blocklist still wins. The server
+// filters, and filterUniverseRows re-checks what the row says about itself,
+// so a wrong or older server can narrow the set but never widen it.
+export const UNIVERSE_SORTS = [
+    "gainers_24h",
+    "losers_24h",
+    "abs_change_24h",
+    "abs_change_1h",
+    "volume_24h",
+    "rank",
+];
+export const UNIVERSE_DEFAULTS = {
+    rankMin: 1,
+    rankMax: 100,
+    minVolume24hUsd: 0,
+    sort: "abs_change_24h",
+    resolveTop: 6,
+    scanLimit: 15,
+};
+export const UNIVERSE_MAX_RESOLVE_TOP = 10;
+export const UNIVERSE_MAX_SCAN_LIMIT = 50;
+const SECTOR_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** True when the agent discovers candidates beyond its watchlist. */
+export function scansUniverse(spec) {
+    return (spec.universe !== undefined || spec.capabilities.includes("universe_scan"));
+}
+/** The screener query a validated universe block asks for. */
+export function universeQuery(u) {
+    return {
+        rankMin: u.rank?.min ?? UNIVERSE_DEFAULTS.rankMin,
+        rankMax: u.rank?.max ?? UNIVERSE_DEFAULTS.rankMax,
+        minVolume24hUsd: u.minVolume24hUsd ?? UNIVERSE_DEFAULTS.minVolume24hUsd,
+        excludeStablecoins: u.excludeStablecoins ?? false,
+        includeSectors: [...(u.includeSectors ?? [])],
+        excludeSectors: [...(u.excludeSectors ?? [])],
+        sort: u.sort ?? UNIVERSE_DEFAULTS.sort,
+        limit: u.scanLimit ?? UNIVERSE_DEFAULTS.scanLimit,
+    };
+}
+/** How many screener rows become full watch entries this cycle. */
+export function universeResolveTop(u) {
+    return Math.min(u.resolveTop ?? UNIVERSE_DEFAULTS.resolveTop, UNIVERSE_MAX_RESOLVE_TOP);
+}
+/** Wire form: csv sectors, string numbers; empty filters are omitted. With
+ * `ucids`, the same boundaries are applied to just those coins (membership). */
+export function universeQueryParams(q, ucids) {
+    return {
+        ...(ucids && ucids.length > 0 ? { ucids: ucids.join(",") } : {}),
+        rankMin: q.rankMin,
+        rankMax: q.rankMax,
+        minVolume24hUsd: q.minVolume24hUsd,
+        excludeStablecoins: q.excludeStablecoins ? "true" : "false",
+        ...(q.includeSectors.length
+            ? { includeSectors: q.includeSectors.join(",") }
+            : {}),
+        ...(q.excludeSectors.length
+            ? { excludeSectors: q.excludeSectors.join(",") }
+            : {}),
+        sort: q.sort,
+        limit: q.limit,
+    };
+}
+/** Keep malformed evidence unknown; dropping bad elements can widen a screen. */
+export function universeSectorsOf(raw) {
+    return Array.isArray(raw) &&
+        raw.every((s) => typeof s === "string" && SECTOR_ID_RE.test(s))
+        ? raw
+        : undefined;
+}
+/**
+ * Defence in depth on server rows (never widen): a row is kept only when its
+ * own fields PROVE it is inside every enabled boundary. The rank band is
+ * always enabled, so a row without a rank is dropped; a volume floor needs a
+ * volume; any sector rule (stablecoins out, sectors out, sectors in) needs the
+ * row's sector list. Missing or malformed evidence drops the row (root review
+ * 2026-10-07: unverifiable is not inside).
+ */
+export function filterUniverseRows(rows, q) {
+    const excluded = new Set([
+        ...q.excludeSectors,
+        ...(q.excludeStablecoins ? ["stablecoins"] : []),
+    ]);
+    const included = q.includeSectors.filter((s) => !excluded.has(s));
+    const sectorRules = excluded.size > 0 || q.includeSectors.length > 0;
+    return rows.filter((r) => {
+        const rank = r.marketCapRank;
+        if (typeof rank !== "number" || !Number.isFinite(rank))
+            return false;
+        if (rank < q.rankMin || rank > q.rankMax)
+            return false;
+        if (q.minVolume24hUsd > 0) {
+            const vol = r.volume24hUsd;
+            if (typeof vol !== "number" || !Number.isFinite(vol))
+                return false;
+            if (vol < q.minVolume24hUsd)
+                return false;
+        }
+        if (sectorRules) {
+            const sectors = universeSectorsOf(r.sectors);
+            if (sectors === undefined)
+                return false;
+            if (sectors.some((s) => excluded.has(s)))
+                return false;
+            if (q.includeSectors.length > 0 &&
+                !sectors.some((s) => included.includes(s)))
+                return false;
+        }
+        return true;
+    });
+}
+/**
+ * Entry eligibility under declared boundaries (root review 2026-10-07): with a
+ * `universe` block, a NEW position may only be opened on a coin proven inside
+ * the boundaries this cycle: a discovered row, or a watchlist coin the
+ * screener confirmed (`withinBoundaries: true`). Anything else (outside, or
+ * unverifiable because the check failed) stays visible as context and can
+ * still be closed or sold, but not entered. Returns the rejection reason, or
+ * null when the entry is allowed. No universe block = no extra rule.
+ */
+export function universeEntryBlock(spec, entry) {
+    if (!spec.universe)
+        return null;
+    if (entry.discovered === true || entry.withinBoundaries === true)
+        return null;
+    return entry.withinBoundaries === false
+        ? "outside the declared market boundaries"
+        : "not verified inside the declared market boundaries this cycle";
+}
+/** Validation issues for a raw `universe` block ([] when valid or absent). */
+export function universeIssues(raw) {
+    if (raw === undefined)
+        return [];
+    const issues = [];
+    const add = (code, reason) => issues.push([code, reason]);
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        add("skill_universe", "universe must be a mapping");
+        return issues;
+    }
+    const u = raw;
+    const int = (v, lo, hi) => typeof v === "number" && Number.isInteger(v) && v >= lo && v <= hi;
+    if (u.rank !== undefined) {
+        const rank = u.rank;
+        if (rank === null || typeof rank !== "object" || Array.isArray(rank)) {
+            add("skill_universe_rank", "universe.rank must be { min, max }");
+        }
+        else {
+            if (rank.min !== undefined && !int(rank.min, 1, 10_000))
+                add("skill_universe_rank", "universe.rank.min must be a whole number between 1 and 10000");
+            if (rank.max !== undefined && !int(rank.max, 1, 10_000))
+                add("skill_universe_rank", "universe.rank.max must be a whole number between 1 and 10000");
+            const min = rank.min ?? UNIVERSE_DEFAULTS.rankMin;
+            const max = rank.max ?? UNIVERSE_DEFAULTS.rankMax;
+            if (int(min, 1, 10_000) && int(max, 1, 10_000) && min > max)
+                add("skill_universe_rank", "universe.rank.min must be <= rank.max");
+        }
+    }
+    if (u.minVolume24hUsd !== undefined &&
+        !(typeof u.minVolume24hUsd === "number" &&
+            Number.isFinite(u.minVolume24hUsd) &&
+            u.minVolume24hUsd >= 0))
+        add("skill_universe_volume", "universe.minVolume24hUsd must be a number >= 0");
+    if (u.excludeStablecoins !== undefined &&
+        typeof u.excludeStablecoins !== "boolean")
+        add("skill_universe_stablecoins", "universe.excludeStablecoins must be true or false");
+    for (const key of ["includeSectors", "excludeSectors"]) {
+        const v = u[key];
+        if (v === undefined)
+            continue;
+        if (!Array.isArray(v) ||
+            v.length > 50 ||
+            !v.every((s) => typeof s === "string" && SECTOR_ID_RE.test(s)))
+            add("skill_universe_sectors", `universe.${key} must be a list of sector ids like "defi" or "eco-solana" (GET /api/agent/universe/sectors)`);
+    }
+    if (u.sort !== undefined &&
+        !UNIVERSE_SORTS.includes(u.sort))
+        add("skill_universe_sort", `universe.sort must be one of ${UNIVERSE_SORTS.join(", ")}`);
+    if (u.resolveTop !== undefined &&
+        !int(u.resolveTop, 1, UNIVERSE_MAX_RESOLVE_TOP))
+        add("skill_universe_resolve_top", `universe.resolveTop must be a whole number between 1 and ${UNIVERSE_MAX_RESOLVE_TOP}`);
+    if (u.scanLimit !== undefined &&
+        !int(u.scanLimit, 1, UNIVERSE_MAX_SCAN_LIMIT))
+        add("skill_universe_scan_limit", `universe.scanLimit must be a whole number between 1 and ${UNIVERSE_MAX_SCAN_LIMIT}`);
+    return issues;
+}
+/** One line for the prompt: the boundaries in plain words. */
+export function describeUniverse(u) {
+    const q = universeQuery(u);
+    const parts = [`market-cap rank ${q.rankMin}-${q.rankMax}`];
+    if (q.minVolume24hUsd > 0)
+        parts.push(`24h volume >= $${Math.round(q.minVolume24hUsd).toLocaleString("en-US")}`);
+    if (q.excludeStablecoins)
+        parts.push("no stablecoins");
+    if (q.includeSectors.length)
+        parts.push(`only sectors: ${q.includeSectors.join(", ")}`);
+    if (q.excludeSectors.length)
+        parts.push(`excluding sectors: ${q.excludeSectors.join(", ")}`);
+    parts.push(`ranked by ${q.sort.replace(/_/g, " ")}`);
+    return parts.join("; ");
+}

package/dist/client.d.ts

@@ -39,6 +39,7 @@ export type ProvenanceReport = {
         sourceCapturedAt?: string;
     };
 };
+export declare const API_KEY_MINT_URL = "https://www.coinrithm.com/en/settings/api-keys";
 export declare class CoinRithmClient {
     private readonly defaultApiKey?;
     private readonly baseUrl;
@@ -113,6 +114,12 @@ export declare class CoinRithmClient {
         range?: "1H" | "1D" | "1W" | "1M" | "3M";
         fiat?: string;
     }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getNews(query: {
+        coins: string;
+        limit?: number;
+        hours?: number;
+        minImportance?: number;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
     discoverPmMarkets(query?: {
         q?: string;
         source?: "all" | "kalshi" | "polymarket";
@@ -145,8 +152,8 @@ export declare class CoinRithmClient {
         page?: number;
         pageSize?: number;
         window?: "7d" | "30d" | "all";
-    }, apiKey?: string): Promise<ApiResult>;
-    getArenaAgent(handle: string, apiKey?: string): Promise<ApiResult>;
+    }): Promise<ApiResult>;
+    getArenaAgent(handle: string): Promise<ApiResult>;
     listOpenOrders(query?: {
         coinId?: string;
         limit?: number;

package/dist/client.js

@@ -71,6 +71,9 @@ const applyAgentTraceHeaders = (headers, trace) => {
 const traceFromBody = (body) => body && typeof body === "object" && "agentTrace" in body
     ? body.agentTrace
     : undefined;
+// Where a user mints an API key (Settings -> API Keys). Named in every
+// missing-key error so an assistant can tell its user where to go.
+export const API_KEY_MINT_URL = "https://www.coinrithm.com/en/settings/api-keys";
 export class CoinRithmClient {
     // Default key for the stdio (single-user) path. Undefined in the multi-user
     // HTTP path, where every call must pass a per-request `apiKey` override.
@@ -88,8 +91,10 @@ export class CoinRithmClient {
                 status: 401,
                 data: {
                     error: "missing_api_key",
-                    message: "No API key for this request. On the hosted MCP, send " +
-                        "`Authorization: Bearer crk_live_…` with your own key.",
+                    message: "No API key for this request. Mint a free key at " +
+                        `${API_KEY_MINT_URL}, then on the hosted MCP send ` +
+                        "`Authorization: Bearer crk_live_…`. Public data tools " +
+                        "(pm_data_*, get_arena_*, get_crypto_movers) need no key.",
                 },
             };
         }
@@ -337,6 +342,13 @@ export class CoinRithmClient {
     getCandles(coinId, query, apiKey, agentTrace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}/candles`, { query, apiKey, agentTrace });
     }
+    getNews(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/news", {
+            query,
+            apiKey,
+            agentTrace,
+        });
+    }
     discoverPmMarkets(query, apiKey, agentTrace) {
         return this.request("GET", "/api/agent/pm/discover", {
             query,
@@ -364,15 +376,15 @@ export class CoinRithmClient {
             agentTrace,
         });
     }
-    // Agent Arena (public leaderboard). The key is sent but ignored by these
-    // endpoints — they expose only public agent names + realized performance.
-    getArenaLeaderboard(query, apiKey) {
-        return this.request("GET", "/api/arena", { query, apiKey });
+    // Agent Arena (public leaderboard): public agent names + realized
+    // performance only, served keyless by the API. These used to go through
+    // the keyed path, so a keyless MCP client got a 401 for public data
+    // (21 of 44 keyless tool calls failed in 14.6h, audit 2026-09-29).
+    getArenaLeaderboard(query) {
+        return this.publicRequest("/api/arena", query);
     }
-    getArenaAgent(handle, apiKey) {
-        return this.request("GET", `/api/arena/${encodeURIComponent(handle)}`, {
-            apiKey,
-        });
+    getArenaAgent(handle) {
+        return this.publicRequest(`/api/arena/${encodeURIComponent(handle)}`);
     }
     listOpenOrders(query, apiKey, agentTrace) {
         return this.request("GET", "/api/agent/orders/open", {

package/dist/http.d.ts

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CoinRithmClient } from "./client.js";
 import { type CompletionLogger } from "./httpCompletion.js";
+export declare const MALFORMED_MCP_LINK: RegExp;
 export declare function createHttpApp(client: CoinRithmClient, options?: {
     completionLogger?: CompletionLogger;
     createServer?: () => McpServer;

package/dist/http.js

@@ -34,6 +34,7 @@
 // Transport is stateless: a fresh McpServer + transport per request, which is
 // the correct isolation model for a multi-user, per-request-keyed surface — no
 // session state is shared between users.
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
 import express from "express";
 import { pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -42,6 +43,9 @@ import { CoinRithmClient, bearerFromHeader, loadHttpConfig, log, } from "./clien
 import { registerTools } from "./tools.js";
 import { SERVER_VERSION } from "./version.js";
 import { observeHttpCompletion, } from "./httpCompletion.js";
+// "/mcp" immediately followed by the markdown "](" of a pasted link, literal or
+// percent-encoded. Anything else under /mcp is not this family.
+export const MALFORMED_MCP_LINK = /^\/mcp(?:\]|%5d)(?:\(|%28)/i;
 // Factory permits isolated localhost SDK tests without opening a listener on import.
 export function createHttpApp(client, options = {}) {
     const app = express();
@@ -108,13 +112,24 @@ export function createHttpApp(client, options = {}) {
     app.get("/robots.txt", (_req, res) => {
         res.type("text/plain").send("User-agent: *\nDisallow: /\n");
     });
+    // Recover one observed malformed URL family. A markdown link to this
+    // endpoint circulates with its "](https://…)" suffix pasted into the path,
+    // e.g. GET /mcp](https:/mcp.coinrithm.com/mcp): 408 such requests on
+    // 2026-09-25, all Claude-User web fetches that received Express's default
+    // 404. GET/HEAD go to the service descriptor. POST is served as MCP below:
+    // on 2026-09-26, 127 Claude-User connector POSTs in 6 h hit the same path
+    // and got 404, so a user who pasted that URL into a connector could never
+    // initialize. Every other unknown path behaves as before.
+    app.get(MALFORMED_MCP_LINK, (_req, res) => {
+        res.redirect(302, "/");
+    });
     app.get("/mcp", (_req, res) => {
         res.status(405).json({
             error: "method_not_allowed",
             message: "This is a POST-only streamable-HTTP MCP endpoint. Connect with an MCP client, or GET / for service info.",
         });
     });
-    app.post("/mcp", async (req, res) => {
+    app.post(["/mcp", MALFORMED_MCP_LINK], async (req, res) => {
         // Per-request auth: read THIS caller's key from the Authorization header,
         // or from Smithery's non-reserved forwarding header.
         // It is optional at the transport layer so registries can initialize the
@@ -132,7 +147,7 @@ export function createHttpApp(client, options = {}) {
             new McpServer({
                 name: "coinrithm-trading",
                 version: SERVER_VERSION,
-            });
+            }, { instructions: SERVER_INSTRUCTIONS });
         if (!options.createServer)
             registerTools(server, client);
         const transport = new StreamableHTTPServerTransport({

package/dist/httpCompletion.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-export declare const COMPLETION_TOOL_NAMES: readonly ["whoami", "get_portfolio", "get_wallet", "list_open_orders", "get_positions", "resolve_symbol", "get_equity_curve", "get_my_trades", "get_market_context", "get_candles", "discover_pm_markets", "get_performance", "get_agent_ledger", "export_agent_ledger", "export_run_evidence", "get_arena_leaderboard", "get_arena_agent", "futures_quote", "pm_quote", "spot_quote", "place_spot_order", "cancel_spot_order", "open_futures_position", "set_futures_sl_tp", "close_futures_position", "open_pm_position", "report_pm_opportunity", "pm_data_overview", "pm_data_sources", "pm_data_sources_health", "pm_data_events", "pm_data_event", "pm_data_whales", "pm_data_whale_wallets", "pm_data_whale_wallet", "pm_data_disagreements", "pm_data_calibration", "pm_data_canonical", "pm_data_volume_history", "get_crypto_movers"];
+export declare const COMPLETION_TOOL_NAMES: readonly ["whoami", "get_portfolio", "get_wallet", "list_open_orders", "get_positions", "resolve_symbol", "get_equity_curve", "get_my_trades", "get_market_context", "get_candles", "get_news", "discover_pm_markets", "get_performance", "get_agent_ledger", "export_agent_ledger", "export_run_evidence", "get_arena_leaderboard", "get_arena_agent", "futures_quote", "pm_quote", "spot_quote", "place_spot_order", "cancel_spot_order", "open_futures_position", "set_futures_sl_tp", "close_futures_position", "open_pm_position", "report_pm_opportunity", "pm_data_overview", "pm_data_sources", "pm_data_sources_health", "pm_data_events", "pm_data_event", "pm_data_whales", "pm_data_whale_wallets", "pm_data_whale_wallet", "pm_data_disagreements", "pm_data_calibration", "pm_data_canonical", "pm_data_volume_history", "get_crypto_movers"];
 type Operation = "initialize" | "tools_list" | "tools_call" | "notification" | "other" | "invalid";
 type Outcome = "result" | "tool_error" | "protocol_error" | "no_response" | "not_applicable";
 type ToolName = (typeof COMPLETION_TOOL_NAMES)[number] | "unknown" | null;

package/dist/httpCompletion.js

@@ -13,6 +13,7 @@ export const COMPLETION_TOOL_NAMES = [
     "get_my_trades",
     "get_market_context",
     "get_candles",
+    "get_news",
     "discover_pm_markets",
     "get_performance",
     "get_agent_ledger",

package/dist/index.js

@@ -10,6 +10,7 @@
 //   COINRITHM_API_URL  (optional)  base URL; defaults to https://api.coinrithm.com
 //
 // stdout is the JSON-RPC channel — we log ONLY to stderr.
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CoinRithmClient, loadConfig, log } from "./client.js";
@@ -21,7 +22,7 @@ async function main() {
     const server = new McpServer({
         name: "coinrithm-trading",
         version: SERVER_VERSION,
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     registerTools(server, client);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,16 @@
+import { API_KEY_MINT_URL } from "./client.js";
+import { PAPER_NOTE } from "./tools.js";
+// Sent once in the MCP `initialize` result. Guidance that used to be repeated
+// on every tool description lives here, so the tool list stays small enough to
+// fit an assistant's context (tools/list was 114,668 bytes with the ~512-char
+// paper disclaimer on 25 tools, audit 2026-09-29).
+export const SERVER_INSTRUCTIONS = [
+    "CoinRithm MCP: crypto and prediction-market data from 12 venues, plus paper trading.",
+    "Start keyless: the pm_data_* tools, get_arena_leaderboard, get_arena_agent and get_crypto_movers need no API key.",
+    "pm_data_events returns open markets by default; pass status=closed or status=all for history.",
+    `Tools that read or act on an account need a key. The user mints one at ${API_KEY_MINT_URL}; start with a read-only key.`,
+    "Every tool returns { httpStatus, ok, ledgerEventId, ledgerStatus, body }: httpStatus is CoinRithm's HTTP status (0 = network error), ok means 2xx, body is the parsed response.",
+    "Always quote before a paper write (spot_quote, futures_quote or pm_quote), then open with that quote.",
+    "Prediction-market probabilities are venue prices, not CoinRithm forecasts. referenceProbability is a cross-venue consensus with a disagreement band (spreadPoints).",
+    PAPER_NOTE,
+].join("\n");

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CoinRithmClient } from "./client.js";
 export declare const PAPER_NOTE: string;
+export declare const PAPER_NOTE_SHORT: string;
 /**
  * Keep keyless discovery calls small enough for an agent context window.
  * Full event evidence remains available from pm_data_event.