crypto-agent-trading

技能：加密货币 Agent 交易

Agent 能力要求

此技能要求你的 Agent 平台支持以下能力。如果平台缺少任何必需能力，此技能将无法运行。

能力	必需	详情
Shell 命令执行	是	必须能够运行 npx tsx ./scripts/... 并捕获 stdout
环境变量	是	必须能够从 shell 环境中读取 CDC_API_KEY 和 CDC_API_SECRET
JSON 解析	是	必须能够解析脚本 stdout 中的结构化 JSON，以提取字段
多轮对话	是	交易使用报价 → 确认流程，需要跨多个用户轮次
持久记忆	否	用于 confirmation_required 偏好设置。如果不支持，默认始终确认交易
经过时间感知	否	用于检查报价是否过期（countdown 字段）。如果不支持，始终尝试确认，并妥善处理 invalid_quotation 错误

关键：此技能的工作方式

所有 API 交互都必须使用 TypeScript 脚本。绝不能使用 curl、fetch 或任何其他 HTTP 方法直接调用 API。

脚本负责请求签名、错误处理和响应格式化。如果绕过脚本：

• 请求将失败（缺少 HMAC 签名）
• 响应不会经过筛选或结构化处理

对于每个用户请求，请在下方找到匹配的命令，并通过 npx tsx 运行。读取 JSON 输出，并据此采取行动。

配置

• BASE_URL：https://wapi.crypto.com
• CDC_API_KEY：{{env.CDC_API_KEY}}
• CDC_API_SECRET：{{env.CDC_API_SECRET}}
• CONFIRMATION_REQUIRED：{{memory.confirmation_required}}（默认：true）
• SKILL_DIR：包含此 SKILL.md 文件的目录。根据加载此文件时使用的路径确定它的位置（例如，如果你读取的是 /home/user/skills/crypto-agent-trading/SKILL.md，那么 SKILL_DIR 就是 /home/user/skills/crypto-agent-trading）。

环境设置

• 使用前必须将 CDC_API_KEY 和 CDC_API_SECRET 都设为环境变量。

• 运行任何脚本之前，先运行以下命令检查这两个变量是否都已设置：

  echo "CDC_API_KEY=${CDC_API_KEY:+set}" "CDC_API_SECRET=${CDC_API_SECRET:+set}"
  

  如果任一变量的输出为空，而不是 set，请提示用户：

  “你的 API 凭据尚未配置。请先在终端中设置，然后我才能继续：

  export CDC_API_KEY="your-api-key"
  export CDC_API_SECRET="your-api-secret"
  

  你可以在 https://help.crypto.com/en/articles/13843786-api-key-management 生成 API 密钥。 设置完成后请告知我。”

  然后停止并等待用户确认，再重试。

• 如果脚本返回 MISSING_ENV 错误，请按相同方式提示用户设置变量并等待。

脚本命令

所有 API 交互都必须通过这些脚本完成。 脚本负责签名、执行、筛选和错误格式化。通过 shell 运行下方相应的命令，然后解析 JSON 输出。

前置条件： npx tsx（需要 Node.js 18+；npx 会自动获取 tsx）。

重要： 下方所有脚本路径都使用 $SKILL_DIR 作为此技能根目录的占位符。请根据加载此 SKILL.md 文件时使用的路径确定该目录，或切换到技能目录并使用 ./scripts/... 作为路径。两种方式均可。

账户命令

# Filtered non-zero balances (scope: fiat | crypto | all)
npx tsx $SKILL_DIR/scripts/account.ts balances [fiat|crypto|all]

# Single token balance lookup
npx tsx $SKILL_DIR/scripts/account.ts balance <SYMBOL>

# Weekly trading limit
npx tsx $SKILL_DIR/scripts/account.ts trading-limit

# Find funded source wallets for a trade type
npx tsx $SKILL_DIR/scripts/account.ts resolve-source <purchase|sale|exchange>

# Kill switch — revoke API key
npx tsx $SKILL_DIR/scripts/account.ts revoke-key

交易命令

交易采用两步流程：先获取报价，再确认订单。

# Step 1 — Get quotation (type: purchase | sale | exchange)
npx tsx $SKILL_DIR/scripts/trade.ts quote <type> '<json-params>'
# Returns: {"ok": true, "data": {"id": "<quotation-id>", "from_amount": {...}, "to_amount": {...}, "countdown": 15, ...}}

# Step 2 — Confirm order: pass the data.id from Step 1 as <quotation-id>
npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <quotation-id>

# View recent transactions
npx tsx $SKILL_DIR/scripts/trade.ts history

如何将用户意图映射到交易类型：

用户说	交易类型	从	到
“用 100 USD 购买 CRO”	purchase	USD（法币）	CRO（加密货币）
“卖出 0.1 BTC”	sale	BTC（加密货币）	USD（法币）
“将 0.1 BTC 兑换为 ETH”	exchange	BTC（加密货币）	ETH（加密货币）

不同交易类型对应的报价 JSON 参数：

类型	JSON 字段
purchase	{"from_currency":"USD","to_currency":"CRO","from_amount":"100"} 或改用 to_amount
sale	{"from_currency":"BTC","to_currency":"USD","from_amount":"0.1","fixed_side":"from"}
exchange	{"from_currency":"BTC","to_currency":"ETH","from_amount":"0.1","side":"buy"}

示例——“用 100 USD 购买 CRO”：

1. 运行：npx tsx $SKILL_DIR/scripts/trade.ts quote purchase '{"from_currency":"USD","to_currency":"CRO","from_amount":"100"}'
2. 从响应中读取 data.id、data.from_amount、data.to_amount 和 data.countdown。
3. 如果需要确认（默认）：询问用户：“确认用 100 USD 购买 X CRO？报价有效期为 {countdown}s。回复‘YES’继续。”
   • 如果用户在倒计时结束前回复 YES：npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id>
4. 如果用户选择不再确认（memory.confirmation_required 为 false）：跳过询问，立即运行 npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id>

**启用/停用确认：**用户可以说“停止询问确认”以自动执行交易，也可以说“需要确认”以重新启用确认提示。请参阅下文第 3 节。

币种发现命令

# Search coins
npx tsx $SKILL_DIR/scripts/coins.ts search '{"keyword":"BTC","sort_by":"rank","sort_direction":"asc","native_currency":"USD","page_size":10}'

必需的 JSON 参数：

参数	类型	允许的值
sort_by	字符串	rank、market_cap、alphabetical、volume、performance
sort_direction	字符串	asc、desc
native_currency	字符串	大写的货币代码（例如 USD）
keyword	字符串	搜索字符串，长度为 1–100 个字符；仅匹配币种名称和代码
page_size	整数	每页结果数

可选：page_token——用于获取下一页的不可读令牌（请参阅下文的分页说明）。

**分页：**响应中包含一个 pagination 对象，其中有 has_more（布尔值）和 next_page_token（字符串）。当 has_more 为 true 时，在下一次请求中将 next_page_token 作为 page_token 传入，以获取下一页。

每种币的关键响应字段：rails_id（与交易和账户 API 中的 currency_id / currency 相同——可用它进行交叉引用）、price_native、price_usd、percent_change_*_native（过去各时间段的价格表现，例如 percent_change_24h_native）。

输出格式

每个脚本都会将结构化 JSON 输出到 stdout：

成功：

{"ok": true, "data": { ... }}

错误：

{"ok": false, "error": "ERROR_CODE", "error_message": "Human-readable message"}

约束

• **验证：**脚本输出中必须包含 ok: true 才算成功。
• **确认时限：**报价有效期由报价数据中的 countdown 字段决定。
• **执行警告：**如果订单确认耗时超过 5s，请通知用户：“订单已提交，但耗时超出预期。请使用‘显示近期交易’检查订单状态。”
• 速率限制：
  • 每分钟最多 10 笔交易。
  • 每分钟最多 100 次 API 调用。
  • 遇到 HTTP 429（RATE_LIMITED 错误）时：等待 60 秒后重试相同请求。请告知用户：“已达到速率限制——请等待 60 秒后再试。”

错误处理

所有脚本都会返回结构化错误。解析 error 字段，以确定适当的响应。

脚本错误代码

以下是脚本 JSON 输出中的 error 值，用于说明失败的类别。

错误代码	含义	Agent 响应
MISSING_ENV	未设置 CDC_API_KEY 或 CDC_API_SECRET	告知用户通过终端设置环境变量
API_ERROR	API 返回非 200 状态码或 ok !== true	报告：“交易失败：{error_message}”
INVALID_ARGS	命令行参数无效	根据 error_message 显示正确用法
QUOTATION_FAILED	API 拒绝了报价请求	向用户报告 error_message（参见下方的 API 错误）
EXECUTION_FAILED	订单确认失败	报告错误并建议：“使用‘显示最近交易’检查订单状态”
API_KEY_NOT_FOUND	密钥已被撤销或不存在	“未找到 API 密钥 — 该密钥可能已被撤销。”
RATE_LIMITED	请求过多（HTTP 429）	“已达到速率限制 — 请等待 60 秒后再试。”
UNKNOWN	未预期的错误	报告原始 error_message

规则： 当输出中的 ok 为 false 时，停止当前操作，并按照上述指引向用户报告错误。失败后绝不要继续下一步。

常见 API 错误（快速参考）

以下是出现在 QUOTATION_FAILED、EXECUTION_FAILED 或 API_ERROR 响应的 error_message 中的具体 API 错误代码，用于说明 API 拒绝请求的原因。

error	含义	处理方法
not_enough_balance	资金不足	检查余额，减少交易金额
invalid_currency	无法识别货币代码	通过币种搜索进行验证
invalid_quotation	报价已过期或已使用	请求新报价
failed_to_create_quotation	报价引擎错误	稍后重试
not_eligible_for_prime	不符合 Prime 福利资格	不使用 Prime 继续操作
unauthorized	账户未获准交易	联系支持团队
restricted_feature	账户受限，无法使用此功能	向用户报告 error_message
existing_currency_order_error	已有订单正在进行	等待或取消现有订单
viban_purchase_not_enabled	未启用法币兑换加密货币	账户未提供此功能
crypto_viban_not_enabled	未启用加密货币兑换法币	账户未提供此功能
bank_transfer_not_enabled	未启用银行转账	账户未提供此功能
missing_parameter	缺少必需参数	脚本错误 — 请报告此问题
failed_to_create_transaction	交易创建失败	重试或联系支持团队
key_not_active	API 密钥已撤销或过期	生成新的 API 密钥并更新环境变量
api_key_not_found	密钥不存在或属于其他用户	确认 CDC_API_KEY 中设置的是正确的密钥

对于动态错误（超出限额、禁用货币、冷静期等），请将 error 和 error_message 直接报告给用户。完整详情请参阅 references/errors.md。

---

逻辑与规则

1. 资产与来源消歧

首先确定交易类型：

• 购买 — 法币 → 加密货币
• 出售 — 加密货币 → 法币
• 兑换 — 加密货币 → 加密货币

然后确定来源钱包：

• 对于购买：运行 npx tsx $SKILL_DIR/scripts/account.ts resolve-source purchase。脚本只返回有资金的法币条目。
• 对于出售或兑换：运行 npx tsx $SKILL_DIR/scripts/account.ts resolve-source sale（或 exchange）。脚本只返回有资金的加密货币条目。

结果（来自 data.status）：

• SELECTED → 自动选择 data.currency。
• AMBIGUOUS → 提示用户从 data.options 中选择。
• EMPTY → 告知用户“未找到有资金的钱包”并停止。

**“全部卖出”场景：**如果用户说“卖出全部 [TOKEN]”，运行 npx tsx $SKILL_DIR/scripts/account.ts balance [TOKEN]。将 data.available 中的金额（或 data.balance）用作报价的 from_amount。

2. 交易流程（报价 → 确认 → 执行）

当用户要求买入、卖出或兑换加密货币时，始终遵循以下三步流程：

• **步骤 A — 获取报价：**根据用户的请求构建 JSON 参数（参见 Trade Commands 中的“Quotation JSON params”表），并运行： npx tsx $SKILL_DIR/scripts/trade.ts quote <type> '<json-params>' 从响应中读取 data.id、data.from_amount、data.to_amount 和 data.countdown。

• 步骤 B — 请求用户确认：

  • 如果 memory.confirmation_required 为 true（或未设置）：
    • 提示：“确认：用 {from_amount} 换取 {to_amount}？报价有效期为 {countdown} 秒。回复‘YES’以继续。”
    • **过期逻辑：**如果用户在 countdown 秒后回复“YES”，则拒绝：“交易已拒绝：报价汇率已过期。请重新请求报价。”
    • 只有用户在有效期内回复“YES”时，才执行步骤 C。
  • 否则（已选择关闭确认）：
    • 通知：“已收到报价。正在自动继续执行……”
    • 立即继续执行步骤 C。

• **步骤 C — 执行订单：**运行：npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <data.id>，使用步骤 A 中的 id。

3. 记忆管理（选择启用/关闭）

• **关闭确认：**如果用户说“停止询问确认”或“启用自动交易”，将 memory.confirmation_required 更新为 false。
• **启用确认：**如果用户说“需要确认”或“启用手动交易”，将 memory.confirmation_required 更新为 true。
• **不支持持久化记忆的平台：**如果你的平台不支持 {{memory.*}}，则始终将 confirmation_required 视为 true（最安全的默认设置）。

4. 错误处理

• 所有脚本输出都包含 ok 字段。成功的唯一判定条件是 ok: true。
• 如果 ok 为 false，读取 error，并根据上方的错误处理表作出响应。
• 命令失败后，绝不要继续执行下一步。

5. 账户与历史记录

• **历史记录：**运行 npx tsx $SKILL_DIR/scripts/trade.ts history — 显示 data 中的条目。
• **每周交易限额：**运行 npx tsx $SKILL_DIR/scripts/account.ts trading-limit — 按以下格式显示：“📊 每周交易限额：{data.used} / {data.limit} USD（剩余：{data.remaining} USD）”。
• 余额（分类）：
  • 如果是“列出法币”：运行 npx tsx $SKILL_DIR/scripts/account.ts balances fiat。
  • 如果是“列出加密货币”：运行 npx tsx $SKILL_DIR/scripts/account.ts balances crypto。
  • 如果是“列出全部”：运行 npx tsx $SKILL_DIR/scripts/account.ts balances all。**重要：**先显示法币类别，再在下方显示加密货币余额。
  • 脚本会自动过滤余额为零的条目。如果某个类别没有条目输出，则在该标题下显示“无持仓”。

6. 紧急停止开关

• 触发条件： 用户说出“STOP ALL TRADING”“kill switch”或类似的紧急停止命令。
• 始终要求明确确认，无论 memory.confirmation_required 的值为何：
  • 提示：“⚠️ 警告：这将立即撤销你的 API 密钥并禁用所有交易。要恢复交易，必须生成新的 API 密钥。输入 ‘CONFIRM KILL SWITCH’ 以继续。”
  • 只有用户回复完全一致的短语时才执行。
• 执行： 运行 npx tsx $SKILL_DIR/scripts/account.ts revoke-key。
• 成功时（ok: true）： 通知：“🛑 紧急停止开关已启用。API 密钥已撤销。所有交易均已禁用。要恢复交易，请生成新的 API 密钥并更新环境变量。”
• 发生 API_KEY_NOT_FOUND 错误时： 通知：“未找到 API 密钥——它可能已被撤销或不存在。”
• 幂等性： 撤销已撤销的密钥不算错误；按撤销成功处理。

7. 余额显示格式

• 法币标题： “🏦 法币余额”
• 加密货币标题： “🪙 加密货币余额”
• 同时请求法币和加密货币时，始终先列出法币部分，再列出加密货币部分。
• 绝不显示余额为零的资产。 只显示余额大于 0 的资产。如果某个类别中的所有资产余额均为零，则在该标题下显示“无持仓”。