@coinrithm/mcp-trading 0.7.14 → 0.7.16

package/dist/tools.js

@@ -7,8 +7,9 @@
 import { z } from "zod";
 import { bearerFromHeader } from "./client.js";
 import { PAPER_EXECUTION_VERSION } from "./executionPolicy.js";
-// Served on tool descriptions. Names the versioned execution policy and never
-// claims costless execution (drift-tested in executionPolicy.test.ts).
+// Served once in the MCP server instructions (instructions.ts). Names the
+// versioned execution policy and never claims costless execution
+// (drift-tested in executionPolicy.test.ts).
 export const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice. " +
     `Paper fills run under the versioned ${PAPER_EXECUTION_VERSION} policy and ` +
     "apply a disclosed execution cost folded into realized PnL: " +
@@ -17,27 +18,22 @@ export const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). N
     "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.";
+// Per-tool form of PAPER_NOTE. The full note is sent once in the server
+// instructions (instructions.ts); every tool still names the versioned
+// execution policy and its disclosed cost (drift-tested with PAPER_NOTE).
+export const PAPER_NOTE_SHORT = `Paper trading only (virtual mUSD). Fills follow ${PAPER_EXECUTION_VERSION} ` +
+    "with a disclosed execution cost; see executionModel in quote/trade results.";
+// The same result envelope on every tool: { httpStatus, ok, ledgerEventId,
+// ledgerStatus, body }. It is sent 40 times in tools/list, so its field
+// descriptions live in the server instructions' wording, not here: httpStatus
+// is CoinRithm's HTTP status (0 = network error), ok is a 2xx, the ledger
+// fields come from /api/agent/* writes, and body is the parsed response.
 const API_RESULT_OUTPUT_SCHEMA = {
-    httpStatus: z
-        .number()
-        .int()
-        .describe("HTTP status returned by CoinRithm, or 0 for network errors."),
-    ok: z
-        .boolean()
-        .describe("True when CoinRithm returned a successful 2xx response."),
-    ledgerEventId: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Private AgentActionEvent id returned by /api/agent/*, when present."),
-    ledgerStatus: z
-        .string()
-        .nullable()
-        .optional()
-        .describe("Ledger write status header returned by CoinRithm, when present."),
-    body: z
-        .unknown()
-        .describe("Parsed CoinRithm response body, or raw text when the response is not JSON."),
+    httpStatus: z.number().int(),
+    ok: z.boolean(),
+    ledgerEventId: z.string().nullable().optional(),
+    ledgerStatus: z.string().nullable().optional(),
+    body: z.unknown(),
 };
 const AGENT_TRACE_SCHEMA = z
     .object({
@@ -165,9 +161,7 @@ function present(result) {
         body: result.data,
     };
     return {
-        content: [
-            { type: "text", text: JSON.stringify(payload, null, 2) },
-        ],
+        content: [{ type: "text", text: JSON.stringify(payload) }],
         structuredContent: payload,
         isError: !result.ok,
     };
@@ -226,6 +220,9 @@ const OUTCOME_SUMMARY_FIELDS = [
     "lifecycle",
     "priorProbability",
     "venueTerms",
+    "hasObservedPrice",
+    "priceBasis",
+    "sourceObservation",
 ];
 const WHALE_TRADE_FIELDS = [
     "source",
@@ -233,6 +230,7 @@ const WHALE_TRADE_FIELDS = [
     "eventSlug",
     "eventTitle",
     "wallet",
+    "walletAddress",
     "traderName",
     "side",
     "outcome",
@@ -256,6 +254,32 @@ function boundedText(value, maxLength) {
         return value;
     return `${value.slice(0, maxLength - 1)}…`;
 }
+function compactSourceObservation(value) {
+    if (value === null)
+        return null;
+    if (!isJsonRecord(value))
+        return undefined;
+    return pick(value, [
+        "version",
+        "basis",
+        "provider",
+        "observedAt",
+        "tradeDate",
+    ]);
+}
+function compactOutcomeSummary(value) {
+    if (!isJsonRecord(value))
+        return value;
+    const outcome = pick(value, OUTCOME_SUMMARY_FIELDS);
+    if ("sourceObservation" in outcome) {
+        const sourceObservation = compactSourceObservation(value.sourceObservation);
+        if (sourceObservation === undefined)
+            delete outcome.sourceObservation;
+        else
+            outcome.sourceObservation = sourceObservation;
+    }
+    return outcome;
+}
 function compactWhaleTrade(value) {
     return isJsonRecord(value) ? pick(value, WHALE_TRADE_FIELDS) : value;
 }
@@ -308,9 +332,7 @@ function eventSummary(value) {
                 : left.index - right.index;
         })
             .slice(0, 5)
-            .map(({ outcome }) => isJsonRecord(outcome)
-            ? pick(outcome, OUTCOME_SUMMARY_FIELDS)
-            : outcome)
+            .map(({ outcome }) => isJsonRecord(outcome) ? compactOutcomeSummary(outcome) : outcome)
         : [];
     return {
         ...pick(value, EVENT_SUMMARY_FIELDS),
@@ -392,9 +414,7 @@ function compactSnapshot(value) {
                 outcomeCount: value.outcomes.length,
                 outcomes: value.outcomes
                     .slice(0, 10)
-                    .map((outcome) => isJsonRecord(outcome)
-                    ? pick(outcome, OUTCOME_SUMMARY_FIELDS)
-                    : outcome),
+                    .map((outcome) => isJsonRecord(outcome) ? compactOutcomeSummary(outcome) : outcome),
             }
             : {}),
     };
@@ -425,6 +445,8 @@ function compactComparison(value) {
             "label",
             "eventAProbability",
             "eventBProbability",
+            "eventAHasObservedPrice",
+            "eventBHasObservedPrice",
             "deltaPoints",
             "presentInA",
             "presentInB",
@@ -727,7 +749,7 @@ export function registerTools(server, client) {
             "(equity.totalUsd plus available/frozen/frozenPm/frozenFutures/" +
             "cashTotal cash partitions), period PnL (pnl.24hUsd … allTimePct), " +
             "open spot orders, and a progression block (league/XP). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             fiat: z
                 .string()
@@ -744,7 +766,7 @@ export function registerTools(server, client) {
         description: "Get raw cash balances: USDT available plus the three frozen partitions " +
             "(frozen = spot orders, frozenPm = PM, frozenFutures = futures margin). " +
             "Optionally include one coin asset. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z
                 .string()
@@ -761,7 +783,7 @@ export function registerTools(server, client) {
             "across coins, or pass one to filter. Response includes asOf — pass it " +
             "back as updatedSince on the next call to poll only rows that changed " +
             "(delta polling). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z
                 .string()
@@ -793,7 +815,7 @@ export function registerTools(server, client) {
             "unrealized mark on open ones). Response includes asOf — pass it back " +
             "as updatedSince on the next call to poll only positions that changed " +
             "(catches worker-fired SL/TP, liquidations, and settlements). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             venue: z
                 .enum(["futures", "pm"])
@@ -817,7 +839,7 @@ export function registerTools(server, client) {
             "CoinGecko category tags. Use this FIRST to get the coinId that the " +
             "wallet / quote / order tools need — don't guess UCIDs (symbols are not " +
             "unique). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             q: z
                 .string()
@@ -837,7 +859,7 @@ export function registerTools(server, client) {
             "PnL event (spot sells, futures closes/liquidations, PM settlements) " +
             "with a cumulative running total — use it for active intraday agents. " +
             "days = look-back window (1-365, default 30). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             days: z
                 .number()
@@ -865,7 +887,7 @@ export function registerTools(server, client) {
             "asOf — pass it back as updatedSince on the next call to fetch only " +
             "NEW closes since your last poll (how you discover worker-fired " +
             "stop-loss/take-profit, liquidations, and PM settlements). " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             venue: z
                 .enum(["all", "spot", "futures", "pm"])
@@ -899,7 +921,7 @@ export function registerTools(server, client) {
             "market's depth/tradability — and up to 6 similar coins (shared category " +
             "/ market-cap peers). Facts only — no generated thesis. Call " +
             "resolve_symbol first to get the coinId. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z
                 .string()
@@ -921,7 +943,7 @@ export function registerTools(server, client) {
             "These are sampled composite-price bars, not venue trade candles. " +
             "v is the mean rolling 24-hour quote-volume observation in the bar, " +
             "NOT volume traded during that candle; do not sum v across bars. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z
                 .string()
@@ -940,6 +962,47 @@ export function registerTools(server, client) {
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get OHLCV candles"),
     }, async ({ coinId, range, fiat, agentTrace }, extra) => present(await client.getCandles(coinId, { range, fiat }, requestKey(extra), agentTrace)));
+    server.registerTool("get_news", {
+        title: "Get scored crypto news",
+        description: "Recent crypto news for up to 25 coins, linked to each coin by " +
+            "CoinRithm's curated coin-news graph. Only AI-scored stories are " +
+            "returned: sentiment (bullish, bearish or neutral) with its " +
+            "confidence and importance 0-10 (8+ = market-moving), ranked by " +
+            "importance then recency. ageMinutes is each story's age. Scoring can " +
+            "lag publication by hours, so an empty or older list does not prove " +
+            "there is no news. Needs an API key with read scope.",
+        inputSchema: {
+            coins: z
+                .string()
+                .min(1)
+                .max(400)
+                .describe('Comma-separated symbols or slugs, e.g. "BTC,ETH" (max 25).'),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(25)
+                .optional()
+                .describe("Stories to return, 1-25 (default 8)."),
+            hours: z
+                .number()
+                .int()
+                .min(1)
+                .max(168)
+                .optional()
+                .describe("Look-back window in hours, 1-168 (default 48)."),
+            minImportance: z
+                .number()
+                .int()
+                .min(0)
+                .max(10)
+                .optional()
+                .describe("Only stories at or above this importance (default 0)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get scored crypto news"),
+    }, async ({ coins, limit, hours, minImportance, agentTrace }, extra) => present(await client.getNews({ coins, limit, hours, minImportance }, requestKey(extra), agentTrace)));
     server.registerTool("discover_pm_markets", {
         title: "Discover prediction markets",
         description: "Find active-open, quote-ready-first prediction markets on the mock-PM " +
@@ -951,7 +1014,7 @@ export function registerTools(server, client) {
             "while the market stays visible). This is discovery only — call pm_quote " +
             "with one returned outcomeExternalMarketId before open_pm_position " +
             "because pm_quote is the final eligibility source. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             q: z
                 .string()
@@ -996,7 +1059,7 @@ export function registerTools(server, client) {
             "PnL (mUSD), trade count, win/loss/neutral counts, and win rate (null " +
             "until there are decided trades). Closed trades only — the scorecard for " +
             "this agent. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             agentTrace: AGENT_TRACE_SCHEMA,
         },
@@ -1009,7 +1072,7 @@ export function registerTools(server, client) {
             "rejects, idempotent replays, latency, sanitized summaries, and optional " +
             "run/decision trace metadata. Only rows for the calling key are returned. " +
             "Use this to audit a reproducible paper-trading run. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             venue: z.string().optional().describe("Optional venue filter."),
             eventType: z
@@ -1057,7 +1120,7 @@ export function registerTools(server, client) {
         description: "Export up to 1,000 private ledger rows for the calling API key as JSON. " +
             "Use filters to export a specific runId or decisionId for reproducible " +
             "evaluation. No public Arena user can see this data. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             venue: z.string().optional().describe("Optional venue filter."),
             eventType: z
@@ -1083,7 +1146,7 @@ export function registerTools(server, client) {
             "The bundle includes sanitized ledger rows, execution assumptions, " +
             "retention policy, outcome attribution, and the evidence checklist. " +
             "No public Arena user can see this data. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             runId: z.string().min(1).describe("Required run id to export."),
             agentTrace: AGENT_TRACE_SCHEMA,
@@ -1105,7 +1168,7 @@ export function registerTools(server, client) {
             "and where you stand — pair " +
             "with get_performance (your own scorecard) and get_arena_agent (drill " +
             "into one handle). Public data: agent names + performance only. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             page: z
                 .number()
@@ -1130,14 +1193,14 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get Agent Arena leaderboard"),
-    }, async ({ page, pageSize, window }, extra) => present(await client.getArenaLeaderboard({ page, pageSize, window }, requestKey(extra))));
+    }, async ({ page, pageSize, window }) => present(await client.getArenaLeaderboard({ page, pageSize, window })));
     server.registerTool("get_arena_agent", {
         title: "Get Agent Arena profile",
         description: "One agent's public Arena profile by handle (the `handle` field from " +
             "get_arena_leaderboard, e.g. 'a42-momentum-scout'): rank, total + " +
             "per-venue realized PnL, decided/total trade counts, and win rate. " +
             "Public data only — no account or key identity. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             handle: z
                 .string()
@@ -1146,14 +1209,14 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get Agent Arena profile"),
-    }, async ({ handle }, extra) => present(await client.getArenaAgent(handle, requestKey(extra))));
+    }, async ({ handle }) => present(await client.getArenaAgent(handle)));
     // ---------------- quotes (read scope, read-only) ----------------
     server.registerTool("futures_quote", {
         title: "Futures quote",
         description: "Read-only futures quote: entry price, notional, size, liquidation price, " +
             "and eligibility. Never mutates state — always quote before opening. " +
             "leverage 1-20, marginMusd >= 10. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z.string().describe("Coin UCID."),
             side: z
@@ -1182,7 +1245,7 @@ export function registerTools(server, client) {
             "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,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             source: z.string().describe("Source slug (e.g. kalshi, polymarket)."),
             slug: z.string().describe("Event slug."),
@@ -1231,7 +1294,7 @@ export function registerTools(server, client) {
             "before place_spot_order instead of buying/selling blind. Price age is " +
             "informational only (a market order fills regardless). coinId is a UCID, " +
             "NOT a ticker — use resolve_symbol first. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z.string().describe("Coin UCID (e.g. '1' = BTC)."),
             side: z
@@ -1255,7 +1318,7 @@ export function registerTools(server, client) {
             "per intent (reuse replays the original result — retry a timed-out " +
             "call with the SAME key; it will never double-execute). Requires the " +
             "trade:spot scope. CONFIRM with the user before calling. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z.string().describe('Coin UCID (e.g. "1" = BTC).'),
             side: z
@@ -1326,7 +1389,7 @@ export function registerTools(server, client) {
             "stopLossPrice/takeProfitPrice atomically at open (side-aware corridor: " +
             "long needs liq < SL < mark < TP; short inverted) — protecting every " +
             "position is good practice. Quote first and CONFIRM with the user. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             coinId: z
                 .string()
@@ -1384,7 +1447,7 @@ export function registerTools(server, client) {
             "live mark (liquidation always takes precedence); a fire closes the " +
             "FULL position at mark with realized PnL. Discover fills between polls " +
             "via my_trades with updatedSince. Requires the trade:futures scope. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             positionId: z
                 .number()
@@ -1420,7 +1483,7 @@ export function registerTools(server, client) {
         description: "Close or partially reduce a mock futures position. fraction in (0,1] " +
             "reduces partially; omit (or 1) for a full close. idempotencyKey is " +
             "REQUIRED. Requires the trade:futures scope. " +
-            PAPER_NOTE,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             positionId: z
                 .number()
@@ -1453,7 +1516,7 @@ export function registerTools(server, client) {
             "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,
+            PAPER_NOTE_SHORT,
         inputSchema: {
             source: z
                 .string()
@@ -1683,7 +1746,8 @@ export function registerTools(server, client) {
             status: z
                 .string()
                 .optional()
-                .describe("Optional status filter (e.g. open or closed)."),
+                .describe("Status filter: open (default), closed, or all. Without it " +
+                "the API's newest-first list starts with long-closed markets."),
             sort: z.string().optional().describe("Optional sort key."),
             limit: z
                 .number()
@@ -1708,7 +1772,9 @@ export function registerTools(server, client) {
     }, async ({ q, source, status, sort, limit, offset, fiat }) => present(mapSuccessfulBody(await client.listPublicPmEvents({
         q,
         source,
-        status,
+        // Open by default: with no status the API's first page was 20
+        // closed markets, 70+ days stale (audit 2026-09-29).
+        status: status ?? "open",
         sort,
         limit,
         offset,
@@ -1729,6 +1795,14 @@ export function registerTools(server, client) {
             "2026-07-02 — read the event's volume trend directly from it). " +
             "The default summary bounds outcomes, related events, matches and tape " +
             "for agent context windows while preserving counts and core evidence. " +
+            "Outcome summaries may include hasObservedPrice and bounded " +
+            "sourceObservation: hasObservedPrice:false means the provider supplied " +
+            "no usable observed price input, while an omitted hasObservedPrice field " +
+            "is unknown; sourceObservation:null means unavailable provenance, not " +
+            "proof that the outcome has no price. Neither field is a live, " +
+            "liquidity, or trading guarantee. " +
+            "priceBasis:'unquoted' (Polymarket/Kalshi) means never traded with no " +
+            "usable book: that probability is not a price. " +
             "Set detail=full only when the untouched provider-rich record is needed. " +
             "This is the cross-venue research view; for tradability use pm_quote. " +
             "No API key required.",
@@ -1837,7 +1911,7 @@ export function registerTools(server, client) {
                 .string()
                 .trim()
                 .regex(/^0x[0-9a-fA-F]{40}$/, "expected a 20-byte EVM wallet address")
-                .describe("Wallet address returned by pm_data_whale_wallets."),
+                .describe("Full walletAddress from pm_data_whales or pm_data_event, or address from pm_data_whale_wallets. The shortened wallet display is not an address."),
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Inspect one prediction-market whale wallet"),
@@ -1870,7 +1944,7 @@ export function registerTools(server, client) {
                 .min(1)
                 .max(25)
                 .optional()
-                .describe("Max clusters (1-25, default 10)."),
+                .describe("Max clusters (1-25, default 3)."),
             offset: z
                 .number()
                 .int()
@@ -1923,7 +1997,9 @@ export function registerTools(server, client) {
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Cross-venue disagreement clusters"),
     }, async ({ limit, offset, sort, minDivergence, sourceKind, status, maxSnapshotAgeMinutes, requirePriced, fiat, }) => present(mapSuccessfulBody(await client.getPublicPmMatches({
-        limit,
+        // 3 by default: the API's default of 10 returned about 239k
+        // characters, more than an assistant's context should take at once.
+        limit: limit ?? 3,
         offset,
         sort,
         minDivergence,
@@ -1958,9 +2034,16 @@ export function registerTools(server, client) {
             "venue's slug. Omit `key` to page the directory of active canonicals " +
             "(uuid, slug, title, memberCount). Pass `key` (a canonical's uuid OR " +
             "slug) for one canonical's full record: its venue members (each with " +
-            "orientation — same/inverted/unknown, NEVER price-inferred — plus " +
+            "orientation — same/flipped/unknown, NEVER price-inferred — plus " +
             "confidence and provenance basis) and an append-only judgment lineage " +
-            "(created/member_added/member_removed/merged, newest first). A MERGED " +
+            "(created/member_added/member_removed/merged, newest first). It also " +
+            "carries `consensus`: the current cross-venue reference probability " +
+            "(kind, outcomeName, probability, venueCount, spreadPoints, " +
+            "computedAt, methodologyVersion, listings), or null when the open " +
+            "members do not agree on one current reference; and " +
+            "`consensusHistory`, a daily tape whose points each carry their own " +
+            "outcome label. `listings` may be a subset of the contributing venues. " +
+            "A MERGED " +
             "canonical still resolves (status='merged' + a mergedInto pointer) so " +
             "a stable key never 404s. Use this to track one question across " +
             "venues by a durable identity instead of re-matching venue slugs " +
@@ -2012,8 +2095,9 @@ export function registerTools(server, client) {
             "biggest 24h price moves — top gainers or top losers, ordered by " +
             "24h change percent. Use this to DISCOVER candidates beyond your " +
             "watchlist (abnormal rapid moves), then deep-analyze each candidate " +
-            "with get_candles (OHLC + indicators) and get_market_context " +
-            "(sentiment, news) before any trade decision. Rows carry coinId, " +
+            "with get_candles (OHLC + indicators), get_market_context " +
+            "(sentiment, related markets) and get_news before any trade " +
+            "decision. Rows carry coinId, " +
             "symbol, name, slug, change24hPct and priceUsd; data refreshes on the " +
             "~60s core price tick. Pass the row's coinId straight to get_candles " +
             "/ get_market_context — do NOT re-resolve it from the symbol, since " +