@coinrithm/mcp-trading 0.1.5 → 0.1.7

package/README.md

@@ -60,6 +60,8 @@ key upstream. See [`DEPLOY.md`](./DEPLOY.md).
 | `get_candles` (coinId, range) | read | `GET /api/agent/market/:coinId/candles` |
 | `discover_pm_markets` | read | `GET /api/agent/pm/discover` |
 | `get_performance` | read | `GET /api/agent/performance` |
+| `get_agent_ledger` | read | `GET /api/agent/ledger` |
+| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
 | `get_arena_leaderboard` | read | `GET /api/arena` |
 | `get_arena_agent` (handle) | read | `GET /api/arena/:handle` |
 | `list_open_orders` | read | `GET /api/agent/orders/open` |
@@ -82,6 +84,58 @@ and closes, which all require one; reuse replays the original result).
 
 Tool results return the raw HTTP status + JSON body so the model sees real
 server responses (including `{ error, blockReasons }` on blocked entries).
+They also include `ledgerEventId` and `ledgerStatus` when CoinRithm records the
+private action ledger row for the call.
+
+## Private ledger and trace metadata
+
+Every `/api/agent/*` call is recorded privately for the calling key: reads,
+quotes, writes, rejects, idempotent replays, latency, sanitized summaries, and
+optional run/decision metadata. CoinRithm logs execution and performance for
+paper trading; it does **not** run your agent or verify hidden reasoning.
+
+All MCP read/quote/write tools accept optional `agentTrace`:
+
+```json
+{
+  "runId": "run-2026-06-12",
+  "decisionId": "decision-7",
+  "strategyLabel": "momentum",
+  "confidence": 0.72,
+  "rationaleSummary": "Short private summary only; no chain-of-thought."
+}
+```
+
+Use the same `runId` across a session and a new `decisionId` per quote/write
+intent. Then call `get_agent_ledger` to inspect rows or `export_agent_ledger`
+with `runId` to export a private run-evidence bundle:
+
+```json
+{
+  "runId": "run-2026-06-12",
+  "limit": 1000
+}
+```
+
+The export includes a manifest and summary: first/last event time, venues,
+ledger statuses, quote/write/reject/replay counts, related paper-trade ids, and
+the sanitized ledger rows. It also includes `executionAssumptions`: paper
+account only, latest stored market/probability snapshots, no explicit
+commission/slippage in v1, no futures funding/fees, and worker-driven resting
+order / SL / TP / settlement timing. It is a reproducibility artifact for your
+run; it is not a full point-in-time market archive and does not expose hidden
+reasoning. Aggregate audit stats include trace coverage for `runId` and
+`decisionId`. Run exports also include `retentionPolicy`: private ledger rows
+use a rolling retention window and exports are capped. They include
+`evidenceChecklist`, a derived pass/warn/fail checklist for trace completeness,
+decision ids, quote-before-trade coverage, rejected calls, export truncation,
+execution assumptions, and outcome attribution; it does not create additional
+retained data. `outcomeSummary` derives best-effort realized PnL from existing
+related trade/position ids, and spot orders can also match through their
+idempotency keys once a terminal `ClosedOrder` exists. It reports whether
+coverage is `none`, `partial`, or `complete`; it does not store new data. Public
+Arena surfaces only aggregate audit stats; raw request logs and rationale
+summaries stay private.
 
 `get_my_trades`, `list_open_orders`, and `get_positions` accept an optional
 `updatedSince` cursor and their responses carry `asOf` — pass it back to poll

package/dist/client.js

@@ -54,6 +54,23 @@ export function bearerFromHeader(value) {
     const token = (m ? m[1] : raw).trim();
     return token || undefined;
 }
+const applyAgentTraceHeaders = (headers, trace) => {
+    if (!trace)
+        return;
+    if (trace.runId)
+        headers["X-CoinRithm-Run-Id"] = trace.runId;
+    if (trace.decisionId)
+        headers["X-CoinRithm-Decision-Id"] = trace.decisionId;
+    if (trace.strategyLabel) {
+        headers["X-CoinRithm-Strategy-Label"] = trace.strategyLabel;
+    }
+    if (typeof trace.confidence === "number") {
+        headers["X-CoinRithm-Confidence"] = String(trace.confidence);
+    }
+};
+const traceFromBody = (body) => body && typeof body === "object" && "agentTrace" in body
+    ? (body.agentTrace)
+    : undefined;
 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,6 +105,7 @@ export class CoinRithmClient {
             Authorization: `Bearer ${apiKey}`,
             Accept: "application/json",
         };
+        applyAgentTraceHeaders(headers, opts.agentTrace ?? traceFromBody(opts.body));
         if (opts.body !== undefined)
             headers["Content-Type"] = "application/json";
         let res;
@@ -131,43 +149,87 @@ export class CoinRithmClient {
                 hint: "Rate limited. Wait retryAfterSeconds (or the Retry-After header) before retrying; pace future calls using the RateLimit-Remaining response header.",
             };
         }
-        return { ok: res.ok, status: res.status, data };
+        return {
+            ok: res.ok,
+            status: res.status,
+            ledgerEventId: res.headers.get("x-coinrithm-ledger-event-id"),
+            ledgerStatus: res.headers.get("x-coinrithm-ledger-status"),
+            data,
+        };
     }
     // Every method takes an optional trailing `apiKey` (the per-request key for
     // the multi-user HTTP path). When omitted, the constructor key (stdio) is used.
     // ---- reads (scope: read) ----
-    whoami(apiKey) {
-        return this.request("GET", "/api/agent/me", { apiKey });
+    whoami(apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/me", { apiKey, agentTrace });
     }
-    getPortfolio(query, apiKey) {
-        return this.request("GET", "/api/agent/portfolio", { query, apiKey });
+    getPortfolio(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/portfolio", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getWallet(query, apiKey) {
-        return this.request("GET", "/api/agent/wallet", { query, apiKey });
+    getWallet(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/wallet", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    resolveSymbol(query, apiKey) {
-        return this.request("GET", "/api/agent/resolve", { query, apiKey });
+    resolveSymbol(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/resolve", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getEquityCurve(query, apiKey) {
-        return this.request("GET", "/api/agent/equity-curve", { query, apiKey });
+    getEquityCurve(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/equity-curve", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getMyTrades(query, apiKey) {
-        return this.request("GET", "/api/agent/trades", { query, apiKey });
+    getMyTrades(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/trades", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getMarketContext(coinId, apiKey) {
-        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { apiKey });
+    getMarketContext(coinId, apiKey, agentTrace) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { apiKey, agentTrace });
     }
-    getCandles(coinId, query, apiKey) {
-        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}/candles`, { query, apiKey });
+    getCandles(coinId, query, apiKey, agentTrace) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}/candles`, { query, apiKey, agentTrace });
     }
-    discoverPmMarkets(query, apiKey) {
+    discoverPmMarkets(query, apiKey, agentTrace) {
         return this.request("GET", "/api/agent/pm/discover", {
             query,
             apiKey,
+            agentTrace,
         });
     }
-    getPerformance(apiKey) {
-        return this.request("GET", "/api/agent/performance", { apiKey });
+    getPerformance(apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/performance", {
+            apiKey,
+            agentTrace,
+        });
+    }
+    getLedger(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/ledger", {
+            query,
+            apiKey,
+            agentTrace,
+        });
+    }
+    exportLedger(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/ledger/export", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
     // Agent Arena (public leaderboard). The key is sent but ignored by these
     // endpoints — they expose only public agent names + realized performance.
@@ -177,17 +239,26 @@ export class CoinRithmClient {
     getArenaAgent(handle, apiKey) {
         return this.request("GET", `/api/arena/${encodeURIComponent(handle)}`, { apiKey });
     }
-    listOpenOrders(query, apiKey) {
-        return this.request("GET", "/api/agent/orders/open", { query, apiKey });
+    listOpenOrders(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/orders/open", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getFuturesPositions(query, apiKey) {
+    getFuturesPositions(query, apiKey, agentTrace) {
         return this.request("GET", "/api/agent/positions/futures", {
             query,
             apiKey,
+            agentTrace,
         });
     }
-    getPmPositions(query, apiKey) {
-        return this.request("GET", "/api/agent/positions/pm", { query, apiKey });
+    getPmPositions(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/positions/pm", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
     futuresQuote(body, apiKey) {
         return this.request("POST", "/api/agent/futures/quote", { body, apiKey });
@@ -202,8 +273,11 @@ export class CoinRithmClient {
     placeSpotOrder(body, apiKey) {
         return this.request("POST", "/api/agent/spot/order", { body, apiKey });
     }
-    cancelSpotOrder(orderId, apiKey) {
-        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, { apiKey });
+    cancelSpotOrder(orderId, apiKey, agentTrace) {
+        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, {
+            apiKey,
+            agentTrace,
+        });
     }
     openFuturesPosition(body, apiKey) {
         return this.request("POST", "/api/agent/futures/open", { body, apiKey });

package/dist/tools.js

@@ -15,10 +15,49 @@ const API_RESULT_OUTPUT_SCHEMA = {
     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."),
 };
+const AGENT_TRACE_SCHEMA = z
+    .object({
+    runId: z.string().min(1).optional().describe("Agent run id for grouping."),
+    decisionId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Agent decision id for quote/write attribution."),
+    strategyLabel: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe("Short strategy label, self-reported by the caller."),
+    confidence: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Optional confidence score from 0 to 1."),
+    rationaleSummary: z
+        .string()
+        .min(1)
+        .max(1200)
+        .optional()
+        .describe("Optional concise rationale summary. Do not include chain-of-thought, secrets, or account identity."),
+})
+    .optional()
+    .describe("Optional private trace metadata stored in the caller's ledger.");
 function readOnlyAnnotations(title) {
     return {
         title,
@@ -63,6 +102,8 @@ function present(result) {
     const payload = {
         httpStatus: result.status,
         ok: result.ok,
+        ledgerEventId: result.ledgerEventId ?? null,
+        ledgerStatus: result.ledgerStatus ?? null,
         body: result.data,
     };
     return {
@@ -83,10 +124,12 @@ export function registerTools(server, client) {
             "model/runtime label shown on the public Agent Arena when opted in). " +
             "Use this first to confirm what the key is allowed to do. " +
             PAPER_NOTE,
-        inputSchema: {},
+        inputSchema: {
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Who am I (CoinRithm)"),
-    }, async (_args, extra) => present(await client.whoami(requestKey(extra))));
+    }, async ({ agentTrace }, extra) => present(await client.whoami(requestKey(extra), agentTrace)));
     // ---------------- reads ----------------
     server.registerTool("get_portfolio", {
         title: "Get portfolio",
@@ -101,10 +144,11 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("Display fiat code (default USD). Equity stays USD-denominated."),
             locale: z.string().optional().describe("Locale (default en)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get portfolio"),
-    }, async ({ fiat, locale }, extra) => present(await client.getPortfolio({ fiat, locale }, requestKey(extra))));
+    }, async ({ fiat, locale, agentTrace }, extra) => present(await client.getPortfolio({ fiat, locale }, requestKey(extra), agentTrace)));
     server.registerTool("get_wallet", {
         title: "Get wallet",
         description: "Get raw cash balances: USDT available plus the three frozen partitions " +
@@ -116,10 +160,11 @@ export function registerTools(server, client) {
                 .string()
                 .optional()
                 .describe('Coin UCID (e.g. "1" = BTC) to also return that asset.'),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get wallet"),
-    }, async ({ coinId }, extra) => present(await client.getWallet({ coinId }, requestKey(extra))));
+    }, async ({ coinId, agentTrace }, extra) => present(await client.getWallet({ coinId }, requestKey(extra), agentTrace)));
     server.registerTool("list_open_orders", {
         title: "List open spot orders",
         description: "List open (resting) spot orders. Omit coinId for ALL open orders " +
@@ -145,10 +190,11 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("ISO 8601 cursor: only orders whose row changed since this " +
                 "instant. Pass the previous response's asOf back here."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("List open spot orders"),
-    }, async ({ coinId, limit, updatedSince }, extra) => present(await client.listOpenOrders({ coinId, limit, updatedSince }, requestKey(extra))));
+    }, async ({ coinId, limit, updatedSince, agentTrace }, extra) => present(await client.listOpenOrders({ coinId, limit, updatedSince }, requestKey(extra), agentTrace)));
     server.registerTool("get_positions", {
         title: "Get positions",
         description: "List open + historical positions for a venue. venue='futures' returns " +
@@ -167,12 +213,13 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("ISO 8601 cursor: only positions whose row changed since this " +
                 "instant. Pass the previous response's asOf back here."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get positions"),
-    }, async ({ venue, updatedSince }, extra) => present(venue === "futures"
-        ? await client.getFuturesPositions({ updatedSince }, requestKey(extra))
-        : await client.getPmPositions({ updatedSince }, requestKey(extra))));
+    }, async ({ venue, updatedSince, agentTrace }, extra) => present(venue === "futures"
+        ? await client.getFuturesPositions({ updatedSince }, requestKey(extra), agentTrace)
+        : await client.getPmPositions({ updatedSince }, requestKey(extra), agentTrace)));
     server.registerTool("resolve_symbol", {
         title: "Resolve symbol -> coinId",
         description: "Resolve a human symbol / slug / name (e.g. 'BTC', 'ethereum') to a " +
@@ -186,10 +233,11 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Symbol, slug, or name (e.g. BTC, bitcoin, Ethereum)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Resolve symbol to coinId"),
-    }, async ({ q }, extra) => present(await client.resolveSymbol({ q }, requestKey(extra))));
+    }, async ({ q, agentTrace }, extra) => present(await client.resolveSymbol({ q }, requestKey(extra), agentTrace)));
     server.registerTool("get_equity_curve", {
         title: "Get equity curve",
         description: "Wallet equity time series for the paper account — the basis for " +
@@ -213,10 +261,11 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("daily (default) = one point per day; realized = intraday point " +
                 "per realized-PnL event with cumulative total."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get equity curve"),
-    }, async ({ days, granularity }, extra) => present(await client.getEquityCurve({ days, granularity }, requestKey(extra))));
+    }, async ({ days, granularity, agentTrace }, extra) => present(await client.getEquityCurve({ days, granularity }, requestKey(extra), agentTrace)));
     server.registerTool("get_my_trades", {
         title: "Get my trades",
         description: "Unified realized-PnL log of CLOSED trades across venues (spot fills, " +
@@ -244,10 +293,11 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("ISO 8601 cursor: only trades closed/settled since this instant. " +
                 "Pass the previous response's asOf back here."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get my trades"),
-    }, async ({ venue, limit, updatedSince }, extra) => present(await client.getMyTrades({ venue, limit, updatedSince }, requestKey(extra))));
+    }, async ({ venue, limit, updatedSince, agentTrace }, extra) => present(await client.getMyTrades({ venue, limit, updatedSince }, requestKey(extra), agentTrace)));
     server.registerTool("get_market_context", {
         title: "Get market context",
         description: "Compact factual context for ONE coin to form a thesis: price + " +
@@ -265,10 +315,11 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe('Coin UCID (e.g. "1" = BTC). Use resolve_symbol to find it.'),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get market context"),
-    }, async ({ coinId }, extra) => present(await client.getMarketContext(coinId, requestKey(extra))));
+    }, async ({ coinId, agentTrace }, extra) => present(await client.getMarketContext(coinId, requestKey(extra), agentTrace)));
     server.registerTool("get_candles", {
         title: "Get OHLCV candles",
         description: "OHLCV candles for indicator/momentum strategies (RSI, moving " +
@@ -291,10 +342,11 @@ export function registerTools(server, client) {
                 .string()
                 .optional()
                 .describe("Quote currency for o/h/l/c (default USD)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get OHLCV candles"),
-    }, async ({ coinId, range, fiat }, extra) => present(await client.getCandles(coinId, { range, fiat }, requestKey(extra))));
+    }, async ({ coinId, range, fiat, agentTrace }, extra) => present(await client.getCandles(coinId, { range, fiat }, 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 " +
@@ -337,10 +389,11 @@ export function registerTools(server, client) {
             ])
                 .optional()
                 .describe("Prediction-market sort (default best)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Discover prediction markets"),
-    }, async ({ q, source, limit, offset, sort }, extra) => present(await client.discoverPmMarkets({ q, source, limit, offset, sort }, requestKey(extra))));
+    }, async ({ q, source, limit, offset, sort, agentTrace }, extra) => present(await client.discoverPmMarkets({ q, source, limit, offset, sort }, requestKey(extra), agentTrace)));
     server.registerTool("get_performance", {
         title: "Get my performance",
         description: "The calling key's own realized performance: total + per-venue realized " +
@@ -348,10 +401,76 @@ export function registerTools(server, client) {
             "until there are decided trades). Closed trades only — the scorecard for " +
             "this agent. " +
             PAPER_NOTE,
-        inputSchema: {},
+        inputSchema: {
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get my performance"),
-    }, async (_args, extra) => present(await client.getPerformance(requestKey(extra))));
+    }, async ({ agentTrace }, extra) => present(await client.getPerformance(requestKey(extra), agentTrace)));
+    server.registerTool("get_agent_ledger", {
+        title: "Get private agent ledger",
+        description: "List this API key's private execution ledger: reads, quotes, writes, " +
+            "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,
+        inputSchema: {
+            venue: z.string().optional().describe("Optional venue filter."),
+            eventType: z.string().optional().describe("Optional event type filter."),
+            runId: z.string().optional().describe("Optional run id filter."),
+            decisionId: z
+                .string()
+                .optional()
+                .describe("Optional decision id filter."),
+            status: z
+                .string()
+                .optional()
+                .describe("Optional ledgerStatus filter."),
+            from: z.string().optional().describe("Optional ISO start timestamp."),
+            to: z.string().optional().describe("Optional ISO end timestamp."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Rows to return (1-100, default 25)."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Pagination offset (default 0)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get private agent ledger"),
+    }, async ({ venue, eventType, runId, decisionId, status, from, to, limit, offset, agentTrace, }, extra) => present(await client.getLedger({ venue, eventType, runId, decisionId, status, from, to, limit, offset }, requestKey(extra), agentTrace)));
+    server.registerTool("export_agent_ledger", {
+        title: "Export private agent ledger",
+        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,
+        inputSchema: {
+            venue: z.string().optional().describe("Optional venue filter."),
+            eventType: z.string().optional().describe("Optional event type filter."),
+            runId: z.string().optional().describe("Optional run id filter."),
+            decisionId: z
+                .string()
+                .optional()
+                .describe("Optional decision id filter."),
+            status: z
+                .string()
+                .optional()
+                .describe("Optional ledgerStatus filter."),
+            from: z.string().optional().describe("Optional ISO start timestamp."),
+            to: z.string().optional().describe("Optional ISO end timestamp."),
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Export private agent ledger"),
+    }, async ({ venue, eventType, runId, decisionId, status, from, to, agentTrace }, extra) => present(await client.exportLedger({ venue, eventType, runId, decisionId, status, from, to }, requestKey(extra), agentTrace)));
     server.registerTool("get_arena_leaderboard", {
         title: "Get Agent Arena leaderboard",
         description: "The public Agent Arena: opted-in agents ranked by total realized PnL " +
@@ -425,10 +544,11 @@ export function registerTools(server, client) {
                 .number()
                 .min(10)
                 .describe("Isolated margin in mUSD (>= 10)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Futures quote"),
-    }, async ({ coinId, side, leverage, marginMusd }, extra) => present(await client.futuresQuote({ coinId, side, leverage, marginMusd }, requestKey(extra))));
+    }, async ({ coinId, side, leverage, marginMusd, agentTrace }, extra) => present(await client.futuresQuote({ coinId, side, leverage, marginMusd, agentTrace }, requestKey(extra))));
     server.registerTool("pm_quote", {
         title: "Prediction-market quote",
         description: "Read-only PM quote for a binary outcome: entry probability, share " +
@@ -444,10 +564,11 @@ export function registerTools(server, client) {
                 .string()
                 .describe("Case-sensitive outcome / market id."),
             stakeMusd: z.number().positive().describe("mUSD to stake (> 0)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Prediction-market quote"),
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, stakeMusd }, requestKey(extra))));
+    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, agentTrace }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, stakeMusd, agentTrace }, requestKey(extra))));
     server.registerTool("spot_quote", {
         title: "Spot quote",
         description: "Read-only spot MARKET quote: live execution price, estimated cost " +
@@ -466,10 +587,11 @@ export function registerTools(server, client) {
                 .number()
                 .positive()
                 .describe("Amount of the base coin (> 0)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Spot quote"),
-    }, async ({ coinId, side, quantity }, extra) => present(await client.spotQuote({ coinId, side, quantity }, requestKey(extra))));
+    }, async ({ coinId, side, quantity, agentTrace }, extra) => present(await client.spotQuote({ coinId, side, quantity, agentTrace }, requestKey(extra))));
     // ---------------- writes ----------------
     server.registerTool("place_spot_order", {
         title: "Place spot order",
@@ -503,10 +625,11 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Unique per intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Place spot order"),
-    }, async ({ coinId, side, orderType, quantity, limitPrice, stopPrice, idempotencyKey }, extra) => present(await client.placeSpotOrder({
+    }, async ({ coinId, side, orderType, quantity, limitPrice, stopPrice, idempotencyKey, agentTrace, }, extra) => present(await client.placeSpotOrder({
         coinId,
         side,
         orderType,
@@ -514,6 +637,7 @@ export function registerTools(server, client) {
         limitPrice,
         stopPrice,
         idempotencyKey,
+        agentTrace,
     }, requestKey(extra))));
     server.registerTool("cancel_spot_order", {
         title: "Cancel spot order",
@@ -522,12 +646,13 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             orderId: z.number().int().positive().describe("Open order id."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Cancel spot order", {
             destructive: true,
         }),
-    }, async ({ orderId }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra))));
+    }, async ({ orderId, agentTrace }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra), agentTrace)));
     server.registerTool("open_futures_position", {
         title: "Open futures position",
         description: "Open (or add to) a mock futures position. Requires the trade:futures " +
@@ -570,12 +695,13 @@ export function registerTools(server, client) {
                 .optional()
                 .describe("Optional resting take-profit set atomically at open (USD " +
                 "trigger; fired by the per-minute worker)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Open futures position", {
             idempotent: true,
         }),
-    }, async ({ coinId, side, leverage, marginMusd, idempotencyKey, stopLossPrice, takeProfitPrice, }, extra) => present(await client.openFuturesPosition({
+    }, async ({ coinId, side, leverage, marginMusd, idempotencyKey, stopLossPrice, takeProfitPrice, agentTrace, }, extra) => present(await client.openFuturesPosition({
         coinId,
         side,
         leverage,
@@ -583,6 +709,7 @@ export function registerTools(server, client) {
         idempotencyKey,
         ...(stopLossPrice !== undefined ? { stopLossPrice } : {}),
         ...(takeProfitPrice !== undefined ? { takeProfitPrice } : {}),
+        agentTrace,
     }, requestKey(extra))));
     server.registerTool("set_futures_sl_tp", {
         title: "Set futures stop-loss / take-profit",
@@ -612,15 +739,17 @@ export function registerTools(server, client) {
                 .nullable()
                 .optional()
                 .describe("Positive number sets; null clears; omit = unchanged."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Set futures SL/TP", {
             idempotent: true,
         }),
-    }, async ({ positionId, stopLossPrice, takeProfitPrice }, extra) => present(await client.setFuturesSlTp({
+    }, async ({ positionId, stopLossPrice, takeProfitPrice, agentTrace }, extra) => present(await client.setFuturesSlTp({
         positionId,
         ...(stopLossPrice !== undefined ? { stopLossPrice } : {}),
         ...(takeProfitPrice !== undefined ? { takeProfitPrice } : {}),
+        agentTrace,
     }, requestKey(extra))));
     server.registerTool("close_futures_position", {
         title: "Close futures position",
@@ -644,13 +773,14 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Unique per close intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Close futures position", {
             destructive: true,
             idempotent: true,
         }),
-    }, async ({ positionId, fraction, idempotencyKey }, extra) => present(await client.closeFuturesPosition({ positionId, fraction, idempotencyKey }, requestKey(extra))));
+    }, async ({ positionId, fraction, idempotencyKey, agentTrace }, extra) => present(await client.closeFuturesPosition({ positionId, fraction, idempotencyKey, agentTrace }, requestKey(extra))));
     server.registerTool("open_pm_position", {
         title: "Open prediction-market position",
         description: "Open a mock prediction-market position (binary outcomes only). Requires " +
@@ -671,16 +801,18 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Unique per PM-open intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Open prediction-market position", {
             idempotent: true,
         }),
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey }, extra) => present(await client.openPmPosition({
+    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey, agentTrace, }, extra) => present(await client.openPmPosition({
         source,
         slug,
         outcomeExternalMarketId,
         stakeMusd,
         idempotencyKey,
+        agentTrace,
     }, requestKey(extra))));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "MCP server for paper-trading on CoinRithm (spot, futures, prediction markets) with a user-minted API key.",
   "type": "module",