hchain-mcp 1.0.0

package/dist/tools/trade.js

@@ -0,0 +1,195 @@
+/**
+ * Trade 模块 — CAT:[链上-Swap]
+ * DEX 聚合器经典兑换: 8 tools, 参数来源官方 API 参考
+ */
+import { z } from "zod";
+import { tradeApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+export function registerTradeTools(server, auth) {
+    server.tool("onchainos_dex_supported_chain", "CAT:[链上-Swap] | ## 功能: 获取 DEX 聚合器支持的链, 返回 chainIndex/chainName/dexTokenApproveAddress\n## 场景: 兑换前确认链 + 获取 DEX Router 授权地址\n## 关键词: DEX, 链列表, chainIndex, router, approve\n## 参数:\n##   - chainIndex: 可选过滤\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: dexTokenApproveAddress -> onchainos_dex_approve_transaction", { chainIndex: z.string().optional().describe("链索引, 可选过滤。不传返回所有链") }, { readOnlyHint: true }, async ({ chainIndex }) => { if (!auth)
+        return AUTH_REQUIRED("READ"); try {
+        return toResult(await tradeApi.supportedChain(auth, chainIndex));
+    }
+    catch (e) {
+        return toError(e);
+    } });
+    server.tool("onchainos_dex_all_tokens", "CAT:[链上-Swap] | ## 功能: 获取链上 DEX 可交易代币列表, 返回 decimals/tokenContractAddress/tokenName/tokenSymbol/tokenLogoUrl\n## 场景: 查找代币合约地址和精度\n## 关键词: 代币列表, tokens, decimals\n## 参数:\n##   - chainIndex: 链索引(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_dex_supported_chain -> 本工具 -> onchainos_dex_quote", { chainIndex: z.string().describe("链索引。'1'=ETH '56'=BSC '137'=Polygon '8453'=Base '501'=Solana '784'=Sui") }, { readOnlyHint: true }, async ({ chainIndex }) => { if (!auth)
+        return AUTH_REQUIRED("READ"); try {
+        return toResult(await tradeApi.allTokens(auth, chainIndex));
+    }
+    catch (e) {
+        return toError(e);
+    } });
+    server.tool("onchainos_dex_liquidity", "CAT:[链上-Swap] | ## 功能: 获取链上流动性源列表, 返回 id/name/logo\n## 场景: 了解 DEX 覆盖范围, 用于 quote 的 dexIds/excludeDexIds 参数\n## 关键词: 流动性, liquidity, DEX列表, dexId\n## 参数:\n##   - chainIndex: 链索引(必填)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: 本工具选流动性 -> onchainos_dex_quote (传 dexIds/excludeDexIds)", { chainIndex: z.string().describe("链索引") }, { readOnlyHint: true }, async ({ chainIndex }) => { if (!auth)
+        return AUTH_REQUIRED("READ"); try {
+        return toResult(await tradeApi.liquidity(auth, chainIndex));
+    }
+    catch (e) {
+        return toError(e);
+    } });
+    server.tool("onchainos_dex_quote", "CAT:[链上-Swap] | ## 功能: 获取最优兑换报价, 返回 toTokenAmount/priceImpactPercent/dexRouterList/estimateGasFee/tradeFee\n## 场景: 交易前比价。返回 fromToken/toToken 含 isHoneyPot(貔貅检测)/taxRate(税率)\n## 关键词: 报价, quote, 价格影响, 路由, swapMode, exactIn, exactOut\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress(必填)\n##   - swapMode: exactIn(默认)/exactOut(必填)\n##   - dexIds/excludeDexIds: 流动性过滤(可选)\n##   - priceImpactProtectionPercent: 价格影响保护(可选, 默认90%)\n##   - feePercent/directRoute/singleRouteOnly/singlePoolPerHop/assetAwareRouting(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_dex_all_tokens -> 本工具 -> onchainos_dex_swap / onchainos_dex_approve_transaction", {
+        chainIndex: z.string().describe("链索引"),
+        amount: z.string().describe("交易数量, 含精度(最小单位)。如 1 USDT=1000000, 1 DAI=1000000000000000000"),
+        swapMode: z.enum(["exactIn", "exactOut"]).optional().default("exactIn").describe("exactIn=按卖出数量报价 exactOut=按买入数量报价。exactOut仅ETH/Base/BSC/Arbitrum支持UniV2/V3"),
+        fromTokenAddress: z.string().describe("卖出代币合约地址"),
+        toTokenAddress: z.string().describe("买入代币合约地址"),
+        dexIds: z.string().optional().describe("限定流动性池 dexId, 逗号分隔。从 onchainos_dex_liquidity 获取"),
+        excludeDexIds: z.string().optional().describe("排除流动性池 dexId, 逗号分隔"),
+        priceImpactProtectionPercent: z.string().optional().describe("价格影响保护百分比(0-100)。超此值报价被拒。默认90, 设100禁用"),
+        feePercent: z.string().optional().describe("分佣百分比。Solana最大10%,其他链最大3%"),
+        excludePoolAddresses: z.string().optional().describe("过滤池子地址, 逗号分隔, 最多20个"),
+        directRoute: z.boolean().optional().describe("true=限制单一流动性池。仅Solana"),
+        singleRouteOnly: z.boolean().optional().describe("true=单路径(允许多跳多池,不并行)"),
+        singlePoolPerHop: z.boolean().optional().describe("true=每跳单池"),
+        assetAwareRouting: z.boolean().optional().describe("true=仅使用匹配资产类型的路由(U-U/U-Native)"),
+        forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+    }, { readOnlyHint: true }, async (params) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            const q = {};
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined)
+                    q[k] = typeof v === "boolean" ? String(v) : v;
+            }
+            return toResult(await tradeApi.quote(auth, q), {
+                nextSteps: [
+                    { action: "如为ERC20, 先授权", tool: "onchainos_dex_approve_transaction", condition: "非原生代币需要" },
+                    { action: "构建兑换交易", tool: "onchainos_dex_swap" },
+                ],
+            });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_dex_approve_transaction", "CAT:[链上-Swap] | ## 功能: 构建 ERC-20 授权交易 calldata, 返回 data/dexContractAddress/gasLimit/gasPrice\n## 场景: ERC20 Swap 前授权 DEX Router 动用代币\n## 关键词: approve, 授权, ERC20, calldata, dexContractAddress\n## 参数:\n##   - chainIndex/tokenContractAddress/approveAmount(必填)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 微小 ~1KB\n## 关联: onchainos_dex_quote -> 本工具 -> onchainos_gateway_broadcast", {
+        chainIndex: z.string().describe("链索引"),
+        tokenContractAddress: z.string().describe("代币合约地址"),
+        approveAmount: z.string().describe("授权数量, 含精度。如授权1 USDT=1000000, 1 DAI=1000000000000000000"),
+    }, { destructiveHint: true, idempotentHint: true }, async ({ chainIndex, tokenContractAddress, approveAmount }) => {
+        if (!auth)
+            return AUTH_REQUIRED("TRADE");
+        try {
+            return toResult(await tradeApi.approveTransaction(auth, chainIndex, tokenContractAddress, approveAmount), {
+                nextSteps: [{ action: "签名后广播", tool: "onchainos_gateway_broadcast" }],
+            });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_dex_swap", "CAT:[链上-Swap] | ## 功能: 构建兑换交易 calldata, 返回 tx(from/to/data/value/gas/gasPrice/maxPriorityFeePerGas/minReceiveAmount/maxSpendAmount/signatureData)\n## 场景: 授权后构建 swap。approveTransaction=true可一并返回授权calldata省去单独调approve\n## 关键词: swap, 兑换, calldata, 交易构建, MEV, Jito\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress/userWalletAddress/slippagePercent(必填)\n##   - swapMode/approveTransaction/approveAmount/feePercent/swapReceiverAddress(可选)\n##   - autoSlippage/maxAutoslippagePercent/priceImpactProtectionPercent(可选)\n##   - dexIds/excludeDexIds/excludePoolAddresses/disableRFQ/directRoute(可选)\n##   - computeUnitPrice/computeUnitLimit/tips: Solana参数(可选)\n##   - gaslimit/gasLevel: EVM gas参数(可选)\n##   - positiveSlippagePercent/positiveSlippageFeeAddress: 正滑点分佣(可选,白名单)\n## 鉴权: 需要 API Key(交易)\n## 风险: WRITE - 返回 calldata\n## 返回量: 中等 ~5KB\n## 关联: onchainos_dex_quote -> 本工具 -> onchainos_gateway_simulate -> onchainos_gateway_broadcast", {
+        chainIndex: z.string().describe("链索引"),
+        amount: z.string().describe("交易数量, 含精度(最小单位)。如1 USDT=1000000"),
+        swapMode: z.enum(["exactIn", "exactOut"]).optional().default("exactIn").describe("exactIn=按卖出 exactOut=按买入(仅ETH/Base/BSC/Arbitrum的UniV2/V3支持)"),
+        fromTokenAddress: z.string().describe("卖出代币地址"),
+        toTokenAddress: z.string().describe("买入代币地址"),
+        userWalletAddress: z.string().describe("用户钱包地址"),
+        slippagePercent: z.string().describe("滑点百分比。EVM:0-100, Solana:0-<100"),
+        approveTransaction: z.boolean().optional().describe("true=一并返回授权calldata(signatureData), 省去单独调approve"),
+        approveAmount: z.string().optional().describe("授权数量, 含精度。approveTransaction=true时使用"),
+        autoSlippage: z.boolean().optional().describe("true=自动滑点覆盖slippagePercent"),
+        maxAutoslippagePercent: z.string().optional().describe("自动滑点上限百分比"),
+        feePercent: z.string().optional().describe("分佣百分比。Solana最大10%, 其他链最大3%"),
+        fromTokenReferrerWalletAddress: z.string().optional().describe("fromToken分佣地址"),
+        toTokenReferrerWalletAddress: z.string().optional().describe("toToken分佣地址"),
+        swapReceiverAddress: z.string().optional().describe("接收代币地址, 默认=userWalletAddress"),
+        priceImpactProtectionPercent: z.string().optional().describe("价格影响保护(0-100,默认90)"),
+        dexIds: z.string().optional().describe("限定流动性池,逗号分隔"),
+        excludeDexIds: z.string().optional().describe("排除流动性池,逗号分隔"),
+        excludePoolAddresses: z.string().optional().describe("过滤池子地址,逗号分隔,最多20"),
+        disableRFQ: z.boolean().optional().describe("true=禁用RFQ"),
+        directRoute: z.boolean().optional().describe("true=单跳模式。Solana和EVM均支持"),
+        singleRouteOnly: z.boolean().optional().describe("true=单路径(允许多跳多池)"),
+        singlePoolPerHop: z.boolean().optional().describe("true=每跳单池"),
+        assetAwareRouting: z.boolean().optional().describe("true=仅匹配资产类型的路由"),
+        gaslimit: z.string().optional().describe("EVM gas限额(wei)。过低会导致报价失败"),
+        gasLevel: z.enum(["average", "fast", "slow"]).optional().describe("EVM gas等级,默认average"),
+        computeUnitPrice: z.string().optional().describe("Solana compute unit price"),
+        computeUnitLimit: z.string().optional().describe("Solana compute unit limit"),
+        tips: z.string().optional().describe("Jito tips(SOL)。0.0000000001~2。指定后signatureData返回Jito转账calldata"),
+        forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+        positiveSlippagePercent: z.string().optional().describe("正滑点分佣比例(0-10,白名单)"),
+        positiveSlippageFeeAddress: z.string().optional().describe("正滑点分佣地址(白名单)"),
+        callDataMemo: z.string().optional().describe("自定义calldata上链数据(64bytes hex,如'0x...')"),
+        maxCalldataSize: z.string().optional().describe("最大calldata大小估计值"),
+        maxAccounts: z.string().optional().describe("最大账户数估计值"),
+    }, { destructiveHint: true }, async (params) => {
+        if (!auth)
+            return AUTH_REQUIRED("TRADE");
+        try {
+            const q = {};
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined)
+                    q[k] = typeof v === "boolean" ? String(v) : v;
+            }
+            return toResult(await tradeApi.swap(auth, q), {
+                nextSteps: [
+                    { action: "如有 signatureData, 先执行授权 calldata", tool: "onchainos_gateway_broadcast", condition: "signatureData 存在时包含 approveContract+approveTxCalldata" },
+                    { action: "模拟交易", tool: "onchainos_gateway_simulate", condition: "广播前建议模拟" },
+                    { action: "签名后广播", tool: "onchainos_gateway_broadcast" },
+                    { action: "查交易状态", tool: "onchainos_dex_swap_history" },
+                ],
+            });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_dex_swap_instruction", "CAT:[链上-Swap] | ## 功能: 获取 Solana 兑换指令(高级), 返回 instructionLists/addressLookupTableAccount/tx/routerResult\n## 场景: Solana 自定义交易组装, 可加自己的指令\n## 关键词: Solana, swap instruction, 高级, lookup table\n## 参数:\n##   - chainIndex/amount/fromTokenAddress/toTokenAddress/userWalletAddress/slippagePercent(必填)\n##   - autoSlippage/maxAutoSlippagePercent/feePercent/useTokenLedger/swapReceiverAddress(可选)\n##   - priceImpactProtectionPercent/dexIds/excludeDexIds/disableRFQ/directRoute(可选)\n##   - computeUnitPrice/computeUnitLimit: Solana gas(可选)\n##   - positiveSlippagePercent/positiveSlippageFeeAddress: 正滑点分佣(可选,白名单)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~30KB\n## 关联: Solana场景: onchainos_dex_quote -> 本工具 -> 自行签名广播", {
+        chainIndex: z.string().describe("Solana固定'501'"),
+        amount: z.string().describe("卖出数量, 含精度"),
+        fromTokenAddress: z.string().describe("卖出代币Mint地址"),
+        toTokenAddress: z.string().describe("买入代币Mint地址"),
+        userWalletAddress: z.string().describe("Solana钱包地址"),
+        slippagePercent: z.string().describe("滑点百分比。Solana:0-<100"),
+        autoSlippage: z.boolean().optional().describe("true=自动滑点"),
+        maxAutoSlippagePercent: z.string().optional().describe("自动滑点上限"),
+        feePercent: z.string().optional().describe("分佣百分比。Solana最大10%"),
+        fromTokenReferrerWalletAddress: z.string().optional().describe("fromToken分佣地址"),
+        toTokenReferrerWalletAddress: z.string().optional().describe("toToken分佣地址"),
+        swapReceiverAddress: z.string().optional().describe("接收代币地址"),
+        useTokenLedger: z.boolean().optional().describe("true=执行前记录代币余额"),
+        priceImpactProtectionPercent: z.string().optional().describe("价格影响保护(0-100)"),
+        dexIds: z.string().optional().describe("限定流动性池,逗号分隔"),
+        excludeDexIds: z.string().optional().describe("排除流动性池,逗号分隔"),
+        disableRFQ: z.boolean().optional().describe("true=禁用RFQ"),
+        directRoute: z.boolean().optional().describe("true=单池路由。仅Solana"),
+        computeUnitPrice: z.string().optional().describe("Solana compute unit price"),
+        computeUnitLimit: z.string().optional().describe("Solana compute unit limit"),
+        positiveSlippagePercent: z.string().optional().describe("正滑点分佣比例(0-10,白名单)"),
+        positiveSlippageFeeAddress: z.string().optional().describe("正滑点分佣地址"),
+        forJitoBundle: z.boolean().optional().describe("true=排除不兼容Jito的DEX"),
+        excludePoolAddresses: z.string().optional().describe("过滤池子地址,逗号分隔,最多20"),
+    }, { readOnlyHint: true }, async (params) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            const q = {};
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined)
+                    q[k] = typeof v === "boolean" ? String(v) : v;
+            }
+            return toResult(await tradeApi.swapInstruction(auth, q));
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_dex_swap_history", "CAT:[链上-Swap] | ## 功能: 查询兑换交易详情(状态/fromToken/toToken/txFee)\n## 场景: 广播后确认交易状态\n## 关键词: swap history, 交易状态, txHash\n## 参数:\n##   - chainIndex: 链索引(必填)\n##   - txHash: 交易哈希(必填)\n##   - isFromMyProject: 是否本项目(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: onchainos_gateway_broadcast -> 本工具", {
+        chainIndex: z.string().describe("链索引"),
+        txHash: z.string().describe("交易哈希"),
+        isFromMyProject: z.boolean().optional().describe("true=仅查本API Key订单 false=查任意OKX DEX订单"),
+    }, { readOnlyHint: true }, async ({ chainIndex, txHash, isFromMyProject }) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            return toResult(await tradeApi.swapHistory(auth, chainIndex, txHash, isFromMyProject));
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+}
+//# sourceMappingURL=trade.js.map

package/dist/tools/txhistory.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Auth } from "../adapters/shared.js";
+export declare function registerTxHistoryTools(server: McpServer, auth: Auth | null): void;
+//# sourceMappingURL=txhistory.d.ts.map

package/dist/tools/txhistory.js

@@ -0,0 +1,49 @@
+/**
+ * 交易历史模块 — CAT:[链上-账户]
+ * 按官方文档逐端点对接
+ */
+import { z } from "zod";
+import { postTxApi } from "../adapters/onchainos.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+export function registerTxHistoryTools(server, auth) {
+    server.tool("onchainos_tx_history_supported_chain", "CAT:[链上-账户] | ## 功能: 获取交易历史 API 支持的链, 返回 chainIndex(字符串)/name/shortName\n## 场景: 查交易历史前确认目标链是否被支持\n## 关键词: 交易历史, 链列表, tx history, chainIndex\n## 参数: 无\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 微小 ~2KB\n## 关联: 本工具 -> onchainos_transaction_history / onchainos_transaction_detail", {}, { readOnlyHint: true }, async () => { if (!auth)
+        return AUTH_REQUIRED("READ"); try {
+        return toResult(await postTxApi.supportedChain(auth));
+    }
+    catch (e) {
+        return toError(e);
+    } });
+    server.tool("onchainos_transaction_history", "CAT:[链上-账户] | ## 功能: 查询地址6个月内交易历史, 按时间倒序, 支持130+链\n## 场景: 用户想看最近交易记录, 或分析某地址的交易行为\n## 关键词: 交易历史, tx history, 转账, 合约交互\n## 参数:\n##   - address: 钱包地址(必填)\n##   - chains: 链索引逗号分隔, 最多50个(必填)\n##   - tokenContractAddress: 代币筛选(可选)\n##   - begin/end: 时间范围 Unix毫秒(可选)\n##   - cursor: 分页游标(可选)\n##   - limit: 返回条数, 多链最多20, 单链最多100(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 大 ~100KB\n## 关联: onchainos_tx_history_supported_chain -> 本工具 -> onchainos_transaction_detail(单笔详情)", {
+        address: z.string().describe("钱包地址"),
+        chains: z.string().describe("链索引, 逗号分隔, 最多50个。如 '1'=ETH '56'=BSC。从 onchainos_tx_history_supported_chain 获取"),
+        tokenContractAddress: z.string().optional().describe("代币合约地址筛选。不传=查所有代币+主链币, 传空字符串=只查主链币, 传具体地址=查该代币"),
+        begin: z.string().optional().describe("开始时间, Unix毫秒时间戳。如 '1700000000000'"),
+        end: z.string().optional().describe("结束时间, Unix毫秒时间戳"),
+        cursor: z.string().optional().describe("分页游标。首次不传, 后续从返回值取"),
+        limit: z.string().optional().describe("返回条数。多链默认20最多20, 单链默认20最多100"),
+    }, { readOnlyHint: true }, async ({ address, chains, tokenContractAddress, begin, end, cursor, limit }) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            return toResult(await postTxApi.transactions(auth, address, chains, tokenContractAddress, begin, end, cursor, limit));
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_transaction_detail", "CAT:[链上-账户] | ## 功能: 根据 txHash 查询单笔交易详情, 含 internalTransactionDetails/tokenTransferDetails\n## 场景: 看某笔交易的 gas 消耗、内部交易、代币转移明细\n## 关键词: 交易详情, tx detail, hash, 内部交易, token transfer\n## 参数:\n##   - chainIndex: 链索引字符串(必填)\n##   - txHash: 交易哈希(必填)\n##   - itype: 交易层级类型(可选)\n## 鉴权: 需要 API Key(只读)\n## 风险: READ - 只读查询\n## 返回量: 中等 ~10KB\n## 关联: onchainos_transaction_history -> 本工具 -> onchainos_portfolio_overview(关联地址分析)", {
+        chainIndex: z.string().describe("链索引(字符串)。如 '1'=ETH '42161'=Arbitrum"),
+        txHash: z.string().describe("交易哈希。从 onchainos_transaction_history 返回值或广播返回获取"),
+        itype: z.enum(["0", "1", "2"]).optional().describe("交易层级: '0'=外层主链币转移 '1'=合约内层主链币转移 '2'=token转移。不传查所有"),
+    }, { readOnlyHint: true }, async ({ chainIndex, txHash, itype }) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            return toResult(await postTxApi.transactionDetail(auth, chainIndex, txHash, itype));
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+}
+//# sourceMappingURL=txhistory.js.map

package/dist/tools/ws.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Auth } from "../adapters/shared.js";
+export declare function registerWsTools(server: McpServer, auth: Auth | null): void;
+//# sourceMappingURL=ws.d.ts.map

package/dist/tools/ws.js

@@ -0,0 +1,64 @@
+/**
+ * WebSocket 模块 — CAT:[链上-行情]/[链上-Swap]
+ * 管理 WS 连接生命周期: connect → subscribe → (数据stderr日志) → unsubscribe → disconnect
+ *
+ * ⚠️ MCP Tool 限制: WS 是长连接推送, Tool 是请求-响应。
+ * subscribe 后数据通过 stderr 日志输出, 供 Agent 读取。
+ */
+import { z } from "zod";
+import { wsConnect, wsSubscribe, wsUnsubscribe, wsDisconnect } from "../adapters/onchainos-ws.js";
+import { toResult, toError, AUTH_REQUIRED } from "../adapters/shared.js";
+export function registerWsTools(server, auth) {
+    server.tool("onchainos_ws_connect", "CAT:[链上-WS] | ## 功能: 建立 WebSocket 连接并登录\n## 场景: 需要实时推送数据(价格/K线/交易/信号)时先调此工具\n## 关键词: WebSocket, 连接, 实时, 登录\n## 参数: 无(使用 API Key 自动登录)\n## 鉴权: 需要 API Key\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: 本工具 -> onchainos_ws_subscribe -> onchainos_ws_unsubscribe -> onchainos_ws_disconnect", {}, { readOnlyHint: true }, async () => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            const connId = await wsConnect(auth);
+            return toResult({ connId, status: "connected" });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_ws_subscribe", "CAT:[链上-WS] | ## 功能: 订阅 WebSocket 频道, 数据实时推送到 stderr 日志\n## 场景: 订阅价格/流通/K线/交易/信号/Memepump/地址追踪\n## 关键词: WebSocket, subscribe, 订阅, 实时推送\n## 参数:\n##   - channel: 频道名(必填)\n##   - chainIndex: 链索引(必填)\n##   - tokenContractAddress: 代币地址(价格/流通/K线/交易频道必填)\n## 鉴权: 需先调 onchainos_ws_connect\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: onchainos_ws_connect -> 本工具", {
+        channel: z.string().describe("频道名: price/price-info/trades/dex-token-candle1m/dex-token-candle1H/dex-market-new-signal-openapi/dex-market-memepump-new-token-openapi/dex-market-memepump-update-metrics-openapi/address-tracker-activity/kol_smartmoney-tracker-activity"),
+        chainIndex: z.string().describe("链索引"),
+        tokenContractAddress: z.string().optional().describe("代币合约地址(小写)。price/price-info/trades/candle频道必填, 信号/Memepump频道不需要"),
+        walletAddress: z.string().optional().describe("钱包地址。仅 address-tracker-activity 频道需要, 最多200个地址"),
+    }, { readOnlyHint: true }, async ({ channel, chainIndex, tokenContractAddress, walletAddress }) => {
+        if (!auth)
+            return AUTH_REQUIRED("READ");
+        try {
+            const ch = { channel, chainIndex };
+            if (tokenContractAddress)
+                ch.tokenContractAddress = tokenContractAddress;
+            if (walletAddress)
+                ch.walletAddress = walletAddress;
+            await wsSubscribe(ch);
+            return toResult({ channel, chainIndex, status: "subscribed" }, {
+                warnings: ["数据将通过 stderr 日志实时推送, 标签 [WS-DATA]"],
+            });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_ws_unsubscribe", "CAT:[链上-WS] | ## 功能: 取消订阅 WebSocket 频道\n## 场景: 不再需要某个频道的实时数据\n## 关键词: WebSocket, unsubscribe, 取消订阅\n## 参数:\n##   - channel/chainIndex/tokenContractAddress: 同 subscribe\n## 鉴权: 需已连接\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: onchainos_ws_subscribe -> 本工具", {
+        channel: z.string().describe("频道名"),
+        chainIndex: z.string().describe("链索引"),
+        tokenContractAddress: z.string().optional().describe("代币地址"),
+    }, { readOnlyHint: true }, async ({ channel, chainIndex, tokenContractAddress }) => {
+        try {
+            const ch = { channel, chainIndex };
+            if (tokenContractAddress)
+                ch.tokenContractAddress = tokenContractAddress;
+            await wsUnsubscribe(ch);
+            return toResult({ channel, status: "unsubscribed" });
+        }
+        catch (e) {
+            return toError(e);
+        }
+    });
+    server.tool("onchainos_ws_disconnect", "CAT:[链上-WS] | ## 功能: 断开 WebSocket 连接\n## 场景: 不再需要实时数据时关闭连接\n## 关键词: WebSocket, disconnect, 断开\n## 参数: 无\n## 鉴权: 无\n## 风险: READ\n## 返回量: 微小 ~1KB\n## 关联: 关闭所有订阅并断开", {}, { readOnlyHint: true }, async () => { wsDisconnect(); return toResult({ status: "disconnected" }); });
+}
+//# sourceMappingURL=ws.js.map

package/docs/DEFI.md

@@ -0,0 +1,65 @@
+# DeFi API — 知识总结
+
+> 来源: web3.okx.com 官方 API 参考 · 对接日期 2026-06-14
+
+---
+
+## 模块速查 (14 endpoints, 全部 Free)
+
+### 投资品查询 (7)
+
+| # | 端点 | 方法 | 说明 |
+|---|------|------|------|
+| 1 | `/defi/product/supported-chains` | GET | 支持链, chainIndex+network |
+| 2 | `/defi/product/supported-platforms` | GET | 协议列表, analysisPlatformId+investmentCount |
+| 3 | `/defi/product/search` | POST | 投资品搜索, tokenKeywordList+productGroup |
+| 4 | `/defi/product/detail` | GET | 投资品详情, APY/TVL/underlyingToken |
+| 5 | `/defi/product/rate/chart` | GET | APY 折线图, timeRange=WEEK/MONTH/SEASON/YEAR |
+| 6 | `/defi/product/tvl/chart` | GET | TVL 折线图 |
+| 7 | `/defi/product/depth-price/chart` | GET | V3 Pool 深度/价格图, 仅 V3 DEX Pool |
+
+### 交易执行 (5)
+
+| # | 端点 | 方法 | 鉴权 | 说明 |
+|---|------|------|:--:|------|
+| 8 | `/defi/product/detail/prepare` | POST | READ | 交易参数准备, investWithTokenList/receiveTokenInfo |
+| 9 | `/defi/calculator/enter/info` | POST | READ | V3 Pool 双币分配计算 |
+| 10 | `/defi/transaction/enter` | POST | TRADE | 申购/存款, 返回 dataList(APPROVE→DEPOSIT) |
+| 11 | `/defi/transaction/exit` | POST | TRADE | 赎回/还款, redeemPercent 建议必传 |
+| 12 | `/defi/transaction/claim` | POST | TRADE | 领取奖励, rewardType 6种 |
+
+### 用户持仓 (2)
+
+| # | 端点 | 方法 | 说明 |
+|---|------|------|------|
+| 13 | `/defi/user/asset/platform/list` | POST | 持仓概览(协议维度), walletAddressList 数组 |
+| 14 | `/defi/user/asset/platform/detail` | POST | 持仓明细(投资品维度), 含 availableRewards |
+
+---
+
+## 投资流程
+
+```
+查询链路: supported-chains → supported-platforms → search → detail → prepare
+执行链路: prepare → enter/exit/claim → gateway_broadcast
+持仓链路: platform/list → platform/detail → claim/exit
+```
+
+## 核心参数
+
+- investmentId: 投资品唯一标识, 从 search 返回值获取
+- analysisPlatformId: 协议ID, 从 supported-platforms 获取
+- productGroup: SINGLE_EARN(单币) / DEX_POOL(流动性) / LENDING(借贷)
+- rewardType: REWARD_INVESTMENT / REWARD_PLATFORM / V3_FEE / REWARD_OKX_BONUS / REWARD_MERKLE_BONUS / UNLOCKED_PRINCIPAL
+
+## enter/exit 返回结构
+
+```
+dataList[{callDataType, from, to, value, serializedData, originalData, signatureData}]
+```
+
+callDataType: APPROVE → DEPOSIT / WITHDRAW / SWAP,DEPOSIT / WITHDRAW,SWAP
+
+## 多链支持
+
+EVM(hex calldata) / Solana(base58) / Sui(base64 BCS) / Aptos(transactionPayload)

package/docs/GATEWAY.md

@@ -0,0 +1,45 @@
+# Onchain Gateway API — 知识总结
+
+> 来源: web3.okx.com 官方 API 参考 · 对接日期 2026-06-14
+
+---
+
+## 端点 (6)
+
+| # | 端点 | 方法 | 关键参数 |
+|---|------|------|---------|
+| 1 | `/api/v6/dex/pre-transaction/supported/chain` | GET | 无 |
+| 2 | `/api/v6/dex/pre-transaction/gas-price?chainIndex=` | GET | chainIndex(String) |
+| 3 | `/api/v6/dex/pre-transaction/gas-limit` | POST | chainIndex, fromAddress, toAddress, txAmount?, extJson.inputData? |
+| 4 | `/api/v6/dex/pre-transaction/simulate` | POST | fromAddress, toAddress, chainIndex, txAmount?, extJson.inputData, priorityFee?, gasPrice? |
+| 5 | `/api/v6/dex/pre-transaction/broadcast-transaction` | POST | signedTx, chainIndex, address, extraData? |
+| 6 | `/api/v6/dex/post-transaction/orders` | GET | address, chainIndex, txStatus?, orderId?, cursor?, limit? |
+
+## 流程
+
+```
+1. supported/chain → 确认链
+2. gas-price → 查Gas价格
+3. gas-limit → 预估用量
+4. simulate → 模拟执行 (白名单, dexapi@okx.com)
+5. broadcast → 广播签名交易
+6. orders → 追踪状态
+```
+
+## 响应要点
+
+- gas-price: EVM/Tron 返回 normal/min/max + eip1559Protocol; Solana 返回 priorityFee
+- simulate: 返回 intention(Swap/Token Approval), assetChange, gasUsed, failReason, risks
+- broadcast: 返回 orderId + txHash; 支持 MEV 保护 (enableMevProtection/jitoSignedTx)
+- orders: txStatus 1=排队 2=成功 3=失败; 支持分页(cursor/limit)
+
+## 错误码
+
+| 错误码 | 含义 |
+|--------|------|
+| 50001 | 服务暂不可用 |
+| 81001 | 参数错误 |
+| 81108 | 钱包类型不匹配 |
+| 81104 | 不支持该链 |
+| 81152 | 代币不存在 |
+| 81451 | 节点返回失败 |

package/docs/MARKET.md

@@ -0,0 +1,109 @@
+# Market API — 知识总结
+
+> 来源: web3.okx.com 官方 API 参考 · 对接日期 2026-06-14
+
+---
+
+## 定价等级
+
+| 等级 | 月度免费额度 | 超出单价 | 端点数 |
+|------|:---------:|:------:|:-----:|
+| Free | 无限 | $0 | 8 |
+| Basic | 100K | $0.0001/次 | 10 |
+| Premium | 100K | $0.0005/次 | 27 |
+
+---
+
+## 模块速查 (45 endpoints)
+
+### 行情价格 (5) — Basic
+| # | 端点 | 方法 | 说明 |
+|---|------|------|------|
+| 1 | `/market/supported/chain?chainIndex=` | GET | 支持链 (Free) |
+| 2 | `/market/price` | POST | 实时价格, body数组 |
+| 3 | `/market/candles` | GET | K线 OHLCV, bar=1m-3M |
+| 4 | `/market/historical-candles` | GET | 历史K线 (Premium) |
+| 5 | `/market/trades` | GET | 交易活动, tagFilter 1-9 |
+
+### 综合币价 (2) — Free
+| # | 端点 | 说明 |
+|---|------|------|
+| 6 | `/index/current-price` | POST 批量 |
+| 7 | `/index/historical-price` | GET 分页 |
+
+### 代币 API (8)
+| # | 端点 | 等级 | 说明 |
+|---|------|:--:|------|
+| 8 | `/market/token/search` | Basic | 跨链搜索 |
+| 9 | `/market/token/basic-info` | Basic | 批量元数据 POST |
+| 10 | `/market/token/top-liquidity` | Basic | 前5流动性池 |
+| 11 | `/market/price-info` | Premium | 批量交易信息 POST |
+| 12 | `/market/token/advanced-info` | Premium | 安全分析(貔貅/狙击手) |
+| 13 | `/market/token/hot-token` | Basic | Trending/Xmentioned |
+| 14 | `/market/token/holder` | Premium | 前100持有人+PnL |
+| 15 | `/market/token/top-trader` | Premium | 前100盈利地址 |
+
+### 聚类 BubbleMap (4)
+| # | 端点 | 等级 | 说明 |
+|---|------|:--:|------|
+| 16 | `/token/cluster/supported/chain` | Free | 支持链 |
+| 17 | `/token/cluster/overview` | Premium | 集中度/rugPull% |
+| 18 | `/token/cluster/list` | Premium | top100集群列表 |
+| 19 | `/token/cluster/top-holders` | Premium | 前10/50/100持仓 |
+
+### Memepump 扫链 (7)
+| # | 端点 | 等级 | 说明 |
+|---|------|:--:|------|
+| 20 | `/memepump/supported/chainsProtocol` | Free | 链+协议 |
+| 21 | `/memepump/tokenList` | Premium | 最多30条, 30+筛选维度 |
+| 22 | `/memepump/tokenDetails` | Premium | 单币详情 |
+| 23 | `/memepump/tokenDevInfo` | Premium | 开发者历史 |
+| 24 | `/memepump/similarToken` | Basic | 相似代币 |
+| 25 | `/memepump/tokenBundleInfo` | Premium | 捆绑检测 |
+| 26 | `/memepump/apedWallet` | Premium | 同车钱包(最多50) |
+
+### 信号 Signal (4)
+| # | 端点 | 等级 | 说明 |
+|---|------|:--:|------|
+| 27 | `/signal/supported/chain` | Free | 支持链 |
+| 28 | `/signal/list` | Premium | 信号列表 POST |
+| 29 | `/leaderboard/supported/chain` | Free | 聪明钱榜单链 |
+| 30 | `/leaderboard/list` | Premium | 聪明钱排行榜 |
+
+### Portfolio 地址分析 (6)
+| # | 端点 | 等级 | 说明 |
+|---|------|:--:|------|
+| 31 | `/portfolio/supported/chain` | Free | 支持链 |
+| 32 | `/portfolio/overview` | Premium | 地址画像(PnL/胜率) |
+| 33 | `/portfolio/recent-pnl` | Premium | 近期收益列表 |
+| 34 | `/portfolio/token/latest-pnl` | Basic | 单代币最新收益 |
+| 35 | `/portfolio/dex-history` | Basic | DEX交易历史 |
+| 36 | `/address-tracker/trades` | Premium | 聪明钱/KOL追踪 |
+
+### 社媒 Social (9) — Premium
+| # | 端点 | 说明 |
+|---|------|------|
+| 37 | `/social/news/latest` | 最新新闻 |
+| 38 | `/social/news/by-symbol` | 按代币查新闻 |
+| 39 | `/social/news/search` | 全文搜索 |
+| 40 | `/social/news/detail` | 文章详情 |
+| 41 | `/social/news/platforms` | 新闻平台列表 |
+| 42 | `/social/sentiment/symbol` | 情绪指标 |
+| 43 | `/social/sentiment/ranking` | 情绪热度排行 |
+| 44 | `/social/vibe/timeline` | Vibe时间线+KOL |
+| 45 | `/social/vibe/top-kols` | 热门KOL列表 |
+
+---
+
+## x402 支付
+
+Market API 调用超出免费额度后走 x402 协议：
+- 请求 → 402 + PAYMENT-REQUIRED → EIP-3009 签名 → PAYMENT-SIGNATURE 头重试
+- X Layer (eip155:196), USDG/USDT0 支付
+
+## 核心参数规则
+
+- chainIndex: 全部 String 类型
+- POST 端点: body 为 JSON 数组
+- tagFilter: 1=KOL 2=Dev 3=聪明钱 4=鲸鱼 5=新钱包 6=老鼠仓 7=狙击手 8=疑似钓鱼 9=Bundle
+- timeFrame: 1=1D/1h 2=3D/4h 3=7D/24h 4=1M 5=3M (各端点有差异)

package/docs/PAYMENTS.md

@@ -0,0 +1,83 @@
+# Agent Payments Protocol — 知识总结
+
+> 来源: web3.okx.com 官方文档 · 对接日期 2026-06-14
+
+---
+
+## 一句话
+
+让 AI Agent 能花钱和挣钱的开放协议——报价→签名→结算→交付 全流程。
+
+---
+
+## 角色三角
+
+```
+Seller ──创建付款──→ Broker(OKX验证+结算) ←──签名付款── Buyer
+ (需API Key)          (托管状态机)            (公开访问)
+```
+
+Broker 不碰资金，只做公证：验签→KYT→提交链上交易。
+
+---
+
+## 4 种支付方式速查
+
+| intent | 产品名 | 签名 | 结算 | 买家钱包 | Agent卖家 |
+|--------|--------|------|------|----------|:--:|
+| `charge` | 单次支付 | EIP-3009 一次签 | Broker 代上链 | 任意 EVM | ✅ |
+| `aggr_deferred` | 批量支付 | Session Key 多次签 | TEE 聚合上链 | Agentic Wallet | 即将 |
+| `session`(voucher) | 按量支付 | Voucher 累计签 | Escrow 关闭结算 | Agentic Wallet | 即将 |
+| `escrow` | 担保支付 | 托管+仲裁 | Arbitrator 裁决 | — | 即将 |
+
+---
+
+## 单次支付 (charge)
+
+**流程**: Buyer请求→Seller返回402 Challenge→Buyer签EIP-3009→提交Credential→Broker验签+KYT→X Layer结算→交付
+
+**链和代币**: X Layer (chainId:196) | USDG `0x4ae4...` | USD₮0 `0x779d...` | 0 Gas
+
+---
+
+## 批量支付 (aggr_deferred)
+
+**适用**: 单价<1美分 + 频率极高(百次/分钟)
+
+**流程**: Session Key签名→Broker入库→TEE定时聚合(验Session Key+sum+EOA重签)→X Layer上链
+
+**关键**: 买家必须Agentic Wallet | settle返回success即视为收款 | 不受出块速度限制
+
+---
+
+## 按量支付 (session/voucher)
+
+**三步**: ①预存到Escrow(链上1次) ②每次签累计Voucher(链下,EIP-712) ③settle/close上链结算
+
+**Voucher特性**: 累计金额(非增量) | 防重放(单调递增) | 抗丢失(只看最新) | 零上链
+
+**关闭**: settle(中途,通道继续) | close(协同,买家配合) | requestClose(强制,15分钟宽限期)
+
+---
+
+## MCP Tools (5)
+
+| Tool | 角色 | 鉴权 |
+|------|------|:--:|
+| `onchainos_payment_supported` | 查网络和代币 | API Key |
+| `onchainos_payment_create` | Seller 创建 charge | API Key |
+| `onchainos_payment_detail` | Buyer 拉取 challenge | 公开 |
+| `onchainos_payment_submit` | Buyer 提交 EIP-3009 签名 | 公开 |
+| `onchainos_payment_status` | 查结算状态 | 公开 |
+
+---
+
+## 术语表
+
+- **EIP-3009**: 买家签转账授权，Broker代上链，买家0 Gas
+- **Session Key**: Agentic Wallet临时密钥，单独无法上链，须TEE重签
+- **TEE**: 硬件隔离环境，批量支付安全底座
+- **Escrow合约**: 链上托管，资金只能按规则释放
+- **Voucher**: 累计凭证——"截至当前累计应付X"
+- **Challenge/Credential**: 协议唯一两类消息，传输载体无关(HTTP402/IM)
+- **KYT**: Broker层交易级合规审查