x402trade-mcp 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# x402Trade MCP Server
+
+让 Claude、Cursor 等 AI 助手直接在 x402Trade 上交易。
+
+## 5 分钟快速接入
+
+### 1. 安装
+
+```bash
+npm install -g @x402trade/mcp-server
+```
+
+或者直接用 npx（无需安装）：
+
+```bash
+npx @x402trade/mcp-server
+```
+
+### 2. 配置 Claude Desktop
+
+打开 Claude Desktop 配置文件：
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "x402trade": {
+      "command": "npx",
+      "args": ["@x402trade/mcp-server"],
+      "env": {
+        "PRIVATE_KEY": "0x你的以太坊钱包私钥"
+      }
+    }
+  }
+}
+```
+
+重启 Claude Desktop，即可使用。
+
+### 3. 配置 Cursor
+
+在 Cursor 设置 → MCP → Add Server：
+
+```json
+{
+  "name": "x402trade",
+  "command": "npx @x402trade/mcp-server",
+  "env": {
+    "PRIVATE_KEY": "0x你的以太坊钱包私钥"
+  }
+}
+```
+
+---
+
+## 你能对 Claude 说什么
+
+配置完成后，你可以直接用自然语言交易：
+
+```
+你: ETH 现在多少钱？
+Claude: 调用 x402_get_price → ETH 当前价格 $2,247.50，24h 涨 +2.3%
+
+你: 帮我用 $500 买 ETH，限价 $2200
+Claude: 调用 x402_place_order → 订单已提交，订单号 abc-123，挂单中
+
+你: 我现在有多少 USDC？
+Claude: 调用 x402_get_balance → USDC 余额 $1,250.00，ETH 余额 0.45
+
+你: 把刚才那个订单取消
+Claude: 调用 x402_cancel_order → 订单已取消，$500 USDC 已解锁
+
+你: 帮我看看 ETH-USDC 的买卖盘
+Claude: 调用 x402_get_orderbook → 显示当前 bids 和 asks
+```
+
+---
+
+## 可用工具
+
+| 工具 | 说明 | 费用 |
+|---|---|---|
+| `x402_get_price` | 当前价格、24h 涨跌、成交量 | $0.001 |
+| `x402_get_orderbook` | 实时买卖盘 | $0.001 |
+| `x402_get_balance` | 你的 USDC + ETH 余额 | 免费 |
+| `x402_place_order` | 下买单或卖单（限价/市价） | $0.01 |
+| `x402_cancel_order` | 撤销挂单 | 免费 |
+| `x402_get_orders` | 查看我的订单记录 | $0.001 |
+| `x402_get_recent_trades` | 市场最近成交记录 | $0.001 |
+| `x402_deposit_info` | 充值地址和说明 | 免费 |
+
+---
+
+## 充值 USDC
+
+1. 调用 `x402_deposit_info` 获取充值地址
+2. 在 Base L2 (Chain ID: 8453) 向该地址发送 USDC
+3. 约 15 秒后余额自动更新
+
+**注意：只支持 Base L2 上的 USDC，不支持其他网络。**
+
+---
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `PRIVATE_KEY` | 你的以太坊钱包私钥（`0x...`） | 无（只读模式） |
+| `X402_GATEWAY_URL` | 交易所 API 地址 | `https://api.getx402.trade` |
+
+**私钥安全提示：** 私钥只在你的本地机器上使用，不会发送到任何服务器。MCP Server 用私钥在本地签名交易请求，签名后的数据发送给交易所验证。
+
+---
+
+## 本地开发
+
+```bash
+git clone https://github.com/bidendavid/x402trade.git
+cd x402trade/services/x402-mcp
+npm install
+PRIVATE_KEY=0x... npm run dev
+```
+
+---
+
+## 交易对
+
+目前支持：
+- `ETH-USDC` — ETH 对 USDC
+- `BTC-USDC` — BTC 对 USDC
+
+---
+
+## 链接
+
+- **交易所 API**: https://api.getx402.trade
+- **官网**: https://getx402.trade
+- **GitHub**: https://github.com/bidendavid/x402trade
+- **x402 协议**: https://x402.org

package/dist/client.js

@@ -0,0 +1,46 @@
+// Order matters: more specific prefixes must come before shorter ones
+export function getPrice(path) {
+    if (path.startsWith('/trades'))
+        return '0.001'; // before /trade
+    if (path.startsWith('/trade'))
+        return '0.01';
+    if (path.startsWith('/ticker'))
+        return '0.001';
+    if (path.startsWith('/orderbook'))
+        return '0.001';
+    if (path.startsWith('/orders/'))
+        return '0'; // DELETE /orders/:id — before /orders
+    if (path.startsWith('/orders'))
+        return '0.001'; // GET /orders list
+    if (path.startsWith('/balance'))
+        return '0';
+    return '0';
+}
+export async function buildPaymentHeader(wallet, amount) {
+    const nonce = Date.now().toString();
+    const signature = await wallet.signMessage(`x402:${nonce}:${amount}`);
+    return Buffer.from(JSON.stringify({
+        wallet: wallet.address,
+        signature,
+        amount,
+        nonce,
+    })).toString('base64');
+}
+export async function callApi(gatewayUrl, wallet, method, path, body) {
+    const price = getPrice(path);
+    const headers = { 'Content-Type': 'application/json' };
+    if (wallet) {
+        headers['x402-payment'] = await buildPaymentHeader(wallet, price);
+    }
+    const res = await fetch(`${gatewayUrl}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        const msg = data?.error ?? res.statusText;
+        throw new Error(`${res.status}: ${msg}`);
+    }
+    return data;
+}

package/dist/index.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * x402Trade MCP Server
+ *
+ * Lets AI assistants (Claude, Cursor, etc.) interact with x402Trade directly.
+ *
+ * Setup:
+ *   PRIVATE_KEY=0x...  (your Ethereum wallet private key)
+ *   X402_GATEWAY_URL=https://api.getx402.trade  (optional, defaults to production)
+ *
+ * Tools exposed:
+ *   x402_get_price        — Current price, 24h change and volume for a pair
+ *   x402_get_orderbook    — Live bids and asks
+ *   x402_get_balance      — Your USDC and ETH balance
+ *   x402_place_order      — Place a limit or market order
+ *   x402_cancel_order     — Cancel an open order
+ *   x402_get_orders       — List your open/recent orders
+ *   x402_get_recent_trades — Recent fills on a pair
+ *   x402_deposit_info     — How to deposit USDC
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ethers } from 'ethers';
+import { callApi } from './client.js';
+// ── Config ────────────────────────────────────────────────────────────────────
+const GATEWAY_URL = (process.env.X402_GATEWAY_URL || 'https://api.getx402.trade').replace(/\/$/, '');
+const PRIVATE_KEY = process.env.PRIVATE_KEY || '';
+const wallet = PRIVATE_KEY ? new ethers.Wallet(PRIVATE_KEY) : null;
+if (!wallet) {
+    process.stderr.write('[x402-mcp] WARNING: PRIVATE_KEY not set. Read-only mode (no trading).\n');
+}
+function api(method, path, body) {
+    return callApi(GATEWAY_URL, wallet, method, path, body);
+}
+// ── Tool Definitions ──────────────────────────────────────────────────────────
+const TOOLS = [
+    {
+        name: 'x402_get_price',
+        description: 'Get the current price, 24h change, volume, high and low for a trading pair on x402Trade.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pair: {
+                    type: 'string',
+                    description: 'Trading pair. Supported: ETH-USDC, BTC-USDC',
+                    enum: ['ETH-USDC', 'BTC-USDC'],
+                },
+            },
+            required: ['pair'],
+        },
+    },
+    {
+        name: 'x402_get_orderbook',
+        description: 'Get the live order book (bids and asks) for a trading pair. Shows current buy and sell orders.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pair: {
+                    type: 'string',
+                    description: 'Trading pair. Supported: ETH-USDC, BTC-USDC',
+                    enum: ['ETH-USDC', 'BTC-USDC'],
+                },
+                depth: {
+                    type: 'number',
+                    description: 'Number of price levels to return per side. Default 10, max 50.',
+                    default: 10,
+                },
+            },
+            required: ['pair'],
+        },
+    },
+    {
+        name: 'x402_get_balance',
+        description: 'Get the USDC and ETH balance for the configured wallet on x402Trade. Requires PRIVATE_KEY to be set.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'x402_place_order',
+        description: `Place a buy or sell order on x402Trade.
+- Limit order: executes at your specified price or better. Stays in the order book if not immediately matched.
+- Market order: executes immediately at the best available price.
+Costs $0.01 USDC per call. Requires PRIVATE_KEY and sufficient USDC balance.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pair: {
+                    type: 'string',
+                    description: 'Trading pair. Supported: ETH-USDC, BTC-USDC',
+                    enum: ['ETH-USDC', 'BTC-USDC'],
+                },
+                side: {
+                    type: 'string',
+                    description: 'Buy or sell',
+                    enum: ['buy', 'sell'],
+                },
+                type: {
+                    type: 'string',
+                    description: 'Order type: limit (specify price) or market (best available price)',
+                    enum: ['limit', 'market'],
+                },
+                amount: {
+                    type: 'string',
+                    description: 'Amount of base token (ETH or BTC) to buy or sell. E.g. "0.1" for 0.1 ETH.',
+                },
+                price: {
+                    type: 'string',
+                    description: 'Price in USDC per base token. Required for limit orders. E.g. "2200" for $2200 per ETH.',
+                },
+            },
+            required: ['pair', 'side', 'type', 'amount'],
+        },
+    },
+    {
+        name: 'x402_cancel_order',
+        description: 'Cancel an open or partially filled order. Cancellation is free. Locked funds are returned to your balance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                order_id: {
+                    type: 'string',
+                    description: 'The order ID to cancel (UUID format, returned when you placed the order)',
+                },
+            },
+            required: ['order_id'],
+        },
+    },
+    {
+        name: 'x402_get_orders',
+        description: 'List your recent orders — open, filled, cancelled, and partially filled. Costs $0.001 USDC.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pair: {
+                    type: 'string',
+                    description: 'Filter by trading pair. Leave empty to see all pairs.',
+                    enum: ['ETH-USDC', 'BTC-USDC'],
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Number of orders to return. Default 20, max 50.',
+                    default: 20,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'x402_get_recent_trades',
+        description: 'Get recent completed trades (fills) on a trading pair. Costs $0.001 USDC.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pair: {
+                    type: 'string',
+                    description: 'Trading pair. Supported: ETH-USDC, BTC-USDC',
+                    enum: ['ETH-USDC', 'BTC-USDC'],
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Number of recent trades to return. Default 20, max 50.',
+                    default: 20,
+                },
+            },
+            required: ['pair'],
+        },
+    },
+    {
+        name: 'x402_deposit_info',
+        description: 'Get instructions and the deposit address for adding USDC to your x402Trade balance.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+];
+// ── Tool Handlers ─────────────────────────────────────────────────────────────
+async function handleTool(name, args) {
+    switch (name) {
+        case 'x402_get_price': {
+            const pair = args.pair;
+            const data = await api('GET', `/ticker?pair=${pair}`);
+            return JSON.stringify({
+                pair,
+                price_usdc: data.price,
+                change_24h_pct: data.change24h,
+                volume_24h_usdc: data.volume24h,
+                high_24h: data.high24h,
+                low_24h: data.low24h,
+            }, null, 2);
+        }
+        case 'x402_get_orderbook': {
+            const pair = args.pair;
+            const depth = Math.min(args.depth || 10, 50);
+            const data = await api('GET', `/orderbook?pair=${pair}&depth=${depth}`);
+            return JSON.stringify(data, null, 2);
+        }
+        case 'x402_get_balance': {
+            if (!wallet)
+                return 'Error: PRIVATE_KEY not configured. Set PRIVATE_KEY env var to check balance.';
+            const data = await api('GET', '/balance');
+            return JSON.stringify({
+                wallet: wallet.address,
+                usdc_balance: data.usdc_balance,
+                usdc_locked_in_orders: data.usdc_locked,
+                eth_balance: data.eth_balance,
+                eth_locked_in_orders: data.eth_locked,
+            }, null, 2);
+        }
+        case 'x402_place_order': {
+            if (!wallet)
+                return 'Error: PRIVATE_KEY not configured. Cannot place orders without a wallet.';
+            const { pair, side, type, amount, price } = args;
+            if (type === 'limit' && !price)
+                return 'Error: price is required for limit orders.';
+            const data = await api('POST', '/trade', { pair, side, type, amount, price });
+            return JSON.stringify({
+                order_id: data.orderId,
+                status: data.status,
+                filled_amount: data.filledAmount,
+                avg_fill_price: data.avgPrice,
+                trades_count: data.trades?.length ?? 0,
+            }, null, 2);
+        }
+        case 'x402_cancel_order': {
+            if (!wallet)
+                return 'Error: PRIVATE_KEY not configured. Cannot cancel orders without a wallet.';
+            const orderId = args.order_id;
+            const data = await api('DELETE', `/orders/${orderId}`);
+            return JSON.stringify({
+                cancelled: data.success,
+                order_id: data.orderId,
+                remaining_amount_unlocked: data.remainingAmount,
+            }, null, 2);
+        }
+        case 'x402_get_orders': {
+            if (!wallet)
+                return 'Error: PRIVATE_KEY not configured. Cannot list orders without a wallet.';
+            const pair = args.pair;
+            const limit = Math.min(args.limit || 20, 50);
+            const qs = new URLSearchParams({ limit: String(limit) });
+            if (pair)
+                qs.set('pair', pair);
+            const data = await api('GET', `/orders?${qs}`);
+            return JSON.stringify(data, null, 2);
+        }
+        case 'x402_get_recent_trades': {
+            const pair = args.pair;
+            const limit = Math.min(args.limit || 20, 50);
+            const data = await api('GET', `/trades?pair=${pair}&limit=${limit}`);
+            return JSON.stringify(data, null, 2);
+        }
+        case 'x402_deposit_info': {
+            const walletAddr = wallet?.address ?? '(configure PRIVATE_KEY to see your wallet address)';
+            return JSON.stringify({
+                instructions: [
+                    '1. Send USDC to the deposit address below on Base L2 (Chain ID: 8453)',
+                    '2. Wait ~15 seconds for the transaction to confirm',
+                    '3. Your balance updates automatically — call x402_get_balance to verify',
+                ],
+                deposit_address: 'See DEPOSIT_ADDRESS in exchange config (ask the exchange operator)',
+                network: 'Base L2 (Ethereum Layer 2)',
+                token: 'USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bA02913C)',
+                your_wallet: walletAddr,
+                minimum_deposit: 'No minimum',
+                note: 'Only send USDC on Base L2. Sending on other networks will result in lost funds.',
+            }, null, 2);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+// ── MCP Server ────────────────────────────────────────────────────────────────
+const server = new Server({ name: 'x402trade', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const result = await handleTool(name, (args ?? {}));
+        return { content: [{ type: 'text', text: result }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[x402-mcp] Server started. Wallet: ${wallet?.address ?? 'not configured (read-only)'}\n`);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "x402trade-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for x402Trade — lets AI agents (Claude, Cursor, etc.) trade on x402Trade",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "x402-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "tsx src/__tests__/integration.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ethers": "^6.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}