gate-exchange-transfer

解析 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 Exchange 转账（内部转账）

通用规则

⚠️ 停止——继续之前，必须阅读并严格遵循共享运行时规则。 阅读完所有规则之前，不要选择或调用任何工具。这些规则具有最高优先级。 → 阅读 ./references/gate-runtime-rules.md

• 仅使用本技能中明确列出的 gate-cli 命令。 即使其他接口提供了未在此处记录的命令，也绝不能在这些工作流中运行。

在 Gate 交易账户之间执行同一 UID 的内部转账，账户类型包括：现货、逐仓杠杆、永续合约、交割合约和期权。唯一执行端点：POST /wallet/transfers（MCP：gate-cli cex wallet transfer create）。 范围（第 1 阶段）

• 支持：仅限内部转账（同一 UID，在上述账户类型之间转账）。
• 不支持：主账户转子账户、子账户转主账户、子账户转子账户。

---

技能依赖

使用的 gate-cli 命令

查询操作（只读）

• gate-cli cex delivery account book
• gate-cli cex futures account book
• gate-cli cex margin account book
• gate-cli cex options account book
• gate-cli cex spot account book

执行操作（写入）

• gate-cli cex wallet transfer create

身份验证

• 交互式文件设置： 当主机上未同时设置 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——绝不要让用户在聊天中粘贴密钥。
• API Key 必需：是
• 权限： Delivery:Read、Fx:Read、Margin:Read、Options:Read、Spot:Read、Wallet:Write
• 门户： 请在聊天之外创建或轮换密钥：https://www.gate.com/myaccount/profile/api-key/manage

安装检查

• 必需： gate-cli（如果缺失，请在此技能目录中运行 sh ./setup.sh；可选 GATE_CLI_SETUP_MODE=release）。
• 如果按名称调用 gate-cli，请将 $HOME/.openclaw/skills/bin 添加到 PATH（或添加 setup.sh 安装它的目录）。
• 凭据： 当主机已设置非空的 GATE_API_KEY 和 GATE_API_SECRET 时，不要要求运行 gate-cli config init——这对 gate-cli 而言是等效的有效配置。当两者均未设置或为空时，提醒操作人员运行 gate-cli config init，或在技能库中的相应技能内配置 GATE_API_KEY / GATE_API_SECRET（绝不要让用户在聊天中粘贴密钥）。
• 健全性检查： 在进行经过身份验证的调用之前，不要继续操作，除非 CLI 行为符合预期（例如，运行 gate-cli --version，或运行本技能中的只读 gate-cli cex ... 命令）；在执行修改操作之前，确认凭据已正确解析。

执行模式

先阅读并严格遵循 references/gate-cli.md，然后执行本技能的转账工作流。

• SKILL.md 负责转账意图路由和账户类型映射。
• references/gate-cli.md 是转账前检查、确认关卡、执行和账本验证的权威 gate-cli 执行规范。

前提条件

前提条件	不满足时
用户已登录	不调用 API；提示用户登录（例外流程）。
已知账户模式	根据上下文推断，或假设为经典模式：现货 ↔ USDT 永续。对于统一账户／交易账户高级模式：交易账户 ↔ BTC 永续。
可核实来源余额	显示草稿前，调用余额 API 查询 from 账户；如果无法查询，提示用户在网页上检查。

---

四个要素

每笔内部转账都由四个要素完整定义。助手必须在显示转账草稿前确定或推断这些要素。

要素	API 参数	必填条件	说明
来源	from	始终必填	spot | margin | futures | delivery | options
目标	to	始终必填	与 from 使用相同枚举值
币种	currency	始终必填	USDT、BTC 等（平台支持的币种）。缺失 → 根据目标自动补全（case2）。
金额	amount	始终必填	字符串，大于 0，最多 8 位小数。缺失 → 询问用户（case8）。

条件参数

• margin：当 from 或 to 为 margin 时，必须填写 currency_pair（例如 BTC_USDT）。
• futures / delivery：当 from 或 to 为 futures 或 delivery 时，必须填写 settle（usdt | btc）。

---

公共 API（阶段 1）

端点	方法	含义	速率限制
/wallet/transfers	POST	同一 UID 的内部转账	80 req/10s

---

工具映射

分组	工具（jsonrpc: call.method）
主账户内部转账	gate-cli cex wallet transfer create

---

案例索引

案例	场景	操作
case1	四个要素齐全	显示转账草稿 → 确认 → 调用 API → 转账结果报告
case2	缺少币种	根据目标账户自动补全币种 → 按 case1 处理
case3	转账完成（API 成功）	输出转账结果报告 + 产品建议
case4	余额不足	预检查失败；不调用 API；显示差额并建议充值／调整
case5	缺少来源／目标或意图不明确	显示缺失信息卡片；不调用 API
case6	账户模式冲突（例如不允许交易账户 → USDT 永续）	解释原因并建议替代路径
case7	币种与目标账户不匹配（例如 USDT 转入 BTC 永续）	自动更正或提示用户更正 → 然后按 case1 处理
case8	缺少金额	询问金额；用户提供后，按 case1／case2 处理
case9	用户取消或在草稿后拒绝	确认收到；不调用 API
case10	确认不明确或已过期	重新显示草稿；要求用户明确回复“Confirm”／“Yes”；不执行
case11	触发速率限制／服务错误	不盲目重试；提示稍后重试或使用网页界面

---

转账草稿（执行前必须提供）

调用 gate-cli cex wallet transfer create 前，先输出转账草稿，并等待用户在紧接着的下一轮对话中明确确认。

草稿内容

• from（账户名称）
• to（账户名称）
• currency
• amount
• 如适用：settle（用于 futures/delivery）、currency_pair（用于 margin）

确认规则

• 确认视为单次有效。如果用户更改金额、币种或方向，必须显示新草稿并重新确认。
• 如果用户未明确确认（例如“Confirm”、“Yes”、“Proceed”），则不得执行（case10）。

---

转账结果报告（API 调用成功后）

• 确认成功：例如“转账成功。{amount} {currency} 已到账至您的 {to account name}。”
• 可根据目标建议下一步操作：现货 → 现货交易；USDT 永续 → USDT 本位永续交易；等等。
• 提及转账历史：例如 transfer/historyV2 或等效 MCP 工具。

---

案例逻辑和输出

case1：四项信息齐全

触发条件 “将 100 USDT 从我的现货账户转到永续合约账户” / “将 1000 USDT 从现货账户转到 USDT 本位合约账户” / “将 0.5 BTC 从币本位账户转到现货账户”

步骤

1. 确定 from、to、currency、amount；如有需要，添加 settle 或 currency_pair。
2. 预检查：获取源账户余额；如果余额 < 金额 → case4。
3. 输出 转账草稿。
4. 等待用户明确确认。
5. 调用 gate-cli cex wallet transfer create。
6. 输出 转账结果报告（case3）。 请求参数映射

意图	API 参数	取值
源账户	from	spot | margin | futures | delivery | options
目标账户	to	spot | margin | futures | delivery | options
币种	currency	USDT、BTC 等
金额	amount	字符串，> 0，最多 8 位小数
保证金交易对	currency_pair	如果 from/to 是 margin，则必填，例如 BTC_USDT
结算币种	settle	如果 from/to 是 futures 或 delivery，则必填：usdt | btc

---

case2：缺少币种，自动补全

触发条件 “转 100 到我的 USDT 本位账户” / “转 500 到合约账户” / “转 1000 到永续合约账户”

逻辑 根据目标账户设置 currency：

目标账户	默认币种
USDT 永续合约（futures settle=usdt）	USDT
BTC 永续合约（futures settle=btc）	BTC
TradFi	USDT
交割合约	USDT
期权	USDT
现货 / 保证金	根据上下文推断或询问

步骤 设置 currency 后，与 case1 相同。

输出（草稿） “检测到您要向 {to account name} 转入 {amount}。根据账户类型，默认币种为 {currency}。请确认。”

---

case3：转账完成（API 调用成功）

触发条件 用户已确认；gate-cli cex wallet transfer create 返回成功。

输出

• “转账成功。{amount} {currency} 已到账您的 {to account name}。”
• 可选：根据目标账户推荐产品（现货 / USDT 永续合约 / BTC 永续合约 / 交割合约 / 保证金 / TradFi / 期权）。
• “转账记录：transfer/historyV2”（或等效内容）。

---

case4：余额不足

触发条件 预检查：源账户可用余额 < 转账金额。

操作 不要调用转账 API。

输出 “您的 {from account name} 余额不足（可用余额：{available} {currency}）。请调整金额或先充值。”

---

case5：缺少 from/to 或意图不明确

触发条件 “合约快要被强平了，转些资金做保证金” / “给我的合约保证金账户充值” / “如何调整账户资金”

逻辑

• 如果 from、to、currency、amount 中至少缺少 2 项：显示信息缺失卡片并请用户补充。
• 仅能确定一侧时的默认值：
• 统一账户/交易账户高级模式：默认 from = 交易账户，to = BTC 永续合约。
• 经典模式：默认 from = 现货，to = USDT 永续合约。
• 四项信息明确前，不要调用 API。

输出 “我可以帮您补充保证金。请指定：转出账户、转入账户和币种（以及您知道的话，金额）。”

---

case6：账户模式冲突

触发条件 用户处于交易账户高级模式，并要求转账到 USDT 永续合约。在此模式下，可能不允许直接转账到 USDT 永续合约（该路径不可用）。 输出 “您当前处于交易账户模式，无法直接转账到 USDT 永续合约。您可以改为转账到 BTC 永续合约（币本位），或在网页端调整账户模式。”

---

case7：币种与目标账户不匹配

触发条件 “将一些 USDT 转到我的 BTC 永续合约账户”

逻辑 BTC 永续合约以 BTC 结算；USDT 与之不匹配。

• 选项 A：更正为 BTC 数量（如果符合用户意图）。
• 选项 B：说明 BTC 永续合约使用 BTC；建议转入 BTC，或使用 USDT 永续合约账户接收 USDT。
• 如果用户确认更正后的草稿（例如：现货 → BTC 永续合约，币种为 BTC），则按 case1 继续。

输出 “BTC 永续合约使用 BTC 结算。我已将转账币种更正为 BTC（或者：请指定 BTC 数量）。请确认。”或者：“若要转入 USDT，请改用 USDT 永续合约账户。”

---

case8：缺少数量

触发条件 “将 USDT 从现货转到期货” / “把我的 USDT 转到永续合约”（未指定数量）。 操作 询问：“您想将多少 {currency} 从 {from} 转到 {to}？”用户提供数量后，如果币种仍未明确，则按 case2 确定币种，然后按 case1 继续。

---

case9：用户取消或拒绝

触发条件 生成转账草稿后，用户说“No” / “Cancel” / “Don't do it” / “Never mind”。

操作 不要调用 API。确认：“转账已取消。未做任何更改。”

---

case10：确认含糊或已过时

触发条件 生成草稿后，用户回复的内容不是明确确认（例如提出新问题、指定不同数量，或在较长的对话中含糊地回复“ok”）。 操作 不要执行。重新展示转账草稿，并说明：“如需执行此转账，请明确确认（例如回复 ‘Confirm’ 或 ‘Yes’）。”

---

case11：速率限制或服务错误

触发条件 API 返回 TOO_MANY_REQUESTS 或发生服务端/网络错误。

操作 不要在同一轮对话中自动重试。 输出 “请求失败（速率限制 / 服务错误）。请稍后重试，或使用 Web 应用进行转账。”

---

异常流程摘要

异常	处理方式	阻止执行
未登录	提示登录	是
余额不足	显示差额 + 建议充值/调整（case4）	是
账户路径无效（例如不允许的转出/转入账户）	引导用户更正（case5/case6）	否，引导用户
用户取消 / 拒绝	确认收到（case9）	是
缺少确认/确认含糊	重新展示草稿，要求明确确认（case10）	是
速率限制 / 服务错误	稍后重试或使用 Web（case11）	是
风控 / 配额	清楚说明原因	是

---

API 参考

请求体示例

{
 "currency": "USDT",
 "from": "spot",
 "to": "futures",
 "amount": "100",
 "currency_pair": "",
 "settle": "usdt"
}

from / to → 产品名称

API 值	产品名称
spot	现货
margin	逐仓保证金
futures	永续合约（使用 settle）
delivery	交割合约
options	期权

settle（futures / delivery）

settle	账户
usdt	USDT 永续合约
btc	BTC 永续合约

currency_pair（保证金）

当 from 或 to 为 margin 时必填；例如 BTC_USDT。

---

转账历史查询

转账后，用户可能会查询历史记录。按账户类型区分：

账户	查询工具（如果 MCP 提供）	备注
现货	gate-cli cex spot account book	币种、时间、数量上限
永续合约	gate-cli cex futures account book	settle、type=dnw
交割合约	gate-cli cex delivery account book	settle、type=dnw
保证金	gate-cli cex margin account book	currency_pair、时间、数量上限
期权	gate-cli cex options account book	参见 MCP 文档

REST：交割合约 GET /delivery/{settle}/account_book?type=dnw；永续合约 GET /futures/{settle}/account_book?type=dnw；保证金 GET /margin/account_book。

---

错误代码

代码	含义
BALANCE_NOT_ENOUGH	余额不足；不要使用相同数量重试
TOO_MANY_REQUESTS	速率限制；提示稍后重试（case11）
QUOTA_NOT_ENOUGH	超出配额；显示提示信息

---

执行规则（摘要）

1. 单一端点：仅通过 POST /wallet/transfers (gate-cli cex wallet transfer create) 进行内部划转。第一阶段不支持主子账户划转。
2. 始终显示划转草稿，包含转出账户、转入账户、币种、金额（以及按需提供的 settle/currency_pair）。
3. 必须在用户下一轮明确确认；确认仅可使用一次；参数变更后需重新确认。
4. 调用 API 前预先检查余额；余额不足时，遵循 case4，不得调用 API。
5. 条件参数：保证金交易需提供 currency_pair；期货/交割合约需提供 settle。
6. 未提供币种：使用 case2 默认表。未提供金额：按 case8 询问。
7. 账户模式／币种不匹配：按 case6 和 case7 处理；执行前解决问题或更正信息。
8. 用户取消或确认不明确时：按 case9/case10 处理；不得执行。