@rackspay/wallet-mcp 1.0.0

package/build/index.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+/**
+ * RACKS Wallet MCP Server
+ *
+ * Crypto-native trading and betting infrastructure for AI agents.
+ * Enables Claude Desktop (and any MCP client) to:
+ *   - Check on-chain USDC balances across Arbitrum, Polygon, Solana, HyperCore
+ *   - Place perp/spot orders on Hyperliquid with builder code revenue
+ *   - Place prediction market bets on Polymarket
+ *   - Monitor open positions, orders, and PnL
+ *
+ * Usage (Claude Desktop):
+ *   {
+ *     "mcpServers": {
+ *       "racks-wallet": {
+ *         "command": "npx",
+ *         "args": ["@rackswallet/mcp", "--api-key", "rk_live_..."]
+ *       }
+ *     }
+ *   }
+ *
+ * @see https://wallet.rackspay.com
+ * @see https://modelcontextprotocol.io
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+// Parse --api-key from CLI args (preferred) or fall back to env var
+const argv = process.argv.slice(2);
+const apiKeyFlagIdx = argv.indexOf("--api-key");
+const apiKeyFromFlag = apiKeyFlagIdx !== -1 ? argv[apiKeyFlagIdx + 1] : undefined;
+const CONFIG = {
+    apiUrl: process.env.RACKS_API_URL ?? "https://api.wallet.rackspay.com",
+    apiKey: apiKeyFromFlag ?? process.env.RACKS_API_KEY ?? "",
+    timeout: 15_000,
+};
+if (!CONFIG.apiKey) {
+    console.error("ERROR: RACKS API key is required.\n\n" +
+        "Provide it via the --api-key flag:\n" +
+        '  npx @rackswallet/mcp --api-key "rk_live_..."\n\n' +
+        "Or via the RACKS_API_KEY environment variable.\n\n" +
+        "Get your agent API key at https://wallet.rackspay.com/agents");
+    process.exit(1);
+}
+async function request(method, path, body) {
+    const url = `${CONFIG.apiUrl}${path}`;
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: {
+                "X-Agent-API-Key": CONFIG.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(CONFIG.timeout),
+        });
+        const data = (await res.json().catch(() => ({})));
+        return { ok: res.ok, status: res.status, data };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            return { ok: false, status: 0, data: { error: "Request timed out" } };
+        }
+        return {
+            ok: false,
+            status: 0,
+            data: { error: err instanceof Error ? err.message : "Network error" },
+        };
+    }
+}
+// ── Shared error response helper ──────────────────────────────────────────────
+function errorResult(message, code) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ success: false, error: message, errorCode: code }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+function apiError(res, fallback) {
+    const msg = typeof res.data?.detail === "string"
+        ? res.data.detail
+        : fallback;
+    const codes = {
+        401: "UNAUTHORIZED",
+        403: "FORBIDDEN",
+        404: "NOT_FOUND",
+        422: "VALIDATION_ERROR",
+        502: "UPSTREAM_ERROR",
+    };
+    return errorResult(msg, codes[res.status] ?? "API_ERROR");
+}
+// ============================================================================
+// MCP SERVER
+// ============================================================================
+const server = new McpServer({
+    name: "racks-wallet",
+    version: "1.0.0",
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_status
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_status", "Check this agent's current status: name, wallet addresses, USDC balances across all chains, " +
+    "enabled capabilities (trading, betting, card issuance), and spending limits. " +
+    "Call this first to understand what this agent can do.", {}, async () => {
+    const res = await request("GET", "/api/v1/agent/status");
+    if (!res.ok)
+        return apiError(res, "Failed to fetch agent status");
+    const d = res.data;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    agent: {
+                        name: d.name,
+                        type: d.type,
+                        status: d.status,
+                        wallet_address: d.wallet_address,
+                        wallet_status: d.wallet_status,
+                        balance: d.balance,
+                        capabilities: d.capabilities,
+                        monthly_spend_limit: d.monthly_spend_limit,
+                        daily_spend_limit: d.daily_spend_limit,
+                    },
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_wallet_balance
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_wallet_balance", "Return this agent's USDC balance on every chain: Arbitrum (primary), Polygon (Polymarket), " +
+    "Solana, and HyperCore (funds deposited into Hyperliquid). " +
+    "Use this before trading or betting to verify sufficient funds.", {}, async () => {
+    const res = await request("GET", "/api/v1/agent/wallet/balance");
+    if (!res.ok)
+        return apiError(res, "Failed to fetch wallet balance");
+    const d = res.data;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    balance: {
+                        arbitrum_usdc: d.arbitrum_usdc,
+                        polygon_usdc: d.polygon_usdc,
+                        hypercore_usdc: d.hypercore_usdc,
+                        total_usdc: d.total_usdc,
+                    },
+                    note: "HyperCore balance is USDC already deposited into Hyperliquid for trading.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_trade_account
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_trade_account", "Fetch this agent's full Hyperliquid HyperCore account state: account value, margin, " +
+    "withdrawable balance, all open positions (with unrealized PnL), and all open orders. " +
+    "Requires trading to be enabled on this agent.", {}, async () => {
+    const res = await request("GET", "/api/v1/agent/trade/account");
+    if (!res.ok)
+        return apiError(res, "Failed to fetch Hyperliquid account");
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ success: true, account: res.data }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_positions
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_positions", "List all open perpetual positions on Hyperliquid for this agent. " +
+    "Each position shows coin, side (long/short), size, entry price, mark price, " +
+    "liquidation price, unrealized PnL, and leverage. " +
+    "Requires trading to be enabled.", {}, async () => {
+    const res = await request("GET", "/api/v1/agent/trade/positions");
+    if (!res.ok)
+        return apiError(res, "Failed to fetch positions");
+    const positions = Array.isArray(res.data) ? res.data : [];
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    position_count: positions.length,
+                    positions,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_place_order
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_place_order", "Place a perpetual futures order on Hyperliquid. The platform's builder code is attached " +
+    "automatically. Supports limit and market orders. " +
+    "IMPORTANT: always call racks_get_wallet_balance first to verify HyperCore balance. " +
+    "Requires trading to be enabled on this agent.", {
+    coin: z
+        .string()
+        .describe('Trading pair coin symbol, e.g. "BTC", "ETH", "SOL"'),
+    side: z
+        .enum(["buy", "sell"])
+        .describe('"buy" opens or adds to a long; "sell" opens or adds to a short'),
+    size: z
+        .number()
+        .positive()
+        .describe("Position size in units of the coin (e.g. 0.01 for 0.01 BTC)"),
+    price: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Limit price in USD. Omit for a market order"),
+    order_type: z
+        .enum(["limit", "market"])
+        .optional()
+        .default("limit")
+        .describe('Order type. Defaults to "limit"'),
+    time_in_force: z
+        .enum(["Gtc", "Ioc", "Alo"])
+        .optional()
+        .default("Gtc")
+        .describe('Time in force: "Gtc" (good till cancel), "Ioc" (immediate or cancel), "Alo" (add liquidity only)'),
+    reduce_only: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, the order can only reduce an existing position"),
+    intent: z
+        .string()
+        .optional()
+        .describe('Human-readable reason for this trade, e.g. "Going long ETH based on bullish breakout"'),
+}, async ({ coin, side, size, price, order_type, time_in_force, reduce_only, intent }) => {
+    const res = await request("POST", "/api/v1/agent/trade/order", {
+        coin,
+        side,
+        size,
+        price,
+        order_type,
+        time_in_force,
+        reduce_only,
+        intent,
+    });
+    if (!res.ok)
+        return apiError(res, "Failed to place order");
+    const d = res.data;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    status: d.status,
+                    order: {
+                        coin,
+                        side,
+                        size,
+                        price: price ?? "market",
+                        order_type,
+                    },
+                    hl_response: d.hl_response,
+                    note: "Builder code attached. Monitor position via racks_get_positions.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_cancel_order
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_cancel_order", "Cancel an open order on Hyperliquid by order ID or client order ID (cloid). " +
+    "Use racks_get_trade_account to find open order IDs.", {
+    coin: z
+        .string()
+        .describe("Coin symbol of the order to cancel, e.g. \"BTC\""),
+    order_id: z
+        .number()
+        .optional()
+        .describe("Hyperliquid numeric order ID (use this or cloid)"),
+    cloid: z
+        .string()
+        .optional()
+        .describe("Client-supplied order ID (use this or order_id)"),
+}, async ({ coin, order_id, cloid }) => {
+    if (!order_id && !cloid) {
+        return errorResult("Provide either order_id or cloid", "MISSING_PARAM");
+    }
+    const res = await request("DELETE", "/api/v1/agent/trade/order", {
+        coin,
+        order_id,
+        cloid,
+    });
+    if (!res.ok)
+        return apiError(res, "Failed to cancel order");
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ success: true, cancelled: { coin, order_id, cloid }, hl_response: res.data.hl_response }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_markets
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_markets", "Browse active Polymarket prediction markets. Returns market questions, outcomes, " +
+    "current prices (0–1 scale = probability), and token IDs needed for placing bets. " +
+    "Use the next_cursor value to paginate through more markets.", {
+    next_cursor: z
+        .string()
+        .optional()
+        .default("MA==")
+        .describe('Pagination cursor (use the next_cursor from a previous call, or omit for the first page)'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .default(10)
+        .describe("Number of markets to return (default 10, max 50)"),
+}, async ({ next_cursor, limit }) => {
+    const res = await request("GET", `/api/v1/agent/predict/markets?next_cursor=${encodeURIComponent(next_cursor ?? "MA==")}&limit=${limit}`);
+    if (!res.ok)
+        return apiError(res, "Failed to fetch Polymarket markets");
+    const d = res.data;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    markets: d.data,
+                    next_cursor: d.next_cursor,
+                    note: "Prices are probabilities on a 0–1 scale. Use token_id when placing bets.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_place_bet
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_place_bet", "Place a prediction market bet on Polymarket via the CLOB. " +
+    "First browse markets with racks_get_markets to find the token_id for the outcome you want. " +
+    "IMPORTANT: ensure the agent holds USDC on Polygon before betting. " +
+    "Requires betting to be enabled and Polymarket API key to be initialised on this agent.", {
+    token_id: z
+        .string()
+        .describe("Polymarket outcome token ID (from racks_get_markets). Each Yes/No outcome has its own token ID"),
+    side: z
+        .enum(["buy", "sell"])
+        .describe('"buy" to open a position; "sell" to close/reduce an existing position'),
+    size_usdc: z
+        .number()
+        .positive()
+        .describe("Amount in USDC to spend on this bet (e.g. 10 = $10 USDC)"),
+    price: z
+        .number()
+        .min(0.01)
+        .max(0.99)
+        .describe("Limit price as a probability between 0.01 and 0.99 (e.g. 0.65 = 65% chance)"),
+    intent: z
+        .string()
+        .optional()
+        .describe('Human-readable rationale, e.g. "Betting Yes on Bitcoin ETF approval before Q3"'),
+}, async ({ token_id, side, size_usdc, price, intent }) => {
+    const res = await request("POST", "/api/v1/agent/predict/bet", {
+        token_id,
+        side,
+        size_usdc,
+        price,
+        intent,
+    });
+    if (!res.ok) {
+        const d = res.data;
+        // Special-case uninitialized API key
+        if (typeof d?.detail === "string" && d.detail.includes("API key not initialised")) {
+            return errorResult("Polymarket API key not initialised. Go to wallet.rackspay.com/agents and click 'Init API Key' for this agent.", "POLY_NOT_INITIALIZED");
+        }
+        return apiError(res, "Failed to place bet");
+    }
+    const d = res.data;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    status: d.status,
+                    order_id: d.order_id,
+                    bet: { token_id, side, size_usdc, price },
+                    note: "Monitor your open positions via racks_get_bet_positions.",
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool: racks_get_bet_positions
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool("racks_get_bet_positions", "List all open Polymarket positions for this agent: market question, outcome, " +
+    "shares held, average entry price, current price, market value, and unrealized PnL. " +
+    "Requires betting to be enabled.", {}, async () => {
+    const res = await request("GET", "/api/v1/agent/predict/positions");
+    if (!res.ok)
+        return apiError(res, "Failed to fetch Polymarket positions");
+    const positions = Array.isArray(res.data) ? res.data : [];
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    position_count: positions.length,
+                    positions,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// SERVER STARTUP
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Print to stderr so it doesn't pollute stdio MCP protocol messages
+    console.error(`RACKS Wallet MCP Server v1.0.0 running (key: ${CONFIG.apiKey.slice(0, 12)}…)`);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rackspay/wallet-mcp",
+  "version": "1.0.0",
+  "description": "RACKS Wallet MCP — crypto trading and betting infrastructure for AI agents. Trade perps on Hyperliquid, bet on Polymarket, and check on-chain balances via Claude Desktop or any MCP client.",
+  "type": "module",
+  "bin": {
+    "racks-wallet-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "racks",
+    "ai-agents",
+    "crypto",
+    "hyperliquid",
+    "polymarket",
+    "trading",
+    "defi"
+  ],
+  "author": "Racks AI, Inc.",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}