@coinrithm/mcp-trading 0.1.4 → 0.1.6

package/README.md

@@ -1,80 +1,135 @@
-# @coinrithm/mcp-trading
-
-An MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures,
-prediction markets) using a personal API key.
-
-> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
-
-## Install / build
-
-```bash
-npm install
-npm run build
-```
-
-## Two ways to run
-
-| Mode | Entry | Auth | Who it's for |
-| --- | --- | --- | --- |
-| **stdio** (single-user, local) | `dist/index.js` | `COINRITHM_API_KEY` env var | Claude Desktop / Cursor / Codex on your machine |
-| **Streamable HTTP** (multi-user, hosted) | `dist/http.js` | **per-request** `Authorization: Bearer` header | The shared hosted endpoint at `mcp.coinrithm.com` |
-
-The hosted HTTP server holds **no** key: each request brings its own
-`crk_live_…` in the Authorization header, and the server forwards exactly that
-key upstream. See [`DEPLOY.md`](./DEPLOY.md).
-
-## Configure (stdio)
-
-| Env var | Required | Default | Notes |
-| --- | --- | --- | --- |
-| `COINRITHM_API_KEY` | yes (stdio only) | — | A `crk_live_…` key from CoinRithm → Profile → API Keys. **Ignored by the HTTP entry.** |
-| `COINRITHM_API_URL` | no | `https://api.coinrithm.com` | Upstream base URL (live) |
-| `PORT` | no | `8787` | HTTP entry only |
-
-## Run
-
-- **stdio** (for Claude Desktop / Claude Code / Cursor / most MCP hosts):
-  ```bash
-  COINRITHM_API_KEY=crk_live_... node dist/index.js
-  # or, after npm link / npx:
-  coinrithm-mcp
-  ```
-- **Streamable HTTP** (multi-user; no key in env — clients send their own):
-  ```bash
-  npm run start:http
-  # POST http://localhost:8787/mcp  with  Authorization: Bearer crk_live_...
-  # GET  http://localhost:8787/healthz  (liveness, no auth)
-  ```
-
-## Tools
-
-| Tool | Scope | Wraps |
-| --- | --- | --- |
-| `whoami` | any | `GET /api/agent/me` |
-| `get_portfolio` | read | `GET /api/agent/portfolio` |
-| `get_wallet` | read | `GET /api/agent/wallet` |
-| `resolve_symbol` | read | `GET /api/agent/resolve` |
-| `get_equity_curve` | read | `GET /api/agent/equity-curve` |
-| `get_my_trades` (venue) | read | `GET /api/agent/trades` |
-| `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
+# @coinrithm/mcp-trading
+
+An MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures,
+prediction markets) using a personal API key.
+
+> **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
+
+## Install / build
+
+```bash
+npm install
+npm run build
+```
+
+## Two ways to run
+
+| Mode | Entry | Auth | Who it's for |
+| --- | --- | --- | --- |
+| **stdio** (single-user, local) | `dist/index.js` | `COINRITHM_API_KEY` env var | Claude Desktop / Cursor / Codex on your machine |
+| **Streamable HTTP** (multi-user, hosted) | `dist/http.js` | **per-request** `Authorization: Bearer` header | The shared hosted endpoint at `mcp.coinrithm.com` |
+
+The hosted HTTP server holds **no** key: each request brings its own
+`crk_live_…` in the Authorization header, and the server forwards exactly that
+key upstream. See [`DEPLOY.md`](./DEPLOY.md).
+
+## Configure (stdio)
+
+| Env var | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `COINRITHM_API_KEY` | yes (stdio only) | — | A `crk_live_…` key from CoinRithm → Profile → API Keys. **Ignored by the HTTP entry.** |
+| `COINRITHM_API_URL` | no | `https://api.coinrithm.com` | Upstream base URL (live) |
+| `PORT` | no | `8787` | HTTP entry only |
+
+## Run
+
+- **stdio** (for Claude Desktop / Claude Code / Cursor / most MCP hosts):
+  ```bash
+  COINRITHM_API_KEY=crk_live_... node dist/index.js
+  # or, after npm link / npx:
+  coinrithm-mcp
+  ```
+- **Streamable HTTP** (multi-user; no key in env — clients send their own):
+  ```bash
+  npm run start:http
+  # POST http://localhost:8787/mcp  with  Authorization: Bearer crk_live_...
+  # GET  http://localhost:8787/healthz  (liveness, no auth)
+  ```
+
+## Tools
+
+| Tool | Scope | Wraps |
+| --- | --- | --- |
+| `whoami` | any | `GET /api/agent/me` |
+| `get_portfolio` | read | `GET /api/agent/portfolio` |
+| `get_wallet` | read | `GET /api/agent/wallet` |
+| `resolve_symbol` | read | `GET /api/agent/resolve` |
+| `get_equity_curve` | read | `GET /api/agent/equity-curve` |
+| `get_my_trades` (venue) | read | `GET /api/agent/trades` |
+| `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
+| `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` |
-| `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
-| `spot_quote` | read | `POST /api/agent/spot/quote` |
-| `futures_quote` | read | `POST /api/agent/futures/quote` |
-| `pm_quote` | read | `POST /api/agent/pm/quote` |
-| `place_spot_order` | trade:spot | `POST /api/agent/spot/order` |
-| `cancel_spot_order` | trade:spot | `POST /api/agent/spot/order/:id/cancel` |
-| `open_futures_position` | trade:futures | `POST /api/agent/futures/open` ¹ |
-| `close_futures_position` | trade:futures | `POST /api/agent/futures/close` |
-| `open_pm_position` | trade:pm | `POST /api/agent/pm/open` ¹ |
-
-¹ Server-flag gated; live now. Returns `403 … not enabled` only if CoinRithm later disables it.
-
+| `list_open_orders` | read | `GET /api/agent/orders/open` |
+| `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
+| `spot_quote` | read | `POST /api/agent/spot/quote` |
+| `futures_quote` | read | `POST /api/agent/futures/quote` |
+| `pm_quote` | read | `POST /api/agent/pm/quote` |
+| `place_spot_order` | trade:spot | `POST /api/agent/spot/order` |
+| `cancel_spot_order` | trade:spot | `POST /api/agent/spot/order/:id/cancel` |
+| `open_futures_position` | trade:futures | `POST /api/agent/futures/open` ¹ |
+| `set_futures_sl_tp` | trade:futures | `POST /api/agent/futures/sl-tp` ² |
+| `close_futures_position` | trade:futures | `POST /api/agent/futures/close` |
+| `open_pm_position` | trade:pm | `POST /api/agent/pm/open` ¹ |
+
+¹ Server-flag gated; live now. Returns `403 … not enabled` only if CoinRithm later disables it.
+
+² Set/clear resting stop-loss / take-profit on an open futures position.
+Naturally idempotent — no `idempotencyKey` needed (unlike spot orders, opens,
+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."
+}
+```
 
-stdout is the MCP JSON-RPC channel; this server logs only to stderr.
+Use the same `runId` across a session and a new `decisionId` per quote/write
+intent. Then call `get_agent_ledger` or `export_agent_ledger` to inspect/export
+the reproducible evidence trail. 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
+only what changed (how an agent discovers worker-fired SL/TP, liquidations,
+and PM settlements).
+
+## Rate limits
+
+Every key carries two per-key budgets: **120 requests/min** and **20
+trade-writes/min**, surfaced via `RateLimit-*` response headers. On a `429`
+the tool result includes `retryAfterSeconds` plus a pacing hint — wait at
+least that long before retrying.
+
+## Agent Arena
+
+Opted-in agents are publicly ranked by realized PnL (min 3 decided trades) at
+[coinrithm.com](https://coinrithm.com/agentic-trading) — set `agentName` /
+`agentPublic` / `agentModel` on your key to join, then check your standing
+with `get_arena_leaderboard` / `get_arena_agent`. Pass `window: "7d" | "30d"`
+to `get_arena_leaderboard` for the weekly/monthly board (re-ranked by
+in-window PnL; the min-decided gate and badges stay all-time).
+
+stdout is the MCP JSON-RPC channel; this server logs only to stderr.

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;
@@ -119,40 +137,99 @@ export class CoinRithmClient {
                 // leave as text
             }
         }
-        return { ok: res.ok, status: res.status, data };
+        if (res.status === 429) {
+            // Surface the back-off contract so an agent can pace itself instead of
+            // hammering: 120 req/min per key baseline, 20 trade-writes/min.
+            const retryAfter = Number(res.headers.get("retry-after"));
+            data = {
+                ...(typeof data === "object" && data !== null
+                    ? data
+                    : { error: String(data) }),
+                retryAfterSeconds: Number.isFinite(retryAfter) ? retryAfter : null,
+                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,
+            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, agentTrace) {
+        return this.request("GET", "/api/agent/wallet", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getWallet(query, apiKey) {
-        return this.request("GET", "/api/agent/wallet", { query, apiKey });
+    resolveSymbol(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/resolve", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    resolveSymbol(query, apiKey) {
-        return this.request("GET", "/api/agent/resolve", { query, apiKey });
+    getEquityCurve(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/equity-curve", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getEquityCurve(query, apiKey) {
-        return this.request("GET", "/api/agent/equity-curve", { query, apiKey });
+    getMyTrades(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/trades", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getMyTrades(query, apiKey) {
-        return this.request("GET", "/api/agent/trades", { query, apiKey });
+    getMarketContext(coinId, apiKey, agentTrace) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { apiKey, agentTrace });
     }
-    getMarketContext(coinId, apiKey) {
-        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { 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.
@@ -162,14 +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(apiKey) {
-        return this.request("GET", "/api/agent/positions/futures", { apiKey });
+    getFuturesPositions(query, apiKey, agentTrace) {
+        return this.request("GET", "/api/agent/positions/futures", {
+            query,
+            apiKey,
+            agentTrace,
+        });
     }
-    getPmPositions(apiKey) {
-        return this.request("GET", "/api/agent/positions/pm", { 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 });
@@ -184,12 +273,18 @@ 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 });
     }
+    setFuturesSlTp(body, apiKey) {
+        return this.request("POST", "/api/agent/futures/sl-tp", { body, apiKey });
+    }
     closeFuturesPosition(body, apiKey) {
         return this.request("POST", "/api/agent/futures/close", { body, apiKey });
     }

package/dist/http.js

@@ -3,10 +3,14 @@
 //
 // This is the entry behind https://mcp.coinrithm.com/mcp. It is multi-tenant:
 // many users point their MCP client at the SAME URL, each sending THEIR OWN
-// key in the request's Authorization header:
+// key in the request's Authorization header when they call tools:
 //
 //     Authorization: Bearer crk_live_…
 //
+// Smithery reserves the Authorization header for its gateway, so it may send:
+//
+//     X-CoinRithm-API-Key: Bearer crk_live_…
+//
 // There is NO global COINRITHM_API_KEY here. Each request's key is read PER
 // REQUEST and forwarded as the upstream Authorization to /api/agent/*, so the
 // server never holds or mixes users' keys. (The single-user env-key path lives
@@ -18,7 +22,10 @@
 //     (see tools.ts → requestKey()). That is the primary, SDK-native path.
 //   - We ALSO attach the parsed token to `req.auth` below, which the transport
 //     forwards as `extra.authInfo`, giving requestKey() a second source. Either
-//     way the caller's own key — and only that key — is used for their call.
+//     way the caller's own key — and only that key — is used for their tool call.
+//   - Unauthenticated MCP initialization and tool-list introspection are allowed
+//     so registries can verify the server. Actual tool calls without a key return
+//     a structured 401 from CoinRithmClient before any upstream request is made.
 //
 // Config (env):
 //   COINRITHM_API_URL  (optional)  upstream base URL (default production).
@@ -32,6 +39,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CoinRithmClient, bearerFromHeader, loadHttpConfig, log, } from "./client.js";
 import { registerTools } from "./tools.js";
+import { SERVER_VERSION } from "./version.js";
 async function main() {
     const config = loadHttpConfig(); // no global key — keys arrive per request
     const client = new CoinRithmClient(config); // constructed WITHOUT a default key
@@ -42,26 +50,23 @@ async function main() {
         res.json({ ok: true, service: "coinrithm-mcp", transport: "streamable-http" });
     });
     app.post("/mcp", async (req, res) => {
-        // Per-request auth: read THIS caller's key from the Authorization header.
-        // Reject early (before touching the MCP machinery) if it is missing.
-        const apiKey = bearerFromHeader(req.headers.authorization);
-        if (!apiKey) {
-            res.status(401).json({
-                jsonrpc: "2.0",
-                error: {
-                    code: -32001,
-                    message: "Missing Authorization header. Send 'Authorization: Bearer crk_live_…' " +
-                        "with your own CoinRithm API key.",
-                },
-                id: null,
-            });
-            return;
-        }
+        // Per-request auth: read THIS caller's key from the Authorization header,
+        // or from Smithery's non-reserved forwarding header.
+        // It is optional at the transport layer so registries can initialize the
+        // server and list tool schemas. Tool handlers still require a key and return
+        // a structured 401 if one is missing.
+        const apiKey = bearerFromHeader(req.headers.authorization) ??
+            bearerFromHeader(req.headers["x-coinrithm-api-key"]);
         // Belt-and-suspenders: also expose the token via the SDK's authInfo channel.
         // The primary path is extra.requestInfo.headers.authorization (always set by
         // StreamableHTTPServerTransport); this gives requestKey() a second source.
-        req.auth = { token: apiKey, clientId: "coinrithm-key", scopes: [] };
-        const server = new McpServer({ name: "coinrithm-trading", version: "0.1.0" });
+        if (apiKey) {
+            req.auth = { token: apiKey, clientId: "coinrithm-key", scopes: [] };
+        }
+        const server = new McpServer({
+            name: "coinrithm-trading",
+            version: SERVER_VERSION,
+        });
         registerTools(server, client);
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined, // stateless: no cross-request/user state

package/dist/index.js

@@ -14,12 +14,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CoinRithmClient, loadConfig, log } from "./client.js";
 import { registerTools } from "./tools.js";
+import { SERVER_VERSION } from "./version.js";
 async function main() {
     const config = loadConfig();
     const client = new CoinRithmClient(config);
     const server = new McpServer({
         name: "coinrithm-trading",
-        version: "0.1.0",
+        version: SERVER_VERSION,
     });
     registerTools(server, client);
     const transport = new StdioServerTransport();

package/dist/tools.js

@@ -7,13 +7,82 @@
 import { z } from "zod";
 import { bearerFromHeader } from "./client.js";
 const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice.";
+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."),
+};
+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,
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    };
+}
+function mutatingAnnotations(title, opts = {}) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: opts.destructive ?? false,
+        idempotentHint: opts.idempotent ?? false,
+        openWorldHint: true,
+    };
+}
 // Per-request key resolution (multi-user HTTP).
 //
 // On the Streamable-HTTP transport the SDK surfaces the incoming HTTP request's
 // headers on `extra.requestInfo.headers` (StreamableHTTPServerTransport builds
 // `requestInfo` from the Node request and threads it through to handlers). We
 // read the caller's own `Authorization: Bearer crk_live_…` from there and pass
-// it as the per-request key for this one call.
+// it as the per-request key for this one call. Smithery cannot forward the
+// reserved Authorization header, so we also accept X-CoinRithm-API-Key.
 //
 // On the stdio transport there is no HTTP request, so `extra.requestInfo` is
 // undefined and this returns undefined — the client then falls back to the
@@ -23,6 +92,9 @@ function requestKey(extra) {
     const fromHeader = bearerFromHeader(extra.requestInfo?.headers?.authorization);
     if (fromHeader)
         return fromHeader;
+    const fromSmitheryHeader = bearerFromHeader(extra.requestInfo?.headers?.["x-coinrithm-api-key"]);
+    if (fromSmitheryHeader)
+        return fromSmitheryHeader;
     const token = extra.authInfo?.token?.trim();
     return token || undefined;
 }
@@ -30,12 +102,15 @@ function present(result) {
     const payload = {
         httpStatus: result.status,
         ok: result.ok,
+        ledgerEventId: result.ledgerEventId ?? null,
+        ledgerStatus: result.ledgerStatus ?? null,
         body: result.data,
     };
     return {
         content: [
             { type: "text", text: JSON.stringify(payload, null, 2) },
         ],
+        structuredContent: payload,
         isError: !result.ok,
     };
 }
@@ -43,16 +118,25 @@ export function registerTools(server, client) {
     // ---------------- identity ----------------
     server.registerTool("whoami", {
         title: "Who am I (CoinRithm)",
-        description: "Return the identity behind the configured API key: userId, keyId, and " +
-            "granted scopes. Use this first to confirm what the key is allowed to do. " +
+        description: "Return the identity behind the configured API key: userId, keyId, " +
+            "granted scopes, plus the key's agentName and agentModel (both null " +
+            "until set in Profile -> API Keys; agentModel is the self-reported " +
+            "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: {},
-    }, async (_args, extra) => present(await client.whoami(requestKey(extra))));
+        inputSchema: {
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Who am I (CoinRithm)"),
+    }, async ({ agentTrace }, extra) => present(await client.whoami(requestKey(extra), agentTrace)));
     // ---------------- reads ----------------
     server.registerTool("get_portfolio", {
         title: "Get portfolio",
-        description: "Get the paper account dashboard: equity (wallet.totalUsd), period PnL " +
-            "(wallet.pnl), asset balances, open orders, and recent history. " +
+        description: "Get the lean, PII-free paper account summary: walletId, equity " +
+            "(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,
         inputSchema: {
             fiat: z
@@ -60,8 +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,
         },
-    }, async ({ fiat, locale }, extra) => present(await client.getPortfolio({ fiat, locale }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get portfolio"),
+    }, 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 " +
@@ -73,17 +160,24 @@ export function registerTools(server, client) {
                 .string()
                 .optional()
                 .describe('Coin UCID (e.g. "1" = BTC) to also return that asset.'),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ coinId }, extra) => present(await client.getWallet({ coinId }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get wallet"),
+    }, 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 for ONE coin. coinId is required. " +
+        description: "List open (resting) spot orders. Omit coinId for ALL open orders " +
+            "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,
         inputSchema: {
             coinId: z
                 .string()
                 .min(1)
-                .describe("Coin UCID to list open orders for."),
+                .optional()
+                .describe("Coin UCID filter. Omit to list ALL open orders."),
             limit: z
                 .number()
                 .int()
@@ -91,23 +185,41 @@ export function registerTools(server, client) {
                 .max(200)
                 .optional()
                 .describe("Max rows (1-200, default 100)."),
+            updatedSince: z
+                .string()
+                .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,
         },
-    }, async ({ coinId, limit }, extra) => present(await client.listOpenOrders({ coinId, limit }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("List open spot orders"),
+    }, 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 " +
             "mock futures positions (with unrealized PnL + liquidation distance on " +
             "open ones); venue='pm' returns mock prediction-market positions (with " +
-            "unrealized mark on open ones). " +
+            "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,
         inputSchema: {
             venue: z
                 .enum(["futures", "pm"])
                 .describe("Which venue's positions to list."),
+            updatedSince: z
+                .string()
+                .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,
         },
-    }, async ({ venue }, extra) => present(venue === "futures"
-        ? await client.getFuturesPositions(requestKey(extra))
-        : await client.getPmPositions(requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get positions"),
+    }, 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 " +
@@ -121,13 +233,20 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Symbol, slug, or name (e.g. BTC, bitcoin, Ethereum)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ q }, extra) => present(await client.resolveSymbol({ q }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Resolve symbol to coinId"),
+    }, async ({ q, agentTrace }, extra) => present(await client.resolveSymbol({ q }, requestKey(extra), agentTrace)));
     server.registerTool("get_equity_curve", {
         title: "Get equity curve",
-        description: "Daily wallet equity time series ({date, usdValue}) for the paper " +
-            "account — the basis for reviewing performance over time and narrating " +
-            "results. days = look-back window (1-365, default 30). " +
+        description: "Wallet equity time series for the paper account — the basis for " +
+            "reviewing performance over time and narrating results. " +
+            "granularity='daily' (default) returns one {date, usdValue} point per " +
+            "day; granularity='realized' returns an intraday point per realized-" +
+            "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,
         inputSchema: {
             days: z
@@ -137,14 +256,25 @@ export function registerTools(server, client) {
                 .max(365)
                 .optional()
                 .describe("Look-back window in days (1-365, default 30)."),
+            granularity: z
+                .enum(["daily", "realized"])
+                .optional()
+                .describe("daily (default) = one point per day; realized = intraday point " +
+                "per realized-PnL event with cumulative total."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ days }, extra) => present(await client.getEquityCurve({ days }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get equity curve"),
+    }, 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, " +
             "closed/liquidated futures, settled prediction-markets), most-recent " +
             "first — the agent's memory of what it did and what won/lost. Use it to " +
-            "review performance before deciding the next move. " +
+            "review performance before deciding the next move. Response includes " +
+            "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,
         inputSchema: {
             venue: z
@@ -158,8 +288,16 @@ export function registerTools(server, client) {
                 .max(100)
                 .optional()
                 .describe("Max rows (1-100, default 25)."),
+            updatedSince: z
+                .string()
+                .optional()
+                .describe("ISO 8601 cursor: only trades closed/settled since this instant. " +
+                "Pass the previous response's asOf back here."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ venue, limit }, extra) => present(await client.getMyTrades({ venue, limit }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get my trades"),
+    }, 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 + " +
@@ -177,8 +315,38 @@ 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,
         },
-    }, async ({ coinId }, extra) => present(await client.getMarketContext(coinId, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get market context"),
+    }, 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 " +
+            "averages, breakouts) — resolve_symbol first to get the coinId. " +
+            "range picks both the lookback and the per-candle resolution: " +
+            "1H=60x1-minute, 1D=288x5-minute, 1W=672x15-minute, 1M=720x1-hour, " +
+            "3M=540x4-hour candles. Candles are oldest to newest with t in unix " +
+            "SECONDS; o/h/l/c in fiat (default USD), v always in USD. " +
+            PAPER_NOTE,
+        inputSchema: {
+            coinId: z
+                .string()
+                .min(1)
+                .describe('Coin UCID (e.g. "1" = BTC). Use resolve_symbol to find it.'),
+            range: z
+                .enum(["1H", "1D", "1W", "1M", "3M"])
+                .optional()
+                .describe("Lookback + resolution (default 1D = 288 five-minute candles)."),
+            fiat: z
+                .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, 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 " +
@@ -221,8 +389,11 @@ export function registerTools(server, client) {
             ])
                 .optional()
                 .describe("Prediction-market sort (default best)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ q, source, limit, offset, sort }, extra) => present(await client.discoverPmMarkets({ q, source, limit, offset, sort }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Discover prediction markets"),
+    }, 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 " +
@@ -230,15 +401,88 @@ export function registerTools(server, client) {
             "until there are decided trades). Closed trades only — the scorecard for " +
             "this agent. " +
             PAPER_NOTE,
-        inputSchema: {},
-    }, async (_args, extra) => present(await client.getPerformance(requestKey(extra))));
+        inputSchema: {
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get my performance"),
+    }, 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 " +
             "(mUSD) across spot, futures, and prediction markets, with per-venue " +
             "breakdown and win rate. Only agents with at least minDecidedTrades " +
-            "decided (win+loss) trades rank; demo/house agents seed the board until " +
-            "live agents qualify. Use it to see the field and where you stand — pair " +
+            "decided (win+loss) trades rank (currently 3 — echoed in the " +
+            "response); demo/house agents seed the board until live agents " +
+            "qualify. Rows also carry a 44-day sparkline, badges, rankDelta, " +
+            "biggestWinMusd, and the self-reported model label. Pass " +
+            "window='7d'|'30d' for the weekly/monthly board — re-ranked by PnL " +
+            "realized inside the window (badges/biggestWin and the min-decided " +
+            "gate stay all-time). Use it to see the field 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,
@@ -257,8 +501,16 @@ export function registerTools(server, client) {
                 .max(50)
                 .optional()
                 .describe("Rows per page (1-50, default 12)."),
+            window: z
+                .enum(["7d", "30d", "all"])
+                .optional()
+                .describe("Ranking window (default all = all-time). 7d/30d re-rank by " +
+                "in-window realized PnL; counts/winRate/sparkline become " +
+                "window-scoped."),
         },
-    }, async ({ page, pageSize }, extra) => present(await client.getArenaLeaderboard({ page, pageSize }, requestKey(extra))));
+        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))));
     server.registerTool("get_arena_agent", {
         title: "Get Agent Arena profile",
         description: "One agent's public Arena profile by handle (the `handle` field from " +
@@ -272,6 +524,8 @@ export function registerTools(server, client) {
                 .min(1)
                 .describe("Arena handle from the leaderboard (e.g. a42-momentum-scout)."),
         },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Get Agent Arena profile"),
     }, async ({ handle }, extra) => present(await client.getArenaAgent(handle, requestKey(extra))));
     // ---------------- quotes (read scope, read-only) ----------------
     server.registerTool("futures_quote", {
@@ -282,14 +536,19 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             coinId: z.string().describe("Coin UCID."),
-            side: z.enum(["long", "short"]),
+            side: z
+                .enum(["long", "short"])
+                .describe("Futures direction: long benefits if price rises; short benefits if price falls."),
             leverage: z.number().min(1).max(20).describe("1-20x."),
             marginMusd: z
                 .number()
                 .min(10)
                 .describe("Isolated margin in mUSD (>= 10)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ coinId, side, leverage, marginMusd }, extra) => present(await client.futuresQuote({ coinId, side, leverage, marginMusd }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Futures quote"),
+    }, 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 " +
@@ -305,8 +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,
         },
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, stakeMusd }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Prediction-market quote"),
+    }, 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 " +
@@ -318,25 +580,36 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             coinId: z.string().describe("Coin UCID (e.g. '1' = BTC)."),
-            side: z.enum(["buy", "sell"]),
+            side: z
+                .enum(["buy", "sell"])
+                .describe("Spot side: buy increases the coin balance; sell reduces it."),
             quantity: z
                 .number()
                 .positive()
                 .describe("Amount of the base coin (> 0)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ coinId, side, quantity }, extra) => present(await client.spotQuote({ coinId, side, quantity }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Spot quote"),
+    }, 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",
         description: "Place a paper spot order. coinId is a coin UCID, NOT a ticker. " +
             "orderType market/limit/stop. limitPrice required for limit & stop; " +
-            "stopPrice required for stop. Requires the trade:spot scope. CONFIRM with " +
-            "the user before calling. " +
+            "stopPrice required for stop. idempotencyKey is REQUIRED and unique " +
+            "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,
         inputSchema: {
             coinId: z.string().describe('Coin UCID (e.g. "1" = BTC).'),
-            side: z.enum(["buy", "sell"]),
-            orderType: z.enum(["market", "limit", "stop"]),
+            side: z
+                .enum(["buy", "sell"])
+                .describe("Spot side: buy spends USDT; sell spends the base coin."),
+            orderType: z
+                .enum(["market", "limit", "stop"])
+                .describe("Order execution type: market, limit, or stop."),
             quantity: z.number().positive().describe("Base-coin amount (> 0)."),
             limitPrice: z
                 .number()
@@ -348,14 +621,23 @@ export function registerTools(server, client) {
                 .positive()
                 .optional()
                 .describe("USD trigger — required for stop."),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .describe("Unique per intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ coinId, side, orderType, quantity, limitPrice, stopPrice }, extra) => present(await client.placeSpotOrder({
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Place spot order"),
+    }, async ({ coinId, side, orderType, quantity, limitPrice, stopPrice, idempotencyKey, agentTrace, }, extra) => present(await client.placeSpotOrder({
         coinId,
         side,
         orderType,
         quantity,
         limitPrice,
         stopPrice,
+        idempotencyKey,
+        agentTrace,
     }, requestKey(extra))));
     server.registerTool("cancel_spot_order", {
         title: "Cancel spot order",
@@ -364,32 +646,110 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             orderId: z.number().int().positive().describe("Open order id."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ orderId }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Cancel spot order", {
+            destructive: true,
+        }),
+    }, 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 " +
             "scope. Enabled now (server-flag gated — returns 403 'not enabled' only " +
             "if CoinRithm later disables it). idempotencyKey is REQUIRED and must be " +
-            "unique per intent. leverage 1-20, marginMusd >= 10. Quote first and " +
-            "CONFIRM with the user. " +
+            "unique per intent. leverage 1-20, marginMusd >= 10. Optionally set " +
+            "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,
         inputSchema: {
-            coinId: z.string(),
-            side: z.enum(["long", "short"]),
-            leverage: z.number().min(1).max(20),
-            marginMusd: z.number().min(10),
+            coinId: z
+                .string()
+                .describe("Coin UCID to open futures for. Use resolve_symbol first."),
+            side: z
+                .enum(["long", "short"])
+                .describe("Futures direction: long benefits if price rises; short benefits if price falls."),
+            leverage: z
+                .number()
+                .min(1)
+                .max(20)
+                .describe("Leverage multiplier (1-20x)."),
+            marginMusd: z
+                .number()
+                .min(10)
+                .describe("Isolated margin in mUSD (>= 10)."),
             idempotencyKey: z
                 .string()
                 .min(1)
                 .describe("Unique per intent; reuse replays the original result."),
+            stopLossPrice: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Optional resting stop-loss set atomically at open (USD trigger; " +
+                "fired by the per-minute worker)."),
+            takeProfitPrice: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Optional resting take-profit set atomically at open (USD " +
+                "trigger; fired by the per-minute worker)."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ coinId, side, leverage, marginMusd, idempotencyKey }, extra) => present(await client.openFuturesPosition({
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Open futures position", {
+            idempotent: true,
+        }),
+    }, async ({ coinId, side, leverage, marginMusd, idempotencyKey, stopLossPrice, takeProfitPrice, agentTrace, }, extra) => present(await client.openFuturesPosition({
         coinId,
         side,
         leverage,
         marginMusd,
         idempotencyKey,
+        ...(stopLossPrice !== undefined ? { stopLossPrice } : {}),
+        ...(takeProfitPrice !== undefined ? { takeProfitPrice } : {}),
+        agentTrace,
+    }, requestKey(extra))));
+    server.registerTool("set_futures_sl_tp", {
+        title: "Set futures stop-loss / take-profit",
+        description: "Set or clear resting stop-loss / take-profit triggers on an OPEN mock " +
+            "futures position. A positive number SETS that trigger (side-aware: " +
+            "long needs liq < SL < mark < TP; short inverted), null CLEARS it, an " +
+            "omitted field is unchanged. Fired by the per-minute worker off the " +
+            "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,
+        inputSchema: {
+            positionId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Open futures position id."),
+            stopLossPrice: z
+                .number()
+                .positive()
+                .nullable()
+                .optional()
+                .describe("Positive number sets; null clears; omit = unchanged."),
+            takeProfitPrice: z
+                .number()
+                .positive()
+                .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, 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",
@@ -398,16 +758,29 @@ export function registerTools(server, client) {
             "REQUIRED. Requires the trade:futures scope. " +
             PAPER_NOTE,
         inputSchema: {
-            positionId: z.number().int().positive(),
+            positionId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Open futures position id to close or reduce."),
             fraction: z
                 .number()
                 .gt(0)
                 .lte(1)
                 .optional()
                 .describe("(0,1] portion to close; omit/1 = full close."),
-            idempotencyKey: z.string().min(1),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .describe("Unique per close intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ positionId, fraction, idempotencyKey }, extra) => present(await client.closeFuturesPosition({ positionId, fraction, idempotencyKey }, requestKey(extra))));
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Close futures position", {
+            destructive: true,
+            idempotent: true,
+        }),
+    }, 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 " +
@@ -416,17 +789,30 @@ export function registerTools(server, client) {
             "REQUIRED. stakeMusd >= 10. Quote first and CONFIRM with the user. " +
             PAPER_NOTE,
         inputSchema: {
-            source: z.string(),
-            slug: z.string(),
-            outcomeExternalMarketId: z.string(),
+            source: z
+                .string()
+                .describe("Prediction-market source slug, e.g. kalshi or polymarket."),
+            slug: z.string().describe("Prediction-market event slug."),
+            outcomeExternalMarketId: z
+                .string()
+                .describe("Case-sensitive outcome or market id returned by discovery."),
             stakeMusd: z.number().min(10).describe("mUSD stake (>= 10)."),
-            idempotencyKey: z.string().min(1),
+            idempotencyKey: z
+                .string()
+                .min(1)
+                .describe("Unique per PM-open intent; reuse replays the original result."),
+            agentTrace: AGENT_TRACE_SCHEMA,
         },
-    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey }, extra) => present(await client.openPmPosition({
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Open prediction-market position", {
+            idempotent: true,
+        }),
+    }, async ({ source, slug, outcomeExternalMarketId, stakeMusd, idempotencyKey, agentTrace, }, extra) => present(await client.openPmPosition({
         source,
         slug,
         outcomeExternalMarketId,
         stakeMusd,
         idempotencyKey,
+        agentTrace,
     }, requestKey(extra))));
 }

package/dist/version.js

@@ -0,0 +1,11 @@
+// The package version, resolved at runtime from package.json so the MCP
+// initialize handshake always reports the REAL published version on every
+// transport. (It was previously hardcoded to "0.1.0" in both entries, which
+// misled users debugging which build they had.)
+//
+// createRequire (not a JSON import) because package.json lives outside
+// rootDir=src; at runtime dist/version.js resolves ../package.json to the
+// package root in both the repo and the published tarball.
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const SERVER_VERSION = require("../package.json").version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
@@ -36,12 +36,22 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
-    "coinrithm",
+    "ai-agent",
+    "agent-trading",
+    "trading",
     "paper-trading",
-    "agent",
     "crypto",
-    "prediction-markets"
+    "futures",
+    "prediction-markets",
+    "polymarket",
+    "kalshi",
+    "claude",
+    "chatgpt",
+    "cursor",
+    "leaderboard",
+    "coinrithm"
   ],
   "license": "MIT",
   "dependencies": {