hchain-mcp 1.0.0

package/docs/TRADE.md

@@ -0,0 +1,103 @@
+# Trade API — 知识总结
+
+> 来源: web3.okx.com 官方教程 · 对接日期 2026-06-14
+
+---
+
+## 经典兑换 API (8 endpoints, v6, 全部 GET)
+
+从 Solana/EVM/Sui/Ton 四个教程提取:
+
+| # | 端点 | 关键参数 |
+|---|------|---------|
+| 1 | `GET /api/v6/dex/aggregator/supported/chain` | 无 |
+| 2 | `GET /api/v6/dex/aggregator/all-tokens?chainIndex=` | chainIndex(String) |
+| 3 | `GET /api/v6/dex/aggregator/get-liquidity?chainIndex=` | chainIndex(String) |
+| 4 | `GET /api/v6/dex/aggregator/approve-transaction` | chainIndex, tokenContractAddress, approveAmount |
+| 5 | `GET /api/v6/dex/aggregator/quote` | chainIndex, fromTokenAddress, toTokenAddress, amount, slippagePercent |
+| 6 | `GET /api/v6/dex/aggregator/swap` | chainIndex, fromTokenAddress, toTokenAddress, amount, userWalletAddress, slippagePercent, autoSlippage, maxAutoSlippagePercent |
+| 7 | `GET /api/v6/dex/aggregator/swap-instruction` | chainIndex, fromTokenAddress, toTokenAddress, amount, slippagePercent, userWalletAddress, feePercent, autoSlippage, fromTokenReferrerWalletAddress, pathNum |
+| 8 | `GET /api/v6/dex/aggregator/history` | chainIndex, txHash, isFromMyProject |
+
+**关键**: chainIndex 全部是 **String** 类型 (如 "501", "8453", "1", "784", "607")
+
+## 兑换流程 (Agent 标准路径)
+
+```
+1. supported/chain → 确认链可用
+2. all-tokens / get-liquidity → 确认代币和流动性
+3. quote → 拿报价 (输出金额, 价格影响, 路由)
+4. approve-transaction → (仅 ERC-20) 授权 DEX 合约
+5. swap → 构建交易 calldata
+6. simulate (Gateway) → 模拟执行
+7. broadcast (Gateway) → 广播已签名交易
+8. history / orders → 追踪状态
+```
+
+## DEX SDK 接口参数 (Phase 2 参考)
+
+### getQuote / executeSwap 通用参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| chainIndex | String | 链ID |
+| fromTokenAddress | String | 卖出代币 |
+| toTokenAddress | String | 买入代币 |
+| amount | String | 数量(人类可读, SDK 内部转 base units) |
+| slippagePercent | String | 滑点, 如 "0.5" |
+| userWalletAddress | String | 钱包地址 |
+
+### executeApproval 参数 (EVM)
+
+| 参数 | 说明 |
+|------|------|
+| chainIndex / tokenContractAddress / approveAmount | 标准授权参数 |
+
+### swap-instruction 额外参数 (Solana 高级)
+
+| 参数 | 说明 |
+|------|------|
+| feePercent | 分佣百分比, 如 "1" |
+| autoSlippage | "true"/"false" |
+| fromTokenReferrerWalletAddress | 推荐费地址 |
+| pathNum | 最大路由数, 如 "3" |
+
+返回: `{ instructionLists, addressLookupTableAccount }`
+
+### 各链常量速查
+
+| 链 | chainIndex | 原生代币 |
+|----|-----------|---------|
+| Solana | "501" | `11111111111111111111111111111111` |
+| Sui | "784" | `0x2::sui::SUI` |
+| Base | "8453" | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` |
+| Ton | "607" | `EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c` |
+| BSC | "56" | `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` |
+
+## DEX Router 合约地址 (来源: 智能合约页面)
+
+| 链 | Router | Approve |
+|----|--------|---------|
+| ETH | `0x28b1Dc1a5E3699A428BC51d234DFab7C9CB2a183` | `0x40aA958dd87FC8305b97f2BA922CDdCa374bcD7f` |
+| Solana | `proVF4pMXVaYqmy4NjniPh4pqKNfMmsihgd4wdkCX3u` | 不需要 |
+| Base | `0xC8F6b8Ba0DC0f175B568B99440B0867F69A29265` | `0x57df6092665eb6058DE53939612413ff4B09114E` |
+| BSC | `0x62cceF0b4545166f721cAa9fEe13c1d3767E27dc` | `0x2c34A2Fb1d0b4f55de51E1d0bDEfaDDce6b7cDD6` |
+| Arbitrum | `0x7CF6b330b437E9fb432B1400DE17B03357Cf049A` | `0x70cBb871E8f30Fc8Ce23609E9E0Ea87B6b222F58` |
+| X Layer | `0x722db4f285F8bD91ef7AF6DA397e83f7fA4E80a7` | `0x8b773D83bc66Be128c60e07E17C8901f7a64F000` |
+| Sui | `0x4f1f29379f9fff73adb850ecf15513179d9b6a924e8c1d553d25582629778923` | 不需要 |
+| Ton | `EQAgvOlWk7C0Pz3YgSaX-MA7UDDhE9n6eQgQRwJahOBm4VKr` | 不需要 |
+
+完整列表见 docs/TRADE.md 源码
+
+## 做市商接入 / Solver 接入 — 反向集成
+
+做市商(PMM): OKX GET → 你的 `/OKXDEX/rfq/pricing` + POST → 你的 `/OKXDEX/rfq/firm-order`
+Solver: OKX POST → 你的 `/OKXDEX/intent/quote` + `/solve` + `/settle` + `/notify`
+
+均非 MCP Tool 可封装的 REST API。需自行实现端点供 OKX 调用。
+
+## 未对接模块
+
+- **意图兑换 API** (8 endpoints) — 官方 API 参考页面未贴
+- **意图交易 Solver** (7 endpoints) — 官方 API 参考页面未贴
+- **做市商接入** — SDK 反向集成, 非 REST

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "hchain-mcp",
+  "version": "1.0.0",
+  "description": "h-mcp — AI-native multi-chain trading MCP Server, 99 tools over HTTP & stdio",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "test": "npx tsx --test src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "dotenv": "^17.4.2",
+    "express": "^5.2.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/adapters/onchainos-ws.ts

@@ -0,0 +1,126 @@
+/**
+ * Onchain OS WebSocket 适配层
+ * wss://wsdex.okx.com/ws/v6/dex
+ *
+ * MCP Tool 限制: WS 是长连接推送, Tool 是请求-响应。
+ * 工具只管理连接生命周期 (subscribe/unsubscribe), 推送数据走 stderr 日志。
+ */
+import type { Auth } from "./shared.js";
+import crypto from "node:crypto";
+
+const WS_URL = "wss://wsdex.okx.com/ws/v6/dex";
+const PING_INTERVAL = 25000;
+
+// ── WebSocket Manager ─────────────────────────────────────
+
+type WSChannel =
+  | { channel: "price"; chainIndex: string; tokenContractAddress: string }
+  | { channel: "price-info"; chainIndex: string; tokenContractAddress: string }
+  | { channel: "trades"; chainIndex: string; tokenContractAddress: string }
+  | { channel: string; chainIndex: string; [key: string]: string };
+
+interface WSState { ws: WebSocket | null; connId: string | null; subscribed: Set<string>; }
+
+const state: WSState = { ws: null, connId: null, subscribed: new Set() };
+
+function channelKey(c: WSChannel): string { return `${c.channel}:${c.chainIndex}:${"tokenContractAddress" in c ? c.tokenContractAddress : ""}`; }
+
+function sign(secret: string, timestamp: string): string {
+  return crypto.createHmac("sha256", secret).update(timestamp + "GET" + "/users/self/verify").digest("base64");
+}
+
+function heartbeat(ws: WebSocket) {
+  const timer = setInterval(() => { if (ws.readyState === WebSocket.OPEN) ws.send("ping"); }, PING_INTERVAL);
+  ws.addEventListener("close", () => clearInterval(timer));
+}
+
+// ── Public API ──────────────────────────────────────────
+
+export async function wsConnect(auth: Auth): Promise<string> {
+  if (state.ws && state.ws.readyState === WebSocket.OPEN) return state.connId ?? "already-connected";
+
+  const timestamp = String(Math.floor(Date.now() / 1000));
+  const loginMsg = JSON.stringify({
+    op: "login",
+    args: [{ apiKey: auth.apiKey, passphrase: auth.passphrase, timestamp, sign: sign(auth.secret, timestamp) }],
+  });
+
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(WS_URL);
+    const timeout = setTimeout(() => { ws.close(); reject(new Error("WS connection timeout")); }, 10000);
+
+    ws.addEventListener("open", () => {
+      ws.send(loginMsg);
+    });
+
+    ws.addEventListener("message", (e: MessageEvent) => {
+      const data = JSON.parse(e.data as string);
+      if (data.event === "login" && data.code === "0") {
+        clearTimeout(timeout);
+        state.ws = ws;
+        state.connId = data.connId;
+        heartbeat(ws);
+        ws.addEventListener("message", (e2: MessageEvent) => {
+          const d = JSON.parse(e2.data as string);
+          if (d.event !== "login" && d.event !== "subscribe" && d.event !== "unsubscribe") {
+            console.error("[WS-DATA]", JSON.stringify(d));
+          }
+        });
+        resolve(data.connId);
+      } else if (data.event === "error") {
+        clearTimeout(timeout);
+        ws.close();
+        reject(new Error(`WS login failed: ${data.code} ${data.msg}`));
+      }
+    });
+
+    ws.addEventListener("error", (e) => { clearTimeout(timeout); reject(new Error(`WS error: ${JSON.stringify(e)}`)); });
+  });
+}
+
+export async function wsSubscribe(channel: WSChannel): Promise<void> {
+  if (!state.ws || state.ws.readyState !== WebSocket.OPEN) throw new Error("WS not connected, call ws_connect first");
+
+  const key = channelKey(channel);
+  if (state.subscribed.has(key)) return;
+
+  return new Promise((resolve, reject) => {
+    const handler = (e: MessageEvent) => {
+      const d = JSON.parse(e.data as string);
+      if (d.event === "subscribe" && d.arg?.channel === channel.channel) {
+        state.subscribed.add(key);
+        state.ws!.removeEventListener("message", handler);
+        resolve();
+      } else if (d.event === "error") {
+        state.ws!.removeEventListener("message", handler);
+        reject(new Error(`WS subscribe failed: ${d.code} ${d.msg}`));
+      }
+    };
+    state.ws!.addEventListener("message", handler);
+    state.ws!.send(JSON.stringify({ op: "subscribe", args: [channel] }));
+  });
+}
+
+export async function wsUnsubscribe(channel: WSChannel): Promise<void> {
+  if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return;
+
+  const key = channelKey(channel);
+  if (!state.subscribed.has(key)) return;
+
+  return new Promise((resolve) => {
+    const handler = (e: MessageEvent) => {
+      const d = JSON.parse(e.data as string);
+      if (d.event === "unsubscribe") {
+        state.subscribed.delete(key);
+        state.ws!.removeEventListener("message", handler);
+        resolve();
+      }
+    };
+    state.ws!.addEventListener("message", handler);
+    state.ws!.send(JSON.stringify({ op: "unsubscribe", args: [channel] }));
+  });
+}
+
+export function wsDisconnect(): void {
+  if (state.ws) { state.ws.close(); state.ws = null; state.connId = null; state.subscribed.clear(); }
+}