hchain-mcp 1.0.0

package/src/http.ts

@@ -0,0 +1,132 @@
+/**
+ * h-mcp Server — HTTP 传输层
+ * 规范: AGENT-MCP-RULES.md §12 (传输层透明 + 无状态)
+ * 使用 StreamableHTTPServerTransport (SDK 推荐), 废弃的 SSE transport 已跳过
+ *
+ * 使用原生 node:http 而非 Express, 避免 Express 5 与 @hono/node-server 兼容问题
+ */
+import "dotenv/config";
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Auth } from "./adapters/shared.js";
+import { registerBalanceTools } from "./tools/balance.js";
+import { registerGatewayTools } from "./tools/gateway.js";
+import { registerTxHistoryTools } from "./tools/txhistory.js";
+import { registerDefiTools } from "./tools/defi.js";
+import { registerPaymentsTools } from "./tools/payments.js";
+import { registerTradeTools } from "./tools/trade.js";
+import { registerIntentTools } from "./tools/intent.js";
+import { registerMarketTools } from "./tools/market.js";
+import { registerWsTools } from "./tools/ws.js";
+import { registerSkillTools } from "./tools/skills.js";
+
+function resolveAuth(): Auth | null {
+  const k = process.env.OKX_API_KEY, s = process.env.OKX_SECRET_KEY, p = process.env.OKX_PASSPHRASE;
+  if (k && s && p) return { apiKey: k, secret: s, passphrase: p };
+  const a = process.argv.slice(2), g = (f: string) => { const i = a.indexOf(f); return i >= 0 ? a[i + 1] : undefined; };
+  const ka = g("--okx-api-key") ?? g("-k"), sa = g("--okx-secret") ?? g("-s"), pa = g("--okx-passphrase") ?? g("-p");
+  if (ka && sa && pa) return { apiKey: ka, secret: sa, passphrase: pa };
+  return null;
+}
+
+/** 简陋 body parser — 读 JSON body 到 req.body */
+function jsonBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", c => chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString();
+      try { resolve(raw ? JSON.parse(raw) : undefined); }
+      catch { reject(new Error("Invalid JSON body")); }
+    });
+    req.on("error", reject);
+  });
+}
+
+async function main() {
+  const auth = resolveAuth();
+  if (!auth) {
+    console.error("[h-mcp] 未配置 API Key。设置 OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE");
+    console.error("[h-mcp] 获取: https://web3.okx.com/onchainos/dev-portal");
+  } else {
+    console.error("[h-mcp] Auth 已配置");
+  }
+
+  const host = process.env.HOST ?? "127.0.0.1";
+  const port = parseInt(process.env.PORT ?? "3000", 10);
+
+  // 1. 创建 HTTP transport (有状态模式, 自动生成 sessionId)
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  });
+
+  // 2. MCP Server + 全部工具注册
+  const server = new McpServer({ name: "hchain-mcp", version: "1.0.0" });
+
+  registerBalanceTools(server, auth);
+  registerGatewayTools(server, auth);
+  registerTxHistoryTools(server, auth);
+  registerDefiTools(server, auth);
+  registerPaymentsTools(server, auth);
+  registerTradeTools(server, auth);
+  registerIntentTools(server, auth);
+  registerMarketTools(server, auth);
+  registerWsTools(server, auth);
+  registerSkillTools(server, auth);
+
+  // 3. 连接 server 到 HTTP transport
+  await server.connect(transport);
+
+  // 4. 原生 HTTP server
+  const httpServer = createServer(async (req, res) => {
+    // CORS
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, MCP-Protocol-Version");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // 健康检查
+    if (req.method === "GET" && req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", tsIso: new Date().toISOString() }));
+      return;
+    }
+
+    // MCP 端点
+    if (req.url === "/mcp" || req.url?.startsWith("/mcp")) {
+      try {
+        let body: unknown;
+        if (req.method === "POST") {
+          body = await jsonBody(req);
+        }
+        await transport.handleRequest(req, res, body);
+      } catch (e) {
+        console.error("[h-mcp] handleRequest error:", e);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+      }
+      return;
+    }
+
+    // 404
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+
+  httpServer.listen(port, host, () => {
+    console.error(`[h-mcp] HTTP MCP Server 已启动 → http://${host}:${port}`);
+    console.error(`[h-mcp] MCP endpoint: POST http://${host}:${port}/mcp`);
+    console.error(`[h-mcp] Health check: GET  http://${host}:${port}/health`);
+  });
+}
+
+main().catch(e => { console.error("[h-mcp] 启动失败:", e); process.exit(1); });

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * h-mcp Server — stdio 传输
+ * 规范: OnchainOS-API对接规范.md §五
+ */
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Auth } from "./adapters/shared.js";
+import { registerBalanceTools } from "./tools/balance.js";
+import { registerGatewayTools } from "./tools/gateway.js";
+import { registerTxHistoryTools } from "./tools/txhistory.js";
+import { registerDefiTools } from "./tools/defi.js";
+import { registerPaymentsTools } from "./tools/payments.js";
+import { registerTradeTools } from "./tools/trade.js";
+import { registerIntentTools } from "./tools/intent.js";
+import { registerMarketTools } from "./tools/market.js";
+import { registerWsTools } from "./tools/ws.js";
+import { registerSkillTools } from "./tools/skills.js";
+
+function resolveAuth(): Auth | null {
+  const k = process.env.OKX_API_KEY, s = process.env.OKX_SECRET_KEY, p = process.env.OKX_PASSPHRASE;
+  if (k && s && p) return { apiKey: k, secret: s, passphrase: p };
+  const a = process.argv.slice(2), g = (f: string) => { const i = a.indexOf(f); return i >= 0 ? a[i + 1] : undefined; };
+  const ka = g("--okx-api-key") ?? g("-k"), sa = g("--okx-secret") ?? g("-s"), pa = g("--okx-passphrase") ?? g("-p");
+  if (ka && sa && pa) return { apiKey: ka, secret: sa, passphrase: pa };
+  return null;
+}
+
+async function main() {
+  const auth = resolveAuth();
+  if (!auth) {
+    console.error("[h-mcp] 未配置 API Key。设置 OKX_API_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE");
+    console.error("[h-mcp] 获取: https://web3.okx.com/onchainos/dev-portal");
+  } else {
+    console.error("[h-mcp] Auth 已配置");
+  }
+
+  const server = new McpServer({ name: "hchain-mcp", version: "1.0.0" });
+
+  // 逐模块注册工具 (按官方文档对接)
+  registerBalanceTools(server, auth);
+  registerGatewayTools(server, auth);
+  registerTxHistoryTools(server, auth);
+  registerDefiTools(server, auth);
+  registerPaymentsTools(server, auth);
+  registerTradeTools(server, auth);
+  registerIntentTools(server, auth);
+  registerMarketTools(server, auth);
+  registerWsTools(server, auth);
+  registerSkillTools(server, auth);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[h-mcp] 就绪");
+}
+
+main().catch(e => { console.error("[h-mcp] 启动失败:", e); process.exit(1); });

package/src/tools/balance.ts

@@ -0,0 +1,67 @@
+/**
+ * Balance 模块 — CAT:[链上-账户]
+ * 按官方文档逐端点对接
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { balanceApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerBalanceTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_balance_supported_chain",
+    "CAT:[链上-账户] | ## 功能: 获取余额 API 支持的链, 返回 chainIndex(字符串)/name/shortName/logoUrl\n## 场景: Agent 在查余额前先调此工具确认目标链的 chainIndex 值\n## 关键词: 余额, 链列表, chainIndex, balance\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: 本工具 -> onchainos_balance_total_value(总估值) / onchainos_balance_all_tokens(资产明细)",
+    {}, { readOnlyHint: true },
+    async () => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await balanceApi.supportedChain(auth)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_balance_total_value",
+    "CAT:[链上-账户] | ## 功能: 获取地址的总资产 USD 估值(代币+DeFi)\n## 场景: Agent 拿到钱包地址后第一步 - 快速了解总资产\n## 关键词: 总资产, total value, USD, 估值\n## 参数:\n##   - address: 钱包地址(必填)\n##   - chains: 链索引逗号分隔, 最多50个(必填)\n##   - assetType: 资产类型(可选)\n##   - excludeRiskToken: 是否过滤风险代币(可选, 默认true)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~1KB\n## 关联: onchainos_balance_supported_chain -> 本工具总览 -> onchainos_balance_all_tokens(明细)",
+    {
+      address: z.string().describe("钱包地址。Agent 从用户输入或上下文获取"),
+      chains: z.string().describe("链索引, 逗号分隔, 最多50个。如 '1'=ETH '56'=BSC '501'=Solana。从 onchainos_balance_supported_chain 获取 chainIndex"),
+      assetType: z.enum(["0","1","2"]).optional().describe("资产类型: 不传默认所有, '0'=代币+DeFi, '1'=仅代币, '2'=仅DeFi"),
+      excludeRiskToken: z.boolean().optional().describe("过滤风险/貔貅代币。不传默认过滤, false 传不过滤"),
+    },
+    { readOnlyHint: true },
+    async ({ address, chains, assetType, excludeRiskToken }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await balanceApi.totalValue(auth, address, chains, assetType, excludeRiskToken)); } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_balance_all_tokens",
+    "CAT:[链上-账户] | ## 功能: 获取地址的代币持仓明细, 返回 symbol/balance/tokenPrice/isRiskToken/chainIndex\n## 场景: 用户问持仓有什么币时调用, 返回所有代币余额+美元价值\n## 关键词: 持仓, 代币余额, token balance, 资产明细\n## 参数:\n##   - address: 钱包地址(必填)\n##   - chains: 链索引逗号分隔, 最多50个(必填)\n##   - excludeRiskToken: 风险代币过滤(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_balance_total_value(总览) -> 本工具明细 -> onchainos_balance_specific_token(精确查)",
+    {
+      address: z.string().describe("钱包地址。Agent 从用户输入或上下文获取"),
+      chains: z.string().describe("链索引, 逗号分隔, 最多50个。如 '1'=ETH '56'=BSC。从 onchainos_balance_supported_chain 获取"),
+      excludeRiskToken: z.enum(["0","1"]).optional().describe("'0'=过滤风险/貔貅代币(默认), '1'=不过滤"),
+    },
+    { readOnlyHint: true },
+    async ({ address, chains, excludeRiskToken }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await balanceApi.allTokenBalances(auth, address, chains, excludeRiskToken)); } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_balance_specific_token",
+    "CAT:[链上-账户] | ## 功能: 批量查询指定代币余额(最多20个), 每个代币可指定不同链\n## 场景: 查一个或多个特定代币的余额。tokenContractAddress 传空字符串查主链币(ETH/SOL等)\n## 关键词: 代币余额, specific token, 批量, 精确, tokenContractAddress\n## 参数:\n##   - address: 钱包地址(必填)\n##   - tokens: JSON数组 [{\"chainIndex\":\"1\",\"tokenContractAddress\":\"0x...\"},...], 最多20个\n##   - excludeRiskToken: 风险代币过滤(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~5KB\n## 关联: onchainos_token_search 拿地址 -> 构造 tokens 数组 -> 本工具 -> 返回 symbol/balance/tokenPrice/isRiskToken",
+    {
+      address: z.string().describe("钱包地址。Agent 从用户输入或上下文获取"),
+      tokens: z.string().describe("JSON 数组字符串。格式: [{\"chainIndex\":\"1\",\"tokenContractAddress\":\"0xabc...\"},{\"chainIndex\":\"56\",\"tokenContractAddress\":\"\"}]。chainIndex 用字符串, 主链币传空字符串。最多20个"),
+      excludeRiskToken: z.enum(["0","1"]).optional().describe("'0'=过滤风险/貔貅代币(默认), '1'=不过滤"),
+    },
+    { readOnlyHint: true },
+    async ({ address, tokens, excludeRiskToken }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        let parsed: Array<{ chainIndex: string; tokenContractAddress: string }>;
+        try { parsed = JSON.parse(tokens); } catch { return toError(new Error("tokens 格式错误: 需要 JSON 数组, 例 [{\"chainIndex\":\"1\",\"tokenContractAddress\":\"0xabc...\"}]")); }
+        if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > 20) return toError(new Error("tokens 需为非空数组且最多20个元素"));
+        return toResult(await balanceApi.specificTokenBalance(auth, address, parsed, excludeRiskToken));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+}

package/src/tools/defi.ts

@@ -0,0 +1,224 @@
+/**
+ * DeFi 模块 — CAT:[链上-分析]
+ * 投资品查询: 链列表 + 协议 + 搜索 + 详情
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { defiApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerDefiTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_defi_supported_chains",
+    "CAT:[链上-分析] | ## 功能: 获取 DeFi 投资品覆盖的链, 返回 chainIndex(字符串)+network\n## 场景: 搜索/投资 DeFi 产品前确认目标链是否被覆盖\n## 关键词: DeFi, 链列表, chainIndex, network\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: 本工具 -> onchainos_defi_supported_platforms / onchainos_defi_search_products",
+    {}, { readOnlyHint: true },
+    async () => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.supportedChains(auth)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_supported_platforms",
+    "CAT:[链上-分析] | ## 功能: 获取 DeFi 协议列表+统计, 返回 analysisPlatformId/platformName/investmentCount\n## 场景: 了解支持哪些协议, 每个协议有多少投资品\n## 关键词: DeFi, 协议, platform, Aave, Lido\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~5KB\n## 关联: onchainos_defi_supported_chains -> 本工具 -> onchainos_defi_search_products(按协议搜索)",
+    {}, { readOnlyHint: true },
+    async () => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.supportedPlatforms(auth)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_search_products",
+    "CAT:[链上-分析] | ## 功能: 按代币/协议/链搜索 DeFi 投资品, 返回 investmentId/name/platformName/rate(APY)/tvl/feeRate\n## 场景: 用户想投 DeFi 时第一步 — 搜索可投产品\n## 关键词: DeFi, 搜索, 投资品, APY, TVL, product\n## 参数:\n##   - tokenKeywordList: 代币关键词数组(必填, 如[\"USDC\",\"ETH\"])\n##   - platformKeywordList: 协议关键词(可选)\n##   - pageNum: 页码(可选, 默认1, pageSize=20)\n##   - chainIndex: 链ID字符串(可选)\n##   - productGroup: 投资类型(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: 本工具拿到 investmentId -> onchainos_defi_product_detail(详情) -> 交易执行",
+    {
+      tokenKeywordList: z.string().describe("代币关键词 JSON 数组字符串。如 '[\"USDC\",\"ETH\"]'"),
+      platformKeywordList: z.string().optional().describe("协议关键词 JSON 数组字符串。如 '[\"Aave V3\"]'"),
+      pageNum: z.number().int().min(1).optional().describe("页码, 最小1, 每页20条。默认1"),
+      chainIndex: z.string().optional().describe("链ID(字符串)。如 '1'=ETH '8453'=Base。不传查所有链"),
+      productGroup: z.enum(["SINGLE_EARN","DEX_POOL","LENDING"]).optional().describe("投资类型: SINGLE_EARN=单币赚币 DEX_POOL=流动性池 LENDING=借贷"),
+    },
+    { readOnlyHint: true },
+    async ({ tokenKeywordList, platformKeywordList, pageNum, chainIndex, productGroup }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        let tokens: string[]; try { tokens = JSON.parse(tokenKeywordList); } catch { return toError(new Error("tokenKeywordList 格式错误: 需要 JSON 数组, 如 '[\"USDC\"]'")); }
+        let platforms: string[] | undefined;
+        if (platformKeywordList) { try { platforms = JSON.parse(platformKeywordList); } catch { return toError(new Error("platformKeywordList 格式错误: 需要 JSON 数组")); } }
+        return toResult(await defiApi.searchProducts(auth, { tokenKeywordList: tokens, platformKeywordList: platforms, pageNum, chainIndex, productGroup }));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_defi_product_detail",
+    "CAT:[链上-分析] | ## 功能: 获取投资品完整信息, 含 APY 明细/底层资产/isSupportClaim/isInvestable/isSupportRedeem\n## 场景: 用户选好产品后查看详情, 判断可执行操作(投资/赎回/领取奖励)\n## 关键词: DeFi, 投资品详情, APY, TVL, underlyingToken\n## 参数:\n##   - investmentId: 投资品ID(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~5KB\n## 关联: onchainos_defi_search_products -> 本工具 -> 根据 isInvestable/isSupportRedeem 决定下一步",
+    {
+      investmentId: z.string().describe("投资品ID。从 onchainos_defi_search_products 返回值的 investmentId 字段获取"),
+    },
+    { readOnlyHint: true },
+    async ({ investmentId }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.productDetail(auth, investmentId)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_rate_chart",
+    "CAT:[链上-分析] | ## 功能: 获取投资品历史 APY 折线图数据, 返回 timestamp/rate/bonusRate/totalReward\n## 场景: 查看收益率走势, 判断最佳入场时机\n## 关键词: APY, 折线图, rate, 收益率, chart\n## 参数:\n##   - investmentId: 投资品ID(必填)\n##   - timeRange: 时间范围(可选, 默认WEEK)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_defi_product_detail -> 本工具",
+    {
+      investmentId: z.string().describe("投资品ID。从 onchainos_defi_search_products 返回值获取"),
+      timeRange: z.enum(["WEEK","MONTH","SEASON","YEAR"]).optional().describe("时间范围: WEEK=一周 MONTH=一月 SEASON=三月 YEAR=一年。默认WEEK"),
+    },
+    { readOnlyHint: true },
+    async ({ investmentId, timeRange }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.rateChart(auth, investmentId, timeRange)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_tvl_chart",
+    "CAT:[链上-分析] | ## 功能: 获取投资品历史 TVL 折线图数据, 返回 chartVos[{timestamp,tvl,limitValue}]\n## 场景: 评估投资品规模变化趋势, TVL 增长=市场信心增强\n## 关键词: TVL, 折线图, 锁仓量, chart\n## 参数:\n##   - investmentId: 投资品ID(必填)\n##   - timeRange: 时间范围(可选, 默认WEEK)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_defi_product_detail -> 本工具",
+    {
+      investmentId: z.string().describe("投资品ID"),
+      timeRange: z.enum(["WEEK","MONTH","SEASON","YEAR"]).optional().describe("时间范围。默认WEEK"),
+    },
+    { readOnlyHint: true },
+    async ({ investmentId, timeRange }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.tvlChart(auth, investmentId, timeRange)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_depth_price_chart",
+    "CAT:[链上-分析] | ## 功能: 获取 V3 Pool 流动性深度图或价格历史图。仅适用于 V3 DEX Pool\n## 场景: 分析 V3 池子流动性分布, 判断大额交易滑点\n## 关键词: V3, depth, 深度图, 价格图, liquidity\n## 参数:\n##   - investmentId: 投资品ID(必填)\n##   - chartType: 图表类型(可选, 默认DEPTH)\n##   - timeRange: 时间范围(可选, chartType=PRICE时生效)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~20KB\n## 关联: onchainos_defi_product_detail -> 本工具(仅V3 Pool)",
+    {
+      investmentId: z.string().describe("投资品ID"),
+      chartType: z.enum(["DEPTH","PRICE"]).optional().describe("图表类型: DEPTH=深度图(默认) PRICE=价格历史图"),
+      timeRange: z.enum(["DAY","WEEK"]).optional().describe("时间范围(仅chartType=PRICE时生效): DAY=24h WEEK=1周。默认DAY"),
+    },
+    { readOnlyHint: true },
+    async ({ investmentId, chartType, timeRange }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.depthPriceChart(auth, investmentId, chartType, timeRange)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_prepare_transaction",
+    "CAT:[链上-分析] | ## 功能: 申购/赎回前的参数准备, 返回可投币种(investWithTokenList)/凭证代币(receiveTokenInfo)/收益代币(gainsTokenList)\n## 场景: 调用 enter/exit 前必调, 确认可投什么币/收到什么凭证\n## 关键词: DeFi, prepare, 参数准备, investWithToken, receiveToken\n## 参数:\n##   - investmentId: 投资品ID(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~5KB\n## 关联: onchainos_defi_product_detail -> 本工具 -> onchainos_defi_enter(申购) / onchainos_defi_exit(赎回)",
+    { investmentId: z.string().describe("投资品ID。从 onchainos_defi_search_products 返回值获取") },
+    { readOnlyHint: true },
+    async ({ investmentId }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.prepareTransaction(auth, investmentId)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_calc_enter_info",
+    "CAT:[链上-分析] | ## 功能: V3 Pool 双币分配计算 - 输入单币金额+tick区间, 返回双币各需投入数量\n## 场景: V3 Pool 申购前计算 token0/token1 分配比例\n## 关键词: V3, 双币分配, calculator, tick, enter info\n## 参数:\n##   - inputAmount/inputTokenAddress/tokenDecimal/investmentId/address/tickLower/tickUpper(全部必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: onchainos_defi_prepare_transaction -> 本工具(仅V3 Pool) -> onchainos_defi_enter",
+    {
+      inputAmount: z.string().describe("单币金额, 人类可读(如'0.05')"),
+      inputTokenAddress: z.string().describe("输入的代币合约地址。可以是 V3 Pool 的 token0 或 token1"),
+      tokenDecimal: z.string().describe("输入代币精度(如'18','6')"),
+      investmentId: z.string().describe("投资品ID"),
+      address: z.string().describe("用户钱包地址"),
+      tickLower: z.string().describe("V3 tick 下限(如'-33500')"),
+      tickUpper: z.string().describe("V3 tick 上限(如'-30450')"),
+    },
+    { readOnlyHint: true },
+    async (params) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await defiApi.calcEnterInfo(auth, params)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_defi_enter",
+    "CAT:[链上-分析] | ## 功能: DeFi 申购/存款/借款, 返回顺序执行的 calldata 列表(APPROVE->DEPOSIT)\n## 场景: 准备好参数后执行投资操作\n## 关键词: DeFi, 申购, enter, deposit, borrow, calldata\n## 参数:\n##   - investmentId/address(必填)\n##   - userInputList: 投入代币 JSON 数组(必填)\n##   - tickLower/tickUpper: V3 Pool 参数(可选)\n##   - tokenId: V3 NFT position ID(可选)\n##   - slippage: 滑点(可选, 默认0.01=1%)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata, 需签名后广播\n## 返回量: 中等 ~5KB\n## 关联: onchainos_defi_prepare_transaction -> 本工具 -> onchainos_gateway_broadcast",
+    {
+      investmentId: z.string().describe("投资品ID"),
+      address: z.string().describe("用户钱包地址"),
+      userInputList: z.string().describe("投入代币 JSON 数组。如 '[{\"tokenAddress\":\"0x...\",\"chainIndex\":\"1\",\"coinAmount\":\"0.05\"}]'。从 onchainos_defi_prepare_transaction 的 investWithTokenList 获取"),
+      tickLower: z.string().optional().describe("V3 tick 下限。仅 Dex Pool 新建仓位时需要"),
+      tickUpper: z.string().optional().describe("V3 tick 上限。仅 Dex Pool 新建仓位时需要"),
+      tokenId: z.string().optional().describe("V3 NFT position token ID。向已有仓位追加时必传"),
+      slippage: z.string().optional().describe("滑点。'0.01'=1% '0.1'=10%。默认'0.01'"),
+    },
+    { destructiveHint: true },
+    async ({ investmentId, address, userInputList, tickLower, tickUpper, tokenId, slippage }) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        let input: unknown; try { input = JSON.parse(userInputList); } catch { return toError(new Error("userInputList 格式错误: 需要 JSON 数组")); }
+        const data = await defiApi.enter(auth, {
+          investmentId, address, userInputList: input,
+          ...(tickLower ? { tickLower } : {}), ...(tickUpper ? { tickUpper } : {}),
+          ...(tokenId ? { tokenId } : {}), slippage,
+        });
+        return toResult(data, {
+          nextSteps: [
+            { action: "按 dataList 顺序执行: APPROVE->签名->广播, 然后 DEPOSIT->签名->广播", tool: "onchainos_gateway_broadcast", condition: "dataList 中每个元素是一个交易步骤" },
+          ],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_defi_exit",
+    "CAT:[链上-分析] | ## 功能: DeFi 赎回/还款, 返回顺序执行的 calldata 列表\n## 场景: 退出投资或偿还借款\n## 关键词: DeFi, 赎回, exit, withdraw, repay, calldata\n## 参数:\n##   - investmentId/address(必填)\n##   - redeemPercent: 赎回比例(建议传, \"1\"=100%)\n##   - userInputList: 输入代币 JSON(可选)\n##   - tokenId: V3 NFT position ID(V3赎回必传)\n##   - slippage: 滑点(可选)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 中等 ~5KB\n## 关联: onchainos_defi_prepare_transaction -> 本工具 -> onchainos_gateway_broadcast",
+    {
+      investmentId: z.string().describe("投资品ID"),
+      address: z.string().describe("用户钱包地址"),
+      redeemPercent: z.string().optional().describe("赎回比例, 建议必传。'1'=100% '0.5'=50%。不传可能导致 aToken 动态余额 revert"),
+      userInputList: z.string().optional().describe("输入代币 JSON 数组。Farm/v2pool 传 LP Token, 其他情况传目标接收 token"),
+      tokenId: z.string().optional().describe("V3 NFT position token ID。V3 Pool 赎回必传"),
+      slippage: z.string().optional().describe("滑点。默认'0.01'"),
+    },
+    { destructiveHint: true },
+    async ({ investmentId, address, redeemPercent, userInputList, tokenId, slippage }) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        const body: Record<string, unknown> = { investmentId, address };
+        if (redeemPercent) body.redeemPercent = redeemPercent;
+        if (userInputList) { try { body.userInputList = JSON.parse(userInputList); } catch { return toError(new Error("userInputList 格式错误")); } }
+        if (tokenId) body.tokenId = tokenId;
+        if (slippage) body.slippage = slippage;
+        return toResult(await defiApi.exit(auth, body), {
+          nextSteps: [{ action: "按 dataList 顺序签名并广播", tool: "onchainos_gateway_broadcast" }],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_defi_claim",
+    "CAT:[链上-分析] | ## 功能: 领取 DeFi 协议奖励(矿币/手续费/Bonus/到期本金)\n## 场景: 定期领取 DeFi 投资收益\n## 关键词: DeFi, claim, 奖励, reward, bonus, 领取\n## 参数:\n##   - address(必填)\n##   - rewardType: 奖励类型(必填, 见描述)\n##   - investmentId: 投资品ID(大部分类型必传)\n##   - analysisPlatformId/tokenId/principalIndex: 按 rewardType 选填\n##   - expectOutputList: 预期输出 JSON(REWARD_MERKLE_BONUS 用)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 微小 ~3KB\n## 关联: onchainos_defi_user_platform_list -> 本工具",
+    {
+      address: z.string().describe("用户钱包地址"),
+      rewardType: z.enum(["REWARD_INVESTMENT","REWARD_PLATFORM","V3_FEE","REWARD_OKX_BONUS","REWARD_MERKLE_BONUS","UNLOCKED_PRINCIPAL"]).describe("奖励类型: REWARD_INVESTMENT=矿币奖励 REWARD_PLATFORM=协议奖励 V3_FEE=V3手续费 REWARD_OKX_BONUS=OKX Bonus REWARD_MERKLE_BONUS=Merkle Bonus UNLOCKED_PRINCIPAL=到期本金"),
+      investmentId: z.string().optional().describe("投资品ID。除 REWARD_PLATFORM 外都需传"),
+      analysisPlatformId: z.string().optional().describe("协议ID。REWARD_PLATFORM 时填写"),
+      tokenId: z.string().optional().describe("V3 仓位 tokenId。V3_FEE 时填写"),
+      principalIndex: z.string().optional().describe("到期订单 index。UNLOCKED_PRINCIPAL 时填写"),
+      expectOutputList: z.string().optional().describe("预期输出 JSON 数组。REWARD_MERKLE_BONUS 时填写, 如 '[{\"chainIndex\":\"1\",\"tokenAddress\":\"0x...\",\"coinAmount\":\"0.001\"}]'"),
+    },
+    { destructiveHint: true },
+    async ({ address, rewardType, investmentId, analysisPlatformId, tokenId, principalIndex, expectOutputList }) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        const body: Record<string, unknown> = { address, rewardType };
+        if (investmentId) body.investmentId = investmentId;
+        if (analysisPlatformId) body.analysisPlatformId = analysisPlatformId;
+        if (tokenId) body.tokenId = tokenId;
+        if (principalIndex) body.principalIndex = principalIndex;
+        if (expectOutputList) { try { body.expectOutputList = JSON.parse(expectOutputList); } catch { return toError(new Error("expectOutputList 格式错误")); } }
+        return toResult(await defiApi.claim(auth, body));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_defi_user_platform_list",
+    "CAT:[链上-分析] | ## 功能: 查询用户在各 DeFi 协议的持仓概览, 返回 platformName/analysisPlatformId/currencyAmount(USD)/investmentCount\n## 场景: 用户想看 DeFi 资产分布时第一步 - 按协议汇总\n## 关键词: DeFi, 持仓, 协议, platform, asset, portfolio\n## 参数:\n##   - walletAddressList: 钱包地址 JSON 数组(必填)\n##   - tag: 自定义标签(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~20KB\n## 关联: 本工具拿 analysisPlatformId -> onchainos_defi_user_platform_detail(明细) -> onchainos_defi_exit/claim",
+    {
+      walletAddressList: z.string().describe("钱包地址 JSON 数组。如 '[{\"chainIndex\":\"1\",\"walletAddress\":\"0x...\"},{\"chainIndex\":\"56\",\"walletAddress\":\"0x...\"}]'。支持多链多钱包"),
+      tag: z.string().optional().describe("自定义标签, 用于标记查询"),
+    },
+    { readOnlyHint: true },
+    async ({ walletAddressList, tag }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        let list: Array<{ chainIndex: string; walletAddress: string; pubKey?: string }>;
+        try { list = JSON.parse(walletAddressList); } catch { return toError(new Error("walletAddressList 格式错误: 需要 JSON 数组")); }
+        return toResult(await defiApi.userPlatformList(auth, { walletAddressList: list, ...(tag ? { tag } : {}) }));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_defi_user_platform_detail",
+    "CAT:[链上-分析] | ## 功能: 查询用户在某协议的详细持仓, 返回每个投资品的仓位/资产/奖励详情\n## 场景: 看某个协议的具体投资分布、可领取奖励、仓位状态\n## 关键词: DeFi, 持仓明细, position, reward, availableRewards\n## 参数:\n##   - walletAddressList: 钱包地址 JSON 数组(必填)\n##   - platformList: 协议 JSON 数组(必填, 含 chainIndex+analysisPlatformId)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_defi_user_platform_list -> 本工具 -> onchainos_defi_claim(领奖励)/onchainos_defi_exit(赎回)",
+    {
+      walletAddressList: z.string().describe("钱包地址 JSON 数组。如 '[{\"chainIndex\":\"1\",\"walletAddress\":\"0x...\"}]'"),
+      platformList: z.string().describe("协议 JSON 数组。如 '[{\"chainIndex\":\"1\",\"analysisPlatformId\":\"44\"}]'。analysisPlatformId 从 onchainos_defi_user_platform_list 获取"),
+    },
+    { readOnlyHint: true },
+    async ({ walletAddressList, platformList }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        let wallets: unknown; try { wallets = JSON.parse(walletAddressList); } catch { return toError(new Error("walletAddressList 格式错误")); }
+        let platforms: unknown; try { platforms = JSON.parse(platformList); } catch { return toError(new Error("platformList 格式错误")); }
+        return toResult(await defiApi.userPlatformDetail(auth, { walletAddressList: wallets, platformList: platforms }));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+}

package/src/tools/gateway.ts

@@ -0,0 +1,115 @@
+/**
+ * Gateway 模块 — CAT:[链上-网关]
+ * 交易上链: Gas预估 + 模拟 + 广播
+ */
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { gatewayApi, postTxApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+import type { Auth } from "../adapters/shared.js";
+
+export function registerGatewayTools(server: McpServer, auth: Auth | null): void {
+
+  server.tool("onchainos_gateway_supported_chain",
+    "CAT:[链上-网关] | ## 功能: 获取交易上链 API 支持的链, 返回 chainIndex(字符串)/name/shortName\n## 场景: Agent 广播/查gas前确认目标链是否被 Gateway 支持\n## 关键词: gateway, 链列表, chainIndex, broadcast\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: 本工具 -> onchainos_gateway_gas_price / onchainos_gateway_broadcast",
+    {}, { readOnlyHint: true },
+    async () => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await gatewayApi.supportedChain(auth)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_gateway_gas_price",
+    "CAT:[链上-网关] | ## 功能: 获取指定链的 Gas Price 推荐值(低/中/高三档)\n## 场景: 交易前估算 gas 成本。EVM链返回 normal/min/max(wei) + EIP1559字段, Solana返回 priorityFee 各档位(microlamports)\n## 关键词: gas price, 矿工费, 成本, EIP1559, priority fee\n## 参数:\n##   - chainIndex: 链索引字符串(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~1KB\n## 关联: onchainos_gateway_supported_chain -> 本工具 -> onchainos_gateway_gas_limit(估limit) / onchainos_gateway_simulate(模拟)",
+    {
+      chainIndex: z.string().describe("链索引(字符串)。'1'=ETH '56'=BSC '501'=Solana。从 onchainos_gateway_supported_chain 获取"),
+    },
+    { readOnlyHint: true },
+    async ({ chainIndex }) => { if(!auth) return AUTH_REQUIRED("READ"); try { return toResult(await gatewayApi.gasPrice(auth, chainIndex)); } catch(e) { return toError(e); } },
+  );
+
+  server.tool("onchainos_gateway_gas_limit",
+    "CAT:[链上-网关] | ## 功能: 预执行交易获取预估 Gas Limit\n## 场景: 知道 gas 用量后计算总费用 = gasPrice * gasLimit\n## 关键词: gas limit, 用量预估, 费用\n## 参数:\n##   - chainIndex: 链索引(必填)\n##   - fromAddress: 发送方地址(必填)\n##   - toAddress: 接收方/合约地址(必填)\n##   - txAmount: 主链币数量(可选, wei单位)\n##   - extJson.inputData: calldata(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~1KB\n## 关联: onchainos_gateway_gas_price -> 本工具 -> onchainos_gateway_simulate",
+    {
+      chainIndex: z.string().describe("链索引(字符串)。从 onchainos_gateway_supported_chain 获取"),
+      fromAddress: z.string().describe("发送方地址(钱包地址)"),
+      toAddress: z.string().describe("接收方地址。转账=代币地址/钱包地址, 兑换=OKX DEX router地址, 授权=代币地址"),
+      txAmount: z.string().optional().describe("主链币金额(wei单位)。主链币交易时填数量, 代币交易填'0'。可从 swap 返回值 tx.value 获取"),
+      inputData: z.string().optional().describe("calldata(hex)。从 swap/approve 返回值获取"),
+    },
+    { readOnlyHint: true },
+    async ({ chainIndex, fromAddress, toAddress, txAmount, inputData }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        const extJson = inputData ? { inputData } : undefined;
+        return toResult(await gatewayApi.gasLimit(auth, { chainIndex, fromAddress, toAddress, txAmount, extJson }));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_gateway_simulate",
+    "CAT:[链上-网关] | ## 功能: 模拟执行交易, 不消耗 gas, 返回资产变化/failReason/risks\n## 场景: 广播前必调 - 验证交易是否 revert、资产变化是否符合预期。需白名单, 联系 dexapi@okx.com\n## 关键词: 模拟, simulate, 预执行, 资产变化, failReason, 风险\n## 参数:\n##   - fromAddress: 发送方(必填)\n##   - toAddress: 接收方/合约(必填)\n##   - chainIndex: 链索引字符串(必填)\n##   - inputData: calldata hex(必填)\n##   - txAmount: 主链币金额 wei(可选, 默认0)\n##   - gasPrice: gas price(可选)\n##   - priorityFee: Solana优先费(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 仅模拟, 不上链\n## 返回量: 微小 ~3KB\n## 关联: onchainos_gateway_gas_limit -> 本工具模拟 -> 模拟通过后 onchainos_gateway_broadcast",
+    {
+      fromAddress: z.string().describe("发送方地址(钱包地址)"),
+      toAddress: z.string().describe("接收方地址。兑换=OKX DEX router, 授权=代币地址"),
+      chainIndex: z.string().describe("链索引(字符串)。如 '1'=ETH '501'=Solana"),
+      inputData: z.string().describe("calldata(hex, base58编码)。从 swap/approve 返回值获取"),
+      txAmount: z.string().optional().describe("主链币金额(wei)。主链币交易填数量, 代币交易填'0'"),
+      gasPrice: z.string().optional().describe("Gas price(wei), 不填用当前网络价"),
+      priorityFee: z.string().optional().describe("优先费。仅 Solana, 单位 microlamports"),
+    },
+    { readOnlyHint: true },
+    async ({ fromAddress, toAddress, chainIndex, inputData, txAmount, gasPrice, priorityFee }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try {
+        return toResult(await gatewayApi.simulate(auth, {
+          fromAddress, toAddress, chainIndex,
+          txAmount,
+          extJson: { inputData },
+          gasPrice, priorityFee,
+        }));
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_gateway_broadcast",
+    "CAT:[链上-网关] | ## 功能: 广播已签名交易到链上, 返回 orderId/txHash\n## 场景: Agent 拿到用户签名后提交上链。支持 MEV 保护(Solana可传 jitoSignedTx)\n## 关键词: 广播, broadcast, 上链, MEV保护, txHash\n## 参数:\n##   - signedTx: 签名后交易hex(必填)\n##   - chainIndex: 链索引字符串(必填)\n##   - address: 用户地址(必填)\n##   - enableMevProtection: 启用防夹(可选)\n##   - jitoSignedTx: Solana Jito签名交易(可选, SOL专用)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 实际执行上链\n## 返回量: 微小 ~1KB\n## 关联: onchainos_gateway_simulate 模拟通过 -> 用户签名 -> 本工具广播 -> onchainos_gateway_orders 查订单状态",
+    {
+      signedTx: z.string().describe("用户签名后的完整交易 hex。用户用私钥/钱包对 calldata 签名后得到"),
+      chainIndex: z.string().describe("链索引(字符串)。如 '1'=ETH '501'=Solana"),
+      address: z.string().describe("用户钱包地址"),
+      enableMevProtection: z.boolean().optional().describe("启用 MEV 防夹保护。仅 ETH/BSC/SOL/BASE 支持"),
+      jitoSignedTx: z.string().optional().describe("Solana Jito 签名交易(base58)。仅 SOL, signedTx 和 jitoSignedTx 必须同时填"),
+    },
+    { destructiveHint: true },
+    async ({ signedTx, chainIndex, address, enableMevProtection, jitoSignedTx }) => {
+      if(!auth) return AUTH_REQUIRED("TRADE");
+      try {
+        const extraData = (enableMevProtection !== undefined || jitoSignedTx)
+          ? JSON.stringify({ enableMevProtection: enableMevProtection ?? false, ...(jitoSignedTx ? { jitoSignedTx } : {}) })
+          : undefined;
+        const data = await gatewayApi.broadcast(auth, { signedTx, chainIndex, address, extraData });
+        return toResult(data, {
+          nextSteps: [
+            { action: "查订单状态", tool: "onchainos_gateway_orders", params: { address, chainIndex, orderId: "{{返回的 orderId}}" } },
+          ],
+        });
+      } catch(e) { return toError(e); }
+    },
+  );
+
+  server.tool("onchainos_gateway_orders",
+    "CAT:[链上-网关] | ## 功能: 查询广播订单列表, 按时间倒序, 返回 txStatus(1排队/2成功/3失败)/txHash\n## 场景: 广播后确认交易是否成功上链\n## 关键词: 订单, orders, txStatus, 确认, 广播记录\n## 参数:\n##   - address: 地址(必填)\n##   - chainIndex: 链索引字符串(必填)\n##   - txStatus: 状态筛选(可选)\n##   - orderId: 订单ID(可选)\n##   - cursor: 分页游标(可选)\n##   - limit: 返回条数(可选, 默认20, 最多100)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_gateway_broadcast -> 本工具 -> onchainos_transaction_detail 看详情",
+    {
+      address: z.string().describe("钱包地址"),
+      chainIndex: z.string().describe("链索引(字符串)。如 '1'=ETH"),
+      txStatus: z.enum(["1","2","3"]).optional().describe("交易状态: '1'=排队中 '2'=成功 '3'=失败"),
+      orderId: z.string().optional().describe("订单ID。从 onchainos_gateway_broadcast 返回值获取"),
+      cursor: z.string().optional().describe("分页游标。首次不传, 后续从返回值取"),
+      limit: z.string().optional().describe("返回条数, 默认20, 最多100"),
+    },
+    { readOnlyHint: true },
+    async ({ address, chainIndex, txStatus, orderId, cursor, limit }) => {
+      if(!auth) return AUTH_REQUIRED("READ");
+      try { return toResult(await postTxApi.orders(auth, address, chainIndex, txStatus, orderId, cursor, limit)); } catch(e) { return toError(e); }
+    },
+  );
+
+}