@coinrithm/mcp-trading 0.7.15 → 0.7.17

package/dist/agent/universe.d.ts

@@ -0,0 +1,78 @@
+import type { UniverseConfig } from "./types.js";
+export declare const UNIVERSE_SORTS: readonly ["gainers_24h", "losers_24h", "abs_change_24h", "abs_change_1h", "volume_24h", "rank"];
+export type UniverseSort = (typeof UNIVERSE_SORTS)[number];
+export declare const UNIVERSE_DEFAULTS: {
+    rankMin: number;
+    rankMax: number;
+    minVolume24hUsd: number;
+    sort: UniverseSort;
+    resolveTop: number;
+    scanLimit: number;
+};
+export declare const UNIVERSE_MAX_RESOLVE_TOP = 10;
+export declare const UNIVERSE_MAX_SCAN_LIMIT = 50;
+/** True when the agent discovers candidates beyond its watchlist. */
+export declare function scansUniverse(spec: {
+    capabilities: readonly string[];
+    universe?: UniverseConfig;
+}): boolean;
+export interface UniverseQuery {
+    rankMin: number;
+    rankMax: number;
+    minVolume24hUsd: number;
+    excludeStablecoins: boolean;
+    includeSectors: string[];
+    excludeSectors: string[];
+    sort: UniverseSort;
+    limit: number;
+}
+/** The screener query a validated universe block asks for. */
+export declare function universeQuery(u: UniverseConfig): UniverseQuery;
+/** How many screener rows become full watch entries this cycle. */
+export declare function universeResolveTop(u: UniverseConfig): number;
+/** Wire form: csv sectors, string numbers; empty filters are omitted. With
+ * `ucids`, the same boundaries are applied to just those coins (membership). */
+export declare function universeQueryParams(q: UniverseQuery, ucids?: readonly string[]): Record<string, string | number>;
+export interface UniverseRow {
+    symbol: string;
+    coinId?: string;
+    name?: string;
+    slug?: string;
+    marketCapRank?: number;
+    priceUsd?: number;
+    change1h?: number;
+    change24h?: number;
+    change7d?: number;
+    volume24hUsd?: number;
+    sectors?: string[];
+}
+/** Keep malformed evidence unknown; dropping bad elements can widen a screen. */
+export declare function universeSectorsOf(raw: unknown): string[] | 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 declare function filterUniverseRows(rows: UniverseRow[], q: UniverseQuery): UniverseRow[];
+/**
+ * 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 declare function universeEntryBlock(spec: {
+    universe?: UniverseConfig;
+}, entry: {
+    discovered?: boolean;
+    withinBoundaries?: boolean;
+}): string | null;
+/** Validation issues for a raw `universe` block ([] when valid or absent). */
+export declare function universeIssues(raw: unknown): Array<[string, string]>;
+/** One line for the prompt: the boundaries in plain words. */
+export declare function describeUniverse(u: UniverseConfig): string;

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/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.7.0";
+    readonly openapiVersion: "1.8.0";
     readonly mcpPackage: "@coinrithm/mcp-trading";
     readonly mcpVersion: string;
 };

package/dist/agent/version.js

@@ -20,7 +20,7 @@ export const COINRITHM_API = {
     mcpUrl: "https://mcp.coinrithm.com/mcp",
     // 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.7.0",
+    openapiVersion: "1.8.0",
     mcpPackage: "@coinrithm/mcp-trading",
     mcpVersion: PACKAGE_VERSION,
 };

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { type PmPaperOpen, type PmPaperClose } from "./pmPaperV2.js";
 export declare const DEFAULT_BASE_URL = "https://api.coinrithm.com";
 export declare function log(...args: unknown[]): void;
 export interface ClientConfig {
@@ -110,6 +111,7 @@ export declare class CoinRithmClient {
         updatedSince?: string;
     }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
     getMarketContext(coinId: string, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getSpotReference(coinId: string, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
     getCandles(coinId: string, query?: {
         range?: "1H" | "1D" | "1W" | "1M" | "3M";
         fiat?: string;
@@ -120,6 +122,10 @@ export declare class CoinRithmClient {
         hours?: number;
         minImportance?: number;
     }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    discoverPmPaperV2(query?: {
+        q?: string;
+        limit?: number;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
     discoverPmMarkets(query?: {
         q?: string;
         source?: "all" | "kalshi" | "polymarket";
@@ -221,6 +227,14 @@ export declare class CoinRithmClient {
         fraction?: number;
         idempotencyKey: string;
     }>, apiKey?: string): Promise<ApiResult>;
+    openPmPaperV2(body: PmPaperOpen, apiKey?: string): Promise<ApiResult>;
+    replayPmPaperV2Open(body: PmPaperOpen, apiKey?: string): Promise<ApiResult>;
+    closePmPaperV2(body: PmPaperClose, apiKey?: string): Promise<ApiResult>;
+    pmPaperV2Positions(apiKey?: string, query?: {
+        status?: "open";
+        beforeId?: number;
+        limit?: number;
+    }): Promise<ApiResult>;
     openPmPosition(body: TraceableBody<{
         source: string;
         slug: string;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { PM_PAPER_V2_BASE, } from "./pmPaperV2.js";
 // Thin HTTP client for the CoinRithm agent surface (/api/agent/*).
 //
 // Auth: a user-minted API key (crk_live_…) passed as `Authorization: Bearer …`.
@@ -30,7 +31,7 @@ function resolveBaseUrl() {
 export function loadConfig() {
     const apiKey = process.env.COINRITHM_API_KEY?.trim();
     if (!apiKey) {
-        throw new Error("COINRITHM_API_KEY is not set. Mint a key in CoinRithm → Profile → API Keys " +
+        throw new Error("COINRITHM_API_KEY is not set. Mint a key in CoinRithm → Settings → API Keys " +
             "and expose it to this MCP server as the COINRITHM_API_KEY environment variable.");
     }
     if (!apiKey.startsWith("crk_live_")) {
@@ -339,6 +340,9 @@ export class CoinRithmClient {
     getMarketContext(coinId, apiKey, agentTrace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { apiKey, agentTrace });
     }
+    getSpotReference(coinId, apiKey, agentTrace) {
+        return this.request("GET", `/api/agent/spot/reference/${encodeURIComponent(coinId)}`, { apiKey, agentTrace });
+    }
     getCandles(coinId, query, apiKey, agentTrace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}/candles`, { query, apiKey, agentTrace });
     }
@@ -349,6 +353,13 @@ export class CoinRithmClient {
             agentTrace,
         });
     }
+    discoverPmPaperV2(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/pm/v2/discover", {
+            query,
+            apiKey,
+            agentTrace,
+        });
+    }
     discoverPmMarkets(query, apiKey, agentTrace) {
         return this.request("GET", "/api/agent/pm/discover", {
             query,
@@ -435,6 +446,25 @@ export class CoinRithmClient {
     closeFuturesPosition(body, apiKey) {
         return this.request("POST", "/api/agent/futures/close", { body, apiKey });
     }
+    // Explicit opt-in contract; API derives and authorizes the configured house tuple.
+    openPmPaperV2(body, apiKey) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/open`, { body, apiKey });
+    }
+    replayPmPaperV2Open(body, apiKey) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/open/replay`, {
+            body,
+            apiKey,
+        });
+    }
+    closePmPaperV2(body, apiKey) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/close`, { body, apiKey });
+    }
+    pmPaperV2Positions(apiKey, query) {
+        return this.request("GET", `${PM_PAPER_V2_BASE}/positions`, {
+            apiKey,
+            query,
+        });
+    }
     openPmPosition(body, apiKey) {
         return this.request("POST", "/api/agent/pm/open", { body, apiKey });
     }

package/dist/http.js

@@ -75,7 +75,7 @@ export function createHttpApp(client, options = {}) {
         res.json({
             service: "CoinRithm MCP",
             version: SERVER_VERSION,
-            description: "Model Context Protocol server for CoinRithm: keyless public prediction-market data tools (pm_data_*) plus paper-trading tools (spot, futures, prediction markets) with a crk_live_ API key. Paper only — never real money.",
+            description: "Model Context Protocol server for CoinRithm: keyless prediction-market data tools across 12 venues (pm_data_*), keyless crypto movers and Agent Arena reads, plus crypto market context and paper-trading tools (spot, futures, prediction markets) with a crk_live_ API key. Opt-in PM paper v2 and spot reference tools are off unless the server enables them. Paper only, never real money.",
             endpoint: {
                 url: "https://mcp.coinrithm.com/mcp",
                 method: "POST",

package/dist/pmPaperV2.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export declare const pmPaperOpenSchema: z.ZodObject<{
+    source: z.ZodEnum<["kalshi", "polymarket"]>;
+    slug: z.ZodString;
+    outcomeExternalMarketId: z.ZodString;
+    side: z.ZodEnum<["yes", "no"]>;
+    maxCashBudget: z.ZodEffects<z.ZodString, string, string>;
+    idempotencyKey: z.ZodString;
+    minEntryProbabilityPct: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+    forecastProbability: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+    thesis: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+}, "strict", z.ZodTypeAny, {
+    source: "kalshi" | "polymarket";
+    slug: string;
+    outcomeExternalMarketId: string;
+    side: "yes" | "no";
+    maxCashBudget: string;
+    idempotencyKey: string;
+    minEntryProbabilityPct?: string | null | undefined;
+    forecastProbability?: string | null | undefined;
+    thesis?: string | null | undefined;
+}, {
+    source: "kalshi" | "polymarket";
+    slug: string;
+    outcomeExternalMarketId: string;
+    side: "yes" | "no";
+    maxCashBudget: string;
+    idempotencyKey: string;
+    minEntryProbabilityPct?: string | null | undefined;
+    forecastProbability?: string | null | undefined;
+    thesis?: string | null | undefined;
+}>;
+export declare const pmPaperCloseSchema: z.ZodObject<{
+    positionId: z.ZodNumber;
+    idempotencyKey: z.ZodString;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+}, "strict", z.ZodTypeAny, {
+    idempotencyKey: string;
+    positionId: number;
+    detail?: string | null | undefined;
+}, {
+    idempotencyKey: string;
+    positionId: number;
+    detail?: string | null | undefined;
+}>;
+export declare const pmForecastProbabilitySchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+export declare const pmPaperAgentOpenSchema: z.ZodObject<{
+    source: z.ZodEnum<["kalshi", "polymarket"]>;
+    slug: z.ZodString;
+    outcomeExternalMarketId: z.ZodString;
+    side: z.ZodEnum<["yes", "no"]>;
+    maxCashBudget: z.ZodEffects<z.ZodString, string, string>;
+    idempotencyKey: z.ZodString;
+    minEntryProbabilityPct: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+    thesis: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+} & {
+    forecastProbability: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+}, "strict", z.ZodTypeAny, {
+    source: "kalshi" | "polymarket";
+    slug: string;
+    outcomeExternalMarketId: string;
+    side: "yes" | "no";
+    maxCashBudget: string;
+    idempotencyKey: string;
+    forecastProbability: string;
+    minEntryProbabilityPct?: string | null | undefined;
+    thesis?: string | null | undefined;
+}, {
+    source: "kalshi" | "polymarket";
+    slug: string;
+    outcomeExternalMarketId: string;
+    side: "yes" | "no";
+    maxCashBudget: string;
+    idempotencyKey: string;
+    forecastProbability: string;
+    minEntryProbabilityPct?: string | null | undefined;
+    thesis?: string | null | undefined;
+}>;
+export type PmPaperOpen = z.infer<typeof pmPaperOpenSchema>;
+export type PmPaperClose = z.infer<typeof pmPaperCloseSchema>;
+export declare const PM_PAPER_V2_BASE = "/api/agent/pm/v2";

package/dist/pmPaperV2.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+// Exact decimal wire values; never derive a fee-inclusive budget from stakeMusd.
+const decimal = z
+    .string()
+    .max(40)
+    .regex(/^(0|[1-9]\d*)(\.\d{1,18})?$/);
+const boundedDecimal = (min, max, exclusive = false) => decimal.refine((value) => {
+    if (!/^(0|[1-9]\d*)(\.\d{1,18})?$/.test(value) || value.length > 40)
+        return false;
+    const [whole, fraction = ""] = value.split(".");
+    const scaled = BigInt(whole) * 10n ** 18n + BigInt(fraction.padEnd(18, "0"));
+    const lower = BigInt(min) * 10n ** 18n, upper = BigInt(max) * 10n ** 18n;
+    return exclusive
+        ? scaled > lower && scaled < upper
+        : scaled >= lower && scaled <= upper;
+});
+const text = (max) => z
+    .string()
+    .max(max)
+    .refine((value) => [...value].every((char) => char.charCodeAt(0) >= 32 && char.charCodeAt(0) !== 127));
+export const pmPaperOpenSchema = z
+    .object({
+    source: z.enum(["kalshi", "polymarket"]),
+    slug: z.string().min(1).max(256),
+    outcomeExternalMarketId: z.string().min(1).max(256),
+    side: z.enum(["yes", "no"]),
+    maxCashBudget: boundedDecimal(10, 1000000).describe("Exact decimal string: maximum total paper cash including entry fees; 10..1000000 mUSD."),
+    idempotencyKey: z.string().regex(/^pm-entry:[A-Za-z0-9:_-]{1,111}$/),
+    minEntryProbabilityPct: boundedDecimal(0, 100).nullable().optional(),
+    forecastProbability: boundedDecimal(0, 100, true).nullable().optional(),
+    thesis: text(280).nullable().optional(),
+})
+    .strict();
+export const pmPaperCloseSchema = z
+    .object({
+    positionId: z.number().int().positive().max(2147483647),
+    idempotencyKey: z.string().regex(/^pm-exit:[A-Za-z0-9:_-]{1,111}$/),
+    detail: text(1024).nullable().optional(),
+})
+    .strict();
+// Matches backend-v2 normalizePmPaperEntryRequest (acbf1cc): the chance that
+// the BOUGHT side pays out. Below 1 is read as a fraction (x100), above 1 as a
+// percent; exactly 1 is ambiguous and refused; 0 and 100 are refused.
+const exactlyOne = /^1(\.0{1,18})?$/;
+export const pmForecastProbabilitySchema = boundedDecimal(0, 100, true)
+    .refine((value) => !exactlyOne.test(value))
+    .describe("Required exact decimal string: chance that the side you buy pays out. Percent above 1 and below 100 (e.g. 62.5), or a fraction above 0 and below 1 (0.625 = 62.5%); exactly 1 is refused.");
+// API-key opens: the API answers 422 forecast_required without a forecast.
+// The base schema above stays optional so stored legacy requests can replay.
+export const pmPaperAgentOpenSchema = pmPaperOpenSchema
+    .extend({ forecastProbability: pmForecastProbabilitySchema })
+    .strict();
+export const PM_PAPER_V2_BASE = "/api/agent/pm/v2";