gate-exchange-smallbalance

解析 gate-cli（二进制文件路径）

按以下顺序解析 gate-cli：（1） command -v gate-cli 和 gate-cli --version 均成功；（2） 如果 ${HOME}/.local/bin/gate-cli 可执行，则使用该文件；（3） 如果 ${HOME}/.openclaw/skills/bin/gate-cli 可执行，则使用该文件。规范规则：exchange-runtime-rules.md §4（或 gate-runtime-rules.md §4）。

Gate 交易所小额余额（Dust 转为 GT）

一般规则

继续操作前，请阅读并遵循共享运行时规则： → exchange-runtime-rules.md（位于上级目录 skills/ 中）

技能依赖项

身份验证

• 交互式文件设置： 如果主机上未同时设置 GATE_API_KEY 和 GATE_API_SECRET，请运行 gate-cli config init，按照向导完成 API 密钥、密钥、配置文件和默认值的设置（参见 gate-cli）。
• 环境变量 / 标志： 如果已提供凭据，则无需运行 gate-cli config init，例如主机上已同时设置 GATE_API_KEY 和 GATE_API_SECRET，或在支持的情况下使用 --api-key / --api-secret；切勿要求用户在聊天中粘贴密钥。
• 权限： 根据 Dust 转为 GT 流程的需要，授予钱包读取和小额余额兑换权限（遵循最小权限原则）。
• 门户： 请在聊天之外创建或轮换密钥：https://www.gate.com/myaccount/profile/api-key/manage

安装检查

• 必需项： gate-cli（从 gate-cli releases 安装，或通过你所在环境的 Gate MCP / 技能安装器安装）。
• 通过名称调用时，请将包含 gate-cli 的目录添加到 PATH。
• 凭据： 如果主机上同时设置了非空的 GATE_API_KEY 和 GATE_API_SECRET，则不要要求运行 gate-cli config init。如果两者都未设置或为空，请提醒操作者运行 gate-cli config init，或在技能库中对应的技能里配置 GATE_API_KEY / GATE_API_SECRET（切勿要求用户在聊天中粘贴密钥）。
• 基本检查： 执行兑换操作前，请确认 CLI 可用（例如运行 gate-cli cex wallet balance small 或 gate-cli --version）。

---

此技能涵盖小额余额兑换：列出符合平台 Dust 阈值的现货持仓、将其兑换为 GT，以及查询兑换历史。在底层，这会映射到钱包路由 GET/POST /wallet/small_balance 和 GET /wallet/small_balance_history；Agent 应通过下方的 MCP 工具 cex_wallet_* 执行此流程，而不是手动构造 HTTP 请求。

领域知识

小额余额兑换会将价值低于平台小额余额门槛的现货（或统一账户现货侧）持仓批量兑换（根据政策，通常每种资产不超过等值 100 USDT；具体限额以 API 响应为准）。

术语	含义
Dust（零散余额）	价值极低、难以单独下单交易的剩余余额
小额余额	符合门槛的币种，可通过一次操作兑换为 GT

特点：

• 将低价值资产合并为 GT
• 适用于整理钱包；不能替代大额持仓的常规现货卖出

账户范围：主要适用于现货或统一账户中的现货余额（以产品范围为准）。

负载说明：gate-cli cex wallet balance small 和 gate-cli cex wallet balance small-history 的响应可能会将行数据包装在一个外层数组中，其中第一个元素是要渲染的对象列表；若如此，请使用该内层列表。典型行字段：列表 — currency、available_balance、estimated_as_btc、convertible_to_gt；历史记录 — id、create_time、currency、amount、gt_amount（create_time 通常为 Unix 秒）。

MCP 工具清单：

工具	类型	描述
gate-cli cex wallet balance small	查询	列出符合小额余额兑换条件的币种及预估 GT 数量
gate-cli cex wallet balance convert-small	写入	将选定币种或所有符合条件的零散余额兑换为 GT
gate-cli cex wallet balance small-history	查询	分页查看小额余额兑换历史记录

工作流

步骤 1：识别用户意图

判断用户是想查看符合条件的资产、兑换为 GT、查看历史记录，还是应从此 Skill 中排除。

意图路由：

意图	常见用户目标	下一步
list	查看可兑换的资产及预估 GT 数量	步骤 2
convert_selected	将指定币种兑换为 GT	步骤 2 → 步骤 3（交互式）
convert_all	兑换所有符合条件的零散余额	步骤 2 → 步骤 3（交互式）
convert_unspecified	想要兑换，但尚未指定币种	步骤 2 → 步骤 3（交互式）
history	查看过去的小额余额兑换记录	步骤 4
exclude	在现货市场卖出大额持仓，或保留指定币种	不调用兑换工具；改为引导或停止

排除规则：

• 用户想以限价或市价卖出高价值现货资产 → 引导至现货交易，而非此 Skill
• 用户明确表示要保留某些币种 → 不要将这些币种纳入 currencies，也不要在未获得明确同意的情况下设置 is_all: true

此步骤中不调用任何工具。

需要提取的关键数据：

• intent：list | convert_selected | convert_all | convert_unspecified | history | exclude
• currencies：选定兑换时使用的可选符号列表（例如 FLOKI、MBLK）
• is_all：用户要求兑换所有符合条件的资产时设为布尔值
• history_filters：历史记录的可选筛选项：currency、page、limit

步骤 2：查询符合条件的小额余额

调用时机：在以下情况下始终调用此步骤：

1. 意图为 list
2. 意图为 convert_selected、convert_all 或 convert_unspecified（在任何兑换操作之前）

调用 gate-cli cex wallet balance small，并传入：

• 无必填参数（可进行空参数调用）

需要提取的关键数据：

• 行列表：如果工具返回嵌套数组，请使用对象的内层数组（见上文负载说明）
• 每项数据：currency、available_balance、estimated_as_btc、convertible_to_gt
• 列表是否为空

展示方式：

• 列表非空：汇总数量，并显示包含 currency、available_balance、convertible_to_gt 的表格
• 列表为空：告知用户当前没有符合条件的小额余额资产

对于兑换意图：将符合条件的列表保存在上下文中，供步骤 3 验证时使用。

步骤 3：交互式兑换流程（如果意图为 convert_selected / convert_all / convert_unspecified）

此步骤强制采用交互式流程，确保用户在充分了解情况后做出决定。

3.1：验证用户指定的币种（如果用户指定了交易代码）

如果用户指定了 currencies（例如：“将 FLOKI 和 MBLK 兑换为 GT”）：

1. 将每种币与步骤 2 中的可兑换列表进行核对：

   • 如果某种币存在于可兑换列表中 → 标记为 available
   • 如果某种币不存在于可兑换列表中 → 标记为 not_eligible

2. 告知用户验证结果：

   • 对于可兑换的币：“✅ {CURRENCY} 可兑换（可用余额：{available_balance}，预计可兑换为 GT：{convertible_to_gt}）”
   • 对于不可兑换的币：“❌ {CURRENCY} 不在符合条件的小额余额列表中。其余额可能高于门槛，或该币种不受支持。”

3. 如果有些币种不符合条件，询问用户：

   • “以下币种不符合条件：{list}。您想仅兑换符合条件的币种（{eligible_list}），还是先查看完整的可兑换列表？”

3.2：引导用户选择（如果意图为 convert_unspecified 或用户想查看选项）

如果用户尚未指定要兑换哪些币种，或想查看可选项：

1. 显示完整的可兑换列表，包含以下列：

   • currency | available_balance | convertible_to_gt

2. 请用户选择：

   • “您想兑换哪些币种？您可以：”
   • “A）从上方列表中选择特定币种”
   • “B）兑换所有符合条件的币种”
   • “请告知您的选择（例如：‘FLOKI 和 MBLK’或‘全部’）”

3. 等待用户回复并提取以下信息：

   • 如果用户指定了币种 → 更新 currencies 列表，设置 is_all: false
   • 如果用户说“全部” → 设置 is_all: true

3.3：最终确认

调用兑换 API 前：

1. 概述将要兑换的内容：

   • 对于选定的币种：“即将兑换：{currencies}。预计 GT 总额：{sum of convertible_to_gt}”
   • 对于所有符合条件的币种：“即将兑换全部 {n} 种符合条件的币种。预计总额：{sum}”

2. 警告用户操作不可逆：

   • “⚠️ 此操作不可逆。兑换后，这些资产将按当前汇率转换为 GT。”

3. 明确征求确认：

   • “要继续吗？请回复 ‘yes’ 或 ‘confirm’ 进行确认。”

4. 仅在用户明确确认后继续操作。

3.4：执行兑换

用户确认后，调用 gate-cli cex wallet balance convert-small，并传入：

• currencies（字符串数组）：例如，兑换选定的交易代码时使用 ["FLOKI","MBLK"] — 同时设置 is_all: false
• is_all（布尔值）：设置为 true 可兑换所有符合条件的小额余额

需要提取的关键数据：

• 响应中的 success、message 以及任何 error_code / 错误字段
• 失败时：准确的错误消息（例如余额不足、触发速率限制）

成功后：用通俗语言确认兑换结果；不要编造 API 未返回的金额。

步骤 4：查询小额余额兑换历史（如果意图为 history）

调用 gate-cli cex wallet balance small-history，并传入：

• currency（可选，字符串）：按已兑换币种筛选
• page（可选，数字）：页码
• limit（可选，数字）：每页数量（默认值/最大值依 API 而定，通常最高为 100）

需要提取的关键数据：

• 记录列表：如适用，遵循与列表工具相同的嵌套解包规则（Payload 说明）
• 每条记录：id、create_time、currency、amount、gt_amount — 如果 create_time 是 Unix 秒数，则以易读格式显示

展示方式：

• 使用表格展示 id、create_time（易读格式）、currency、amount、gt_amount
• 如果列表为空，告知用户：“未找到兑换历史记录。”

步骤 5：整理并展示结果

使用“报告模板”部分。对于任何 API 错误，报告真实的代码和消息 — 切勿捏造成功结果。

错误处理

场景	处理方式
执行 gate-cli cex wallet balance small 后，符合条件的列表为空	友好提示：没有符合条件的小额资产
用户指定的币种不在符合条件的列表中	告知用户哪些币种不符合条件；询问是否继续处理符合条件的币种，或查看完整列表
BALANCE_NOT_ENOUGH 或余额相关错误	说明余额不足；不得声称操作成功
TOO_MANY_REQUESTS / 速率限制	请用户稍后重试；遵守钱包端点每 10 秒 200 次请求的限制
身份验证 / 权限错误	遵循 exchange-runtime-rules.md 中的授权指南
用户想要大额现货卖出	转到现货交易流程，而非小额余额兑换
缺少有效的兑换参数（既没有非空的 currencies 且 is_all: false，也没有 is_all: true）	停止操作，请用户选择代码或确认兑换全部
MCP / 网络故障	建议检查连接并重试；不得伪造结果

安全规则

• 绝不伪造兑换结果、GT 数量或 ID——仅报告 API 返回的真实信息
• 调用 gate-cli cex wallet balance convert-small 前始终确认：明确的币种列表或已确认兑换全部，并说明操作不可逆以及汇率免责声明（最终汇率以执行时为准）
• 用户想要兑换时，始终先查询符合条件的列表——绝不跳过展示可兑换资产，直接执行兑换
• 根据符合条件的列表验证用户指定的币种，并告知用户任何不符之处
• 不要兑换用户要求保留的币种
• 不要泄露 API 密钥或密钥信息
• 按 API 返回的原样显示数量，不得任意取整
• 风险提示：兑换不可逆；GT 价值随市场行情波动

判断逻辑摘要

条件	操作	工具
用户询问哪些零散余额 / 小额余额可以兑换	列出符合条件的资产	gate-cli cex wallet balance small
用户想整理钱包 / “我可以兑换哪些资产”	先列出，再在用户决定继续时提供兑换选项	gate-cli cex wallet balance small → 交互式步骤 3
用户指定要兑换为 GT 的代码	查询列表 → 验证币种 → 确认 → 执行	gate-cli cex wallet balance small → gate-cli cex wallet balance convert-small
用户表示兑换所有零散余额 / 小额币种	查询列表 → 展示兑换范围 → 确认 → 使用 is_all: true 执行	gate-cli cex wallet balance small → gate-cli cex wallet balance convert-small
用户想兑换但尚未指定币种	查询列表 → 请用户选择 → 确认 → 执行	gate-cli cex wallet balance small → 交互式选择 → gate-cli cex wallet balance convert-small
用户询问小额余额 / 零散余额兑换历史	使用可选筛选条件查询历史记录	gate-cli cex wallet balance small-history
用户想正常卖出大额现货持仓	排除；使用现货交易 Skill	—
用户拒绝兑换或要保留特定资产	不调用兑换工具	—
API 返回错误	停止操作；显示真实错误	—

报告模板

时间戳：适用时使用 ISO 8601 格式 YYYY-MM-DD HH:mm:ss UTC。

符合条件的小额余额报告

## Small Balances Eligible for GT Conversion

**Query Time**: {timestamp}

| Currency | Available | Est. BTC value | Est. GT |
|----------|-----------|----------------|---------|
| {currency} | {available_balance} | {estimated_as_btc} | {convertible_to_gt} |

**Summary**: {n} currencies eligible. (If empty: no eligible small-balance assets.)

兑换结果报告

## Small Balance Conversion

**Time**: {timestamp}
**Mode**: {Selected currencies: ... | All eligible}

**Result**: {success / failed}
**Message**: {message}

If failed: **Code**: {error_code_if_any}

历史记录报告

## Small Balance Conversion History

**Query Time**: {timestamp}
**Filters**: currency={currency or Any}, page={page}, limit={limit}

| ID | Time (UTC) | Currency | Amount | GT Received |
|----|--------------|----------|--------|-------------|
| {id} | {create_time — convert Unix seconds to readable time} | {currency} | {amount} | {gt_amount} |

币种验证报告（用于交互流程）

## Currency Validation

| Currency | Status | Available | Est. GT |
|----------|--------|-----------|---------|
| {currency} | ✅ Eligible | {available_balance} | {convertible_to_gt} |
| {currency} | ❌ Not eligible | — | — |

**Summary**: {n} of {m} specified currencies are eligible for conversion.