@usenami/signer-mcp 0.1.0

package/dist/parsers/okx.js

@@ -0,0 +1,104 @@
+/**
+ * OKX v5 account parser.
+ *
+ * OKX splits balance and positions across TWO endpoints:
+ *   GET /api/v5/account/balance   → equity + free margin
+ *   GET /api/v5/account/positions → open positions
+ *
+ * For the Option-A architecture this means signer's `/account/<venue>` for
+ * OKX may need to return TWO signed requests (or one composite). For v0 we
+ * accept a combined raw payload:
+ *
+ *   {
+ *     "balance":   { ...OKX /balance response... },
+ *     "positions": { ...OKX /positions response... }
+ *   }
+ *
+ * If only `balance` is present (positions response missing), we still emit
+ * a valid NormalizedAccount with empty positions — the agent can decide.
+ *
+ * OKX response wrapper: { "code": "0", "msg": "", "data": [ {...} ] }
+ * Single-element data arrays are typical for these endpoints.
+ *
+ * Docs:
+ *   https://www.okx.com/docs-v5/en/#trading-account-rest-api-get-balance
+ *   https://www.okx.com/docs-v5/en/#trading-account-rest-api-get-positions
+ *
+ * Quirks:
+ *   - OKX returns numbers as strings (like Binance).
+ *   - Empty equity field returns "" not null.
+ *   - Positions array can include zeroed-out rows after closes; filter them.
+ *   - `instId` is OKX's symbol field (e.g. "BTC-USDT-SWAP").
+ */
+function toNum(v, fallback = 0) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : fallback;
+    if (typeof v === "string" && v.length > 0) {
+        const n = parseFloat(v);
+        return Number.isFinite(n) ? n : fallback;
+    }
+    return fallback;
+}
+function unwrapOkxArray(payload) {
+    // Standard shape: { code: "0", data: [ {...} ] }
+    const obj = payload;
+    if (!obj || !Array.isArray(obj.data))
+        return null;
+    const first = obj.data[0];
+    return first ?? null;
+}
+export const parseOkxAccount = (raw) => {
+    const wrap = raw ?? {};
+    const balanceWrap = unwrapOkxArray(wrap.balance);
+    const positionsWrap = wrap.positions;
+    // Equity + free margin from /balance.
+    // OKX returns multi-currency `details: [...]` per account; we sum USDT/USDC
+    // available balances and use totalEq (already USD-normalized).
+    const equity = toNum(balanceWrap?.totalEq);
+    let freeMargin = 0;
+    const details = Array.isArray(balanceWrap?.details) ? balanceWrap?.details : [];
+    for (const d of details) {
+        const ccy = String(d.ccy ?? "");
+        if (ccy === "USDT" || ccy === "USDC" || ccy === "USD") {
+            // availBal is the spendable balance in that currency. Sum across stable
+            // collateral types — close enough for v0 USD-equivalent.
+            freeMargin += toNum(d.availBal);
+        }
+    }
+    // Fallback: if no stable collateral row, use adjEq as a rough proxy.
+    if (freeMargin === 0) {
+        freeMargin = toNum(balanceWrap?.adjEq);
+    }
+    // Positions from /positions.
+    const positions = [];
+    if (positionsWrap && Array.isArray(positionsWrap.data)) {
+        for (const p of positionsWrap.data) {
+            const qty = toNum(p.pos);
+            if (qty === 0)
+                continue;
+            const symbol = String(p.instId ?? "");
+            if (symbol === "")
+                continue;
+            positions.push({
+                symbol,
+                qty,
+                entry_price: toNum(p.avgPx),
+                unrealized_pnl: toNum(p.upl),
+                mark_price: p.markPx !== undefined ? toNum(p.markPx) : undefined,
+            });
+        }
+    }
+    // OKX gives uTime / cTime (timestamps in ms) — use balance.uTime when present.
+    const ts = balanceWrap?.uTime;
+    const updated_at = typeof ts === "string" && ts.length > 0
+        ? new Date(parseInt(ts, 10)).toISOString()
+        : new Date(0).toISOString();
+    return {
+        venue: "okx",
+        equity_usd: equity,
+        free_margin_usd: freeMargin,
+        positions,
+        updated_at,
+    };
+};
+//# sourceMappingURL=okx.js.map

package/dist/parsers/okx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"okx.js","sourceRoot":"","sources":["../../src/parsers/okx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,SAAS,KAAK,CAAC,CAAU,EAAE,QAAQ,GAAG,CAAC;IACrC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,OAAgB;IACtC,iDAAiD;IACjD,MAAM,GAAG,GAAG,OAAkC,CAAC;IAC/C,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAQ,KAAiC,IAAI,IAAI,CAAC;AACpD,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAkB,CAAC,GAAG,EAAqB,EAAE;IACvE,MAAM,IAAI,GAAI,GAA+B,IAAI,EAAE,CAAC;IACpD,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,aAAa,GAAG,IAAI,CAAC,SAAgD,CAAC;IAE5E,sCAAsC;IACtC,4EAA4E;IAC5E,+DAA+D;IAC/D,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,KAAK,MAAM,CAAC,IAAI,OAAyC,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YACtD,wEAAwE;YACxE,yDAAyD;YACzD,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IACD,qEAAqE;IACrE,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,6BAA6B;IAC7B,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,IAAI,aAAa,IAAI,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,KAAK,MAAM,CAAC,IAAI,aAAa,CAAC,IAAsC,EAAE,CAAC;YACrE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,GAAG,KAAK,CAAC;gBAAE,SAAS;YACxB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,EAAE;gBAAE,SAAS;YAC5B,SAAS,CAAC,IAAI,CAAC;gBACb,MAAM;gBACN,GAAG;gBACH,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC3B,cAAc,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;gBAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;aACjE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,MAAM,EAAE,GAAG,WAAW,EAAE,KAAK,CAAC;IAC9B,MAAM,UAAU,GACd,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACrC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE;QAC1C,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAEhC,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,UAAU,EAAE,MAAM;QAClB,eAAe,EAAE,UAAU;QAC3B,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC,CAAC"}

package/dist/parsers/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Common shapes for venue parsers under the Option-A architecture (signer
+ * returns signed read request, signer-mcp executes it + parses).
+ *
+ * Per signer's 2026-05-31T2150 schema-coordination report. The MCP tool
+ * contract returns this normalized shape — venue-specific quirks live
+ * inside each parser.
+ */
+export interface NormalizedAccount {
+    /** Venue id (binance, okx, asterdex) — echoed for agent introspection. */
+    venue: string;
+    /**
+     * Total margin balance in USD-equivalent. Some venues return USDT-collat;
+     * we treat USDT as USD for v0 (acceptable for the demo, real conversion
+     * via mark price comes in v0.1).
+     */
+    equity_usd: number;
+    /**
+     * Free margin = equity - used by open positions. Used for `place_order`
+     * pre-checks ("do I have margin?").
+     */
+    free_margin_usd: number;
+    /** Per-symbol open positions. Empty array when flat. */
+    positions: NormalizedPosition[];
+    /**
+     * Server-side timestamp from the venue. ISO 8601 if the venue gives one,
+     * otherwise a normalized fetch timestamp (parser sets it).
+     */
+    updated_at: string;
+}
+export interface NormalizedPosition {
+    symbol: string;
+    /**
+     * Signed quantity in base asset. Positive = long, negative = short. Zero
+     * positions are filtered out before returning.
+     */
+    qty: number;
+    /** Volume-weighted average entry price. */
+    entry_price: number;
+    /** Unrealized PnL in venue's quote/collat currency. */
+    unrealized_pnl: number;
+    /** Mark price if the venue provides it (Binance does, OKX does, Asterdex partial). */
+    mark_price?: number;
+}
+export interface SignedRequest {
+    venue: string;
+    method: "GET" | "POST" | "DELETE";
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/**
+ * A parser turns a venue's raw account-endpoint response into our normalized
+ * shape. Each parser knows ONE venue's quirks; the dispatcher in
+ * parsers/index.ts picks the right one based on venue id.
+ *
+ * Parsers MUST be tolerant: missing fields → return 0 or [], never throw.
+ * Throwing in a parser cascades to the tool error path, which kills the
+ * agent's ability to call place_order even when the account read partially
+ * worked.
+ */
+export type AccountParser = (raw: unknown) => NormalizedAccount;

package/dist/parsers/types.js

@@ -0,0 +1,10 @@
+/**
+ * Common shapes for venue parsers under the Option-A architecture (signer
+ * returns signed read request, signer-mcp executes it + parses).
+ *
+ * Per signer's 2026-05-31T2150 schema-coordination report. The MCP tool
+ * contract returns this normalized shape — venue-specific quirks live
+ * inside each parser.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/parsers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/parsers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@usenami/signer-mcp",
+  "version": "0.1.0",
+  "description": "Sign CEX orders from any MCP-aware AI agent (Claude Desktop, Cursor, ElizaOS) with keys that never leave an AWS Nitro Enclave.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "signer-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "smoke": "npm run build && tsx scripts/smoke-test.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "trading",
+    "binance",
+    "okx",
+    "perpetuals",
+    "attested-compute",
+    "aws-nitro-enclaves",
+    "claude",
+    "cursor",
+    "elizaos",
+    "ai-agents",
+    "usenami",
+    "signer"
+  ],
+  "author": "Usenami",
+  "license": "MIT",
+  "homepage": "https://usenami.io/signer",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/namixai/namixai-terminal.git",
+    "directory": "signer-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/namixai/namixai-terminal/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.7"
+  }
+}

package/server.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://registry.modelcontextprotocol.io/schemas/server.json",
+  "name": "@usenami/signer-mcp",
+  "version": "0.1.0",
+  "description": "Sign CEX orders (Binance, OKX, Asterdex) from any MCP-aware AI agent with keys that never leave an AWS Nitro Enclave.",
+  "homepage": "https://usenami.io/signer",
+  "license": "MIT",
+  "tags": [
+    "trading",
+    "binance",
+    "okx",
+    "perpetuals",
+    "attested-compute",
+    "aws-nitro-enclaves",
+    "signer",
+    "ai-agents"
+  ],
+  "categories": ["trading", "finance", "security"],
+  "transport": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@usenami/signer-mcp"]
+  },
+  "env_schema": {
+    "SIGNER_GATEWAY_URL": {
+      "description": "Override the Signer gateway URL (default: https://signer.usenami.io)",
+      "required": false
+    },
+    "SIGNER_API_TOKEN": {
+      "description": "Bearer token issued by usenami.io/signer. Required for everything except list_venues.",
+      "required": false,
+      "secret": true
+    }
+  },
+  "tools": [
+    {
+      "name": "list_venues",
+      "description": "List the venues supported by this Signer. Read-only static manifest — no gateway call.",
+      "readOnly": true
+    },
+    {
+      "name": "get_attestation",
+      "description": "Return the AWS Nitro attestation document (PCR0+sig) for the running enclave.",
+      "readOnly": true
+    },
+    {
+      "name": "get_account",
+      "description": "Return equity, free margin, and open positions for a venue.",
+      "readOnly": true
+    },
+    {
+      "name": "place_order",
+      "description": "Sign and submit a single market or limit order. Enclave enforces policy caps.",
+      "readOnly": false
+    },
+    {
+      "name": "cancel_order",
+      "description": "Cancel an outstanding order by venue order_id. Idempotent.",
+      "readOnly": false
+    }
+  ]
+}