@coinrithm/mcp-trading 0.2.0 → 0.4.0

package/dist/agent/types.d.ts

@@ -0,0 +1,286 @@
+import { IndicatorSet } from "./indicators.js";
+export declare const SPEC_VERSION = "coinrithm.agent.v1";
+export type Venue = "spot" | "futures" | "pm";
+export declare const VENUES: readonly Venue[];
+export declare const ACTION_TYPES: readonly ["futures_open", "futures_close", "futures_set_sltp", "spot_order", "spot_cancel", "pm_open"];
+export type ActionType = (typeof ACTION_TYPES)[number];
+export type ProviderName = "anthropic" | "openai" | "groq" | "nvidia" | "openai-compatible";
+export declare const PROVIDERS: readonly ProviderName[];
+export interface ModelConfig {
+    provider: ProviderName;
+    name: string;
+    baseUrl?: string;
+}
+export interface TriggerConfig {
+    cadence: string;
+    timezone?: string;
+}
+export interface RiskConfig {
+    maxLeverage: number;
+    perTradeMarginMusd: number;
+    maxConcurrentPositions: number;
+    requireStopLoss: boolean;
+    watchlist: string[];
+    blocklist?: string[];
+}
+export interface LimitsConfig {
+    maxTradesPerDay: number;
+    maxWritesPerCycle: number;
+    maxDailyLossMusd: number;
+    maxOpenMarginMusd: number;
+}
+export interface AbstentionConfig {
+    onStaleData: boolean;
+    onWeakSignal: boolean;
+    onMissingQuote: boolean;
+    onInsufficientBalance: boolean;
+    minConfidence: number;
+}
+export interface SyncConfig {
+    requirePollBeforeWrite: boolean;
+}
+export interface KillSwitchConfig {
+    maxDrawdownMusd: number;
+    maxConsecutiveRejects: number;
+    maxConsecutiveModelFailures: number;
+    onRateLimitPressure: boolean;
+}
+export declare const OBJECTIVE_PRIMARIES: readonly ["realized_pnl", "risk_adjusted", "drawdown_control", "calibration"];
+export type ObjectivePrimary = (typeof OBJECTIVE_PRIMARIES)[number];
+export interface ObjectiveConfig {
+    primary: ObjectivePrimary;
+    secondary: string[];
+    horizon?: string;
+}
+export declare const ALLOWED_CAPABILITIES: readonly ["websearch", "indicators"];
+export type Capability = (typeof ALLOWED_CAPABILITIES)[number];
+export interface AgentSpec {
+    name: string;
+    description: string;
+    spec: string;
+    trigger: TriggerConfig;
+    model?: ModelConfig;
+    venues: Venue[];
+    risk: RiskConfig;
+    limits: LimitsConfig;
+    abstention: AbstentionConfig;
+    sync: SyncConfig;
+    killSwitch: KillSwitchConfig;
+    objective?: ObjectiveConfig;
+    capabilities: Capability[];
+}
+export interface ParsedSkill {
+    spec: AgentSpec;
+    body: string;
+    raw: Record<string, unknown>;
+}
+export interface ValidationResult {
+    valid: boolean;
+    code?: string;
+    reason?: string;
+}
+export declare const ok: () => ValidationResult;
+export declare const fail: (code: string, reason: string) => ValidationResult;
+export interface Freshness {
+    status: string;
+    ageSeconds?: number;
+}
+export interface WatchEntry {
+    symbol: string;
+    coinId: string | null;
+    name?: string;
+    priceUsd?: number;
+    change1h?: number;
+    change24h?: number;
+    change7d?: number;
+    freshness?: Freshness;
+    indicators?: IndicatorSet;
+}
+export interface OpenPosition {
+    venue: Venue;
+    id: number;
+    coinId?: string;
+    symbol?: string;
+    side?: string;
+    status?: string;
+    marginMusd?: number;
+    unrealizedPnlMusd?: number;
+}
+export interface SpotOrder {
+    id: number;
+    coinId?: string;
+    symbol?: string;
+    side?: string;
+    orderType?: string;
+    quantity?: number;
+    status?: string;
+}
+export interface PmPosition {
+    id: number;
+    source?: string;
+    slug?: string;
+    outcomeExternalMarketId?: string;
+    stakeMusd?: number;
+    status?: string;
+}
+export interface PmMarket {
+    source: string;
+    slug: string;
+    outcomeExternalMarketId: string;
+    title?: string;
+    freshness?: Freshness;
+}
+export interface Observation {
+    asOf: string;
+    scopes: string[];
+    cashAvailableMusd: number | null;
+    equityMusd: number | null;
+    openPositions: OpenPosition[];
+    openOrders: SpotOrder[];
+    pmPositions: PmPosition[];
+    pmMarkets: PmMarket[];
+    watch: WatchEntry[];
+    syncCursor: string | null;
+    newClosedTrades: Array<Record<string, unknown>>;
+    polledBeforeWrite: boolean;
+}
+export type ProposedAction = {
+    type: "futures_open";
+    symbol: string;
+    side: "long" | "short";
+    leverage: number;
+    marginMusd: number;
+    stopLossPrice?: number | null;
+    takeProfitPrice?: number | null;
+    confidence?: number;
+    rationaleSummary?: string;
+} | {
+    type: "futures_close";
+    positionId: number;
+    fraction?: number;
+    confidence?: number;
+    rationaleSummary?: string;
+} | {
+    type: "futures_set_sltp";
+    positionId: number;
+    stopLossPrice?: number | null;
+    takeProfitPrice?: number | null;
+} | {
+    type: "spot_order";
+    symbol: string;
+    side: "buy" | "sell";
+    orderType: "market" | "limit" | "stop";
+    quantity: number;
+    limitPrice?: number;
+    stopPrice?: number;
+    confidence?: number;
+    rationaleSummary?: string;
+} | {
+    type: "spot_cancel";
+    orderId: number;
+} | {
+    type: "pm_open";
+    source: string;
+    slug: string;
+    outcomeExternalMarketId: string;
+    stakeMusd: number;
+    confidence?: number;
+    rationaleSummary?: string;
+};
+export type ActionVenue = Venue;
+export declare function actionVenue(a: ProposedAction): ActionVenue;
+export declare function isWriteAction(a: ProposedAction): boolean;
+export declare function isOpenAction(a: ProposedAction): a is Extract<ProposedAction, {
+    type: "futures_open" | "spot_order" | "pm_open";
+}>;
+export declare function spotBuyCost(action: Extract<ProposedAction, {
+    type: "spot_order";
+}>, quote?: QuoteEvidence): number | undefined;
+export interface Decision {
+    decision: "skip" | "act";
+    reason?: string;
+    confidence?: number;
+    actions: ProposedAction[];
+}
+export interface QuoteEvidence {
+    eligible: boolean;
+    blockReasons?: unknown;
+    entryPrice?: number;
+    liquidationPrice?: number;
+    executionPrice?: number;
+    estimatedCostMusd?: number;
+    freshness?: Freshness;
+}
+export interface RunState {
+    runId: string;
+    cyclesRun: number;
+    writesToday: number;
+    realizedPnlMusd: number;
+    peakRealizedMusd: number;
+    consecutiveRejectCycles: number;
+    consecutiveModelFailures: number;
+    rateLimitHits: number;
+    disabled: boolean;
+    disabledReason?: string;
+    dayKey: string;
+    cursor: string | null;
+    seen: string[];
+    realizedPnlTodayMusd: number;
+    consecutiveExecFailures: number;
+    intentSeq: Record<string, number>;
+}
+export interface AgentTrace {
+    runId?: string;
+    decisionId?: string;
+    strategyLabel?: string;
+    confidence?: number;
+    rationaleSummary?: string;
+}
+export interface ApiResult {
+    ok: boolean;
+    status: number;
+    data: unknown;
+    retryAfterSeconds?: number;
+    rateLimitRemaining?: number;
+    ledgerEventId?: string | null;
+}
+export interface PlannedAction {
+    action: ProposedAction;
+    accepted: boolean;
+    code?: string;
+    reason?: string;
+    quote?: QuoteEvidence;
+    executed?: boolean;
+    result?: unknown;
+}
+export interface CycleResult {
+    decision: "skip" | "act";
+    skipReason?: string;
+    planned: PlannedAction[];
+    modelFailed?: boolean;
+    disabled?: boolean;
+    disabledReason?: string;
+    live: boolean;
+}
+export interface ResolveIssue {
+    code: string;
+    message: string;
+    path?: string;
+}
+export interface Provenance {
+    sources: Record<string, string>;
+    mergeOrder: string[];
+    includeOrder: string[];
+}
+export interface ResolvedAgent {
+    inputPath: string;
+    isDirectory: boolean;
+    rawFrontmatter: Record<string, unknown>;
+    mergedProse: string;
+    proseParts: Array<{
+        source: string;
+        text: string;
+    }>;
+    provenance: Provenance;
+    contentHashes: Record<string, string>;
+}

package/dist/agent/types.js

@@ -7,10 +7,24 @@
 // money.
 export const SPEC_VERSION = "coinrithm.agent.v1";
 export const VENUES = ["spot", "futures", "pm"];
+// The runner's live action vocabulary — the capability set the drift guard
+// checks authored prose against. MUST mirror the ProposedAction union below and
+// the zod schema in decision.ts. A test ("ACTION_TYPES stays in lockstep with
+// the decision schema", capabilityGuard.test.ts) derives the literal set from
+// decision.ts's actionSchema and asserts equality, so the two cannot drift.
+export const ACTION_TYPES = [
+    "futures_open",
+    "futures_close",
+    "futures_set_sltp",
+    "spot_order",
+    "spot_cancel",
+    "pm_open",
+];
 export const PROVIDERS = [
     "anthropic",
     "openai",
     "groq",
+    "nvidia",
     "openai-compatible",
 ];
 // What the agent declares it is optimizing for — so two similar-looking agents
@@ -46,5 +60,29 @@ export function isWriteAction(a) {
     return true;
 }
 export function isOpenAction(a) {
-    return a.type === "futures_open" || a.type === "spot_order" || a.type === "pm_open";
+    return (a.type === "futures_open" || a.type === "spot_order" || a.type === "pm_open");
+}
+// Gross mUSD a spot BUY consumes. The validator (per-trade cap + balance gate)
+// and the runner (running-cash decrement) BOTH size with this one function so
+// they can never diverge. Sizing: limit -> limitPrice*qty, stop -> stopPrice*qty,
+// market -> the server-computed `estimatedCostMusd` (preferred) or
+// executionPrice*qty. Returns undefined when no price is available (e.g. an
+// unpriced market quote) so callers FAIL CLOSED instead of treating it as $0.
+export function spotBuyCost(action, quote) {
+    if (action.orderType === "limit") {
+        return typeof action.limitPrice === "number"
+            ? action.limitPrice * action.quantity
+            : undefined;
+    }
+    if (action.orderType === "stop") {
+        return typeof action.stopPrice === "number"
+            ? action.stopPrice * action.quantity
+            : undefined;
+    }
+    // market: prefer the server's gross notional, else derive from the fill price.
+    if (typeof quote?.estimatedCostMusd === "number")
+        return quote.estimatedCostMusd;
+    return typeof quote?.executionPrice === "number"
+        ? quote.executionPrice * action.quantity
+        : undefined;
 }

package/dist/agent/util.d.ts

@@ -0,0 +1,13 @@
+export declare const sleep: (ms: number) => Promise<void>;
+export declare function parseCadenceMs(cadence: unknown): number | null;
+export declare function dayKey(d?: Date): string;
+export declare function envFlag(value: string | undefined): boolean;
+export declare function scanForSecrets(value: unknown, pathPrefix?: string, findings?: string[]): string[];
+export declare function shortId(): string;
+export declare function normalizeContent(text: string): string;
+export declare function sha256(text: string): string;
+export declare function toPosix(p: string): string;
+export declare function isPathInside(parent: string, child: string): boolean;
+export declare function boundTail(text: string, maxLines: number, maxBytes: number): string;
+export declare function stableStringify(value: unknown): string;
+export declare function sortDeep(value: unknown): unknown;

package/dist/agent/util.js

@@ -21,6 +21,10 @@ export function parseCadenceMs(cadence) {
 export function dayKey(d = new Date()) {
     return d.toISOString().slice(0, 10);
 }
+// Truthy reading of an opt-in env flag (1/true/yes/on, case-insensitive).
+export function envFlag(value) {
+    return ["1", "true", "yes", "on"].includes((value ?? "").trim().toLowerCase());
+}
 // Deep-scan a parsed frontmatter object for anything that looks like a secret.
 // The skill file is meant to be committable and shareable; a real key must
 // NEVER live in it (keys are supplied at runtime via env / encrypted store).

package/dist/agent/version.d.ts

@@ -0,0 +1,11 @@
+export declare const RUNNER_VERSION = "0.1.0";
+export declare const RESOLVER_VERSION = "1";
+export declare const MANIFEST_SCHEMA = "coinrithm.manifest.v1";
+export declare const COINRITHM_API: {
+    readonly kind: "coinrithm-agent-api";
+    readonly baseUrl: "https://api.coinrithm.com";
+    readonly mcpUrl: "https://mcp.coinrithm.com/mcp";
+    readonly openapiVersion: "1.4.0";
+    readonly mcpPackage: "@coinrithm/mcp-trading";
+    readonly mcpVersion: "0.3.0";
+};

package/dist/agent/version.js

@@ -12,5 +12,5 @@ export const COINRITHM_API = {
     mcpUrl: "https://mcp.coinrithm.com/mcp",
     openapiVersion: "1.4.0",
     mcpPackage: "@coinrithm/mcp-trading",
-    mcpVersion: "0.1.8",
+    mcpVersion: "0.3.0",
 };

package/dist/client.d.ts

@@ -0,0 +1,162 @@
+export declare const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+export declare function log(...args: unknown[]): void;
+export interface ClientConfig {
+    apiKey?: string;
+    baseUrl: string;
+}
+export interface AgentTrace {
+    runId?: string;
+    decisionId?: string;
+    strategyLabel?: string;
+    confidence?: number;
+    rationaleSummary?: string;
+}
+export declare function loadConfig(): ClientConfig;
+export declare function loadHttpConfig(): ClientConfig;
+export declare function bearerFromHeader(value: string | string[] | undefined): string | undefined;
+export interface ApiResult {
+    ok: boolean;
+    status: number;
+    ledgerEventId?: string | null;
+    ledgerStatus?: string | null;
+    data: unknown;
+}
+type TraceableBody<T extends Record<string, unknown>> = T & {
+    agentTrace?: AgentTrace;
+};
+export declare class CoinRithmClient {
+    private readonly defaultApiKey?;
+    private readonly baseUrl;
+    constructor(config: ClientConfig);
+    private request;
+    whoami(apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getPortfolio(query?: {
+        fiat?: string;
+        locale?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getWallet(query?: {
+        coinId?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    resolveSymbol(query: {
+        q: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getEquityCurve(query?: {
+        days?: number;
+        granularity?: "daily" | "realized";
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getMyTrades(query?: {
+        venue?: string;
+        limit?: number;
+        updatedSince?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getMarketContext(coinId: string, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getCandles(coinId: string, query?: {
+        range?: "1H" | "1D" | "1W" | "1M" | "3M";
+        fiat?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    discoverPmMarkets(query?: {
+        q?: string;
+        source?: "all" | "kalshi" | "polymarket";
+        limit?: number;
+        offset?: number;
+        sort?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getPerformance(apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getLedger(query?: {
+        venue?: string;
+        eventType?: string;
+        runId?: string;
+        decisionId?: string;
+        status?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    exportLedger(query?: {
+        venue?: string;
+        eventType?: string;
+        runId?: string;
+        decisionId?: string;
+        status?: string;
+        from?: string;
+        to?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getArenaLeaderboard(query?: {
+        page?: number;
+        pageSize?: number;
+        window?: "7d" | "30d" | "all";
+    }, apiKey?: string): Promise<ApiResult>;
+    getArenaAgent(handle: string, apiKey?: string): Promise<ApiResult>;
+    listOpenOrders(query?: {
+        coinId?: string;
+        limit?: number;
+        updatedSince?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getFuturesPositions(query?: {
+        updatedSince?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    getPmPositions(query?: {
+        updatedSince?: string;
+    }, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    futuresQuote(body: {
+        coinId: string;
+        side: string;
+        leverage: number;
+        marginMusd: number;
+    } & {
+        agentTrace?: AgentTrace;
+    }, apiKey?: string): Promise<ApiResult>;
+    pmQuote(body: {
+        source: string;
+        slug: string;
+        outcomeExternalMarketId: string;
+        stakeMusd: number;
+    } & {
+        agentTrace?: AgentTrace;
+    }, apiKey?: string): Promise<ApiResult>;
+    spotQuote(body: {
+        coinId: string;
+        side: string;
+        quantity: number;
+    } & {
+        agentTrace?: AgentTrace;
+    }, apiKey?: string): Promise<ApiResult>;
+    placeSpotOrder(body: TraceableBody<{
+        coinId: string;
+        side: string;
+        orderType: string;
+        quantity: number;
+        limitPrice?: number;
+        stopPrice?: number;
+        idempotencyKey: string;
+    }>, apiKey?: string): Promise<ApiResult>;
+    cancelSpotOrder(orderId: number, apiKey?: string, agentTrace?: AgentTrace): Promise<ApiResult>;
+    openFuturesPosition(body: TraceableBody<{
+        coinId: string;
+        side: string;
+        leverage: number;
+        marginMusd: number;
+        idempotencyKey: string;
+        stopLossPrice?: number | null;
+        takeProfitPrice?: number | null;
+    }>, apiKey?: string): Promise<ApiResult>;
+    setFuturesSlTp(body: TraceableBody<{
+        positionId: number;
+        stopLossPrice?: number | null;
+        takeProfitPrice?: number | null;
+    }>, apiKey?: string): Promise<ApiResult>;
+    closeFuturesPosition(body: TraceableBody<{
+        positionId: number;
+        fraction?: number;
+        idempotencyKey: string;
+    }>, apiKey?: string): Promise<ApiResult>;
+    openPmPosition(body: TraceableBody<{
+        source: string;
+        slug: string;
+        outcomeExternalMarketId: string;
+        stakeMusd: number;
+        idempotencyKey: string;
+    }>, apiKey?: string): Promise<ApiResult>;
+}
+export {};

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CoinRithmClient } from "./client.js";
+export declare function registerTools(server: McpServer, client: CoinRithmClient): void;

package/dist/version.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "CoinRithm paper-trading toolkit: an MCP server (coinrithm-mcp) AND a self-host agent runner (coinrithm-agent) for spot, futures, and prediction markets with a user-minted API key.",
   "type": "module",
@@ -24,7 +24,8 @@
   "main": "dist/index.js",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -53,7 +54,11 @@
     "kalshi",
     "claude",
     "chatgpt",
+    "gemini",
     "cursor",
+    "open-knowledge-format",
+    "okf",
+    "model-agnostic",
     "leaderboard",
     "coinrithm"
   ],