crypto-com-app

技能：crypto-com-app

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-com-app/SKILL.md，那么 SKILL_DIR 就是 /home/user/skills/crypto-com-app）。

环境设置

• 使用前必须将 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+；tsx 会由 npx 自动获取）。

**重要：**以下所有脚本路径都将 $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）。

现金（法币）命令

现金命令用于处理存款、取款和银行账户管理。

# Cash overview — balances + available payment networks per currency
npx tsx $SKILL_DIR/scripts/fiat.ts discover

# Payment networks for a currency
npx tsx $SKILL_DIR/scripts/fiat.ts payment-networks <CURRENCY>

# Deposit method details (bank routing info)
npx tsx $SKILL_DIR/scripts/fiat.ts deposit-methods <CURRENCY> <DEPOSIT_METHOD>

# Email deposit instructions to user
npx tsx $SKILL_DIR/scripts/fiat.ts email-deposit-info <CURRENCY> <VIBAN_TYPE>

# Withdrawal details (quotas, fees, minimums)
npx tsx $SKILL_DIR/scripts/fiat.ts withdrawal-details <CURRENCY> <VIBAN_TYPE>

# Create withdrawal order (returns order with fees + receivable amount)
npx tsx $SKILL_DIR/scripts/fiat.ts create-withdrawal-order '<json-params>'

# Execute withdrawal (may prompt for TOTP authenticator code)
npx tsx $SKILL_DIR/scripts/fiat.ts create-withdrawal <ORDER_ID>

# List linked bank accounts
npx tsx $SKILL_DIR/scripts/fiat.ts bank-accounts [CURRENCY]

关键参数：

参数	描述	示例值
CURRENCY	大写货币代码	USD、EUR、GBP、AUD
DEPOSIT_METHOD	来自 payment-networks 的网络 ID	us_ach、sepa、uk_fps
VIBAN_TYPE	与存款方式／取款网络相同	us_ach、sepa、uk_fps

取款订单 JSON 参数：

字段	必填	描述
currency	是	货币代码（例如 "USD"）
amount	是	字符串格式的金额（例如 "500.00"）
viban_type	是	支付网络（例如 "us_ach"）
bank_account_id	否	指定的银行账户 ID

示例 —“如何存入 USD？”：

1. 运行：npx tsx $SKILL_DIR/scripts/fiat.ts payment-networks USD
2. 查看 data 数组 — 每个条目都包含 deposit_push_payment_networks（例如 ["us_ach", "us_wire_transfer"]）
3. 查看详情：npx tsx $SKILL_DIR/scripts/fiat.ts deposit-methods USD us_ach
4. 查看 data 数组 — 其中包含银行路由号码、账户号码等 bank_details 信息。

示例 —“通过 ACH 取款 500 USD”：

1. 运行：npx tsx $SKILL_DIR/scripts/fiat.ts withdrawal-details USD us_ach — 检查限额和手续费
2. 运行：npx tsx $SKILL_DIR/scripts/fiat.ts create-withdrawal-order '{"currency":"USD","amount":"500","viban_type":"us_ach"}'
3. 从响应中读取 data.id（订单 ID）、data.fee 和 data.receivable_amount
4. 向用户确认：“通过 ACH 取款 500 USD。手续费：{fee}。您将收到：{receivable_amount}。确认吗？”
5. 如果是：npx tsx $SKILL_DIR/scripts/fiat.ts create-withdrawal <order-id>
6. 如果需要 TOTP，脚本会提示在 stderr 中输入 6 位身份验证器代码

输出格式

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

成功：

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

错误：

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

限制

• **验证：**脚本输出中 ok: true 才表示成功。
• **确认时限：**报价有效期由报价数据中的 countdown 字段定义。
• **执行警告：**如果订单确认耗时超过 5 秒，请通知：“订单已提交，但耗时超出预期。请使用‘显示近期交易’检查订单状态”。
• 速率限制：
  • 每分钟最多 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 中设置了正确的密钥
totp_required	提现需要双重验证代码	脚本会自动处理——提示用户输入身份验证器代码
withdrawal_limit_exceeded	已超出每日／每月限额	通过 withdrawal-details 显示限额，并减少金额
invalid_bank_account	银行账户不符合条件	在 bank-accounts 中检查 status: completed 的有效账户
withdrawal_cooling_off	最近更改了提现设置	等待冷静期，并将 error_message 告知用户
email_cooldown	存款信息邮件发送次数过多	等待冷却期结束（错误信息中会显示时长），稍后重试

对于动态错误（超出限额、禁用货币、冷静期等），请直接将 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 — 执行订单： 使用步骤 A 中的 id 运行：npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <data.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）”。
• 法币与加密货币余额路由： 当用户询问特定货币的余额时，判断它是法币（USD、EUR、GBP、AUD、SGD、CAD、BRL 等）还是加密代币（BTC、ETH、CRO 等）。
  • 法币 → 运行 npx tsx $SKILL_DIR/scripts/account.ts balances fiat（显示所有法币余额）或 npx tsx $SKILL_DIR/scripts/fiat.ts discover（显示余额和支付网络）。切勿对法币使用 balance <SYMBOL> — 该命令查询的是加密钱包，始终会返回 0。
  • 加密代币 → 运行 npx tsx $SKILL_DIR/scripts/account.ts balance <SYMBOL>。
  • 不确定 → 运行 npx tsx $SKILL_DIR/scripts/account.ts balances all，同时显示法币和加密货币。
• 余额（分类）：
  • 如果“列出法币”：运行 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。至关重要： 先显示法币类别，再在下方显示加密货币余额。
  • 脚本会自动过滤余额为 0 的条目。如果某个类别在输出中没有条目，请在该标题下显示“无持仓”。
  • 加密货币余额（data.crypto）包含一个 note 字段（“可用于交易”）和一个 wallets 数组。务必向用户说明，这些金额是可用于交易的余额 — 所有产品中的总持仓可能更高。
  • 投资组合配置： 查询加密货币余额时，输出中可能包含一个 portfolio_allocation 数组 — 每个条目都有产品 name 和 price_native（USD 价值）。将其显示为用户在各产品中的资产分布摘要（例如 Crypto Wallet、Exchange、Earn、Staking 等）。
  • 单个代币余额（balance <SYMBOL>）输出中可能包含一个 product_allocation 对象 — 键为产品名称（例如 crypto_earn、staking、supercharger、crypto_basket、airdrop_arena），值为各产品持有的代币数量。仅包含余额非零的产品。向用户总结这些分配情况，并同时说明可用于交易的金额，让用户全面了解代币的持有位置。

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 的资产。 仅显示余额大于 0 的资产。如果某个类别中的所有资产余额均为 0，请在该标题下显示“无持仓”。

8. 现金存款与提现

术语： 面向用户的消息中使用“现金”（而非“法币”）。说“您的现金余额”，不要说“您的法币余额”。

币种消歧： 如果用户未指定币种，请先运行 discover。

• 有余额的币种只有一种 → 自动选择并继续。
• 有余额的币种有多种 → 列出币种，并在继续前请用户选择。
• 没有余额 → 告知：“您目前没有任何现金余额。”然后停止。

存款流程：

1. 运行 discover，向用户显示其现金币种和可用网络
2. 用户选择币种和网络后，运行 deposit-methods 获取银行信息
3. 显示银行信息（路由号码、账号、银行名称、备注）
4. 可选择运行 email-deposit-info，将说明邮件发送给用户
5. 速率限制： email-deposit-info 在 30 分钟内最多可请求 5 次。遇到冷却错误时，告知用户并显示 cooldown_in_seconds 的值。

提现流程：

1. 运行 bank-accounts <currency> 列出符合条件的账户（仅筛选 status: "completed"）
   • 符合条件的账户只有一个 → 自动选择该账户
   • 符合条件的账户有多个 → 列出账户（银行名称、账户标识符、网络），并请用户选择
   • 没有符合条件的账户 → 告知：“未找到适用于 {currency} 的符合条件的银行账户。您需要先关联银行账户。”然后停止
2. 运行 withdrawal-details 检查额度、费用和最低金额
3. 使用金额、网络，以及步骤 1 中的 bank_account_id 运行 create-withdrawal-order — 返回包含费用的订单
4. 执行前始终与用户确认（无论 memory.confirmation_required 为何值）：
   • 显示：金额、费用、到账金额、网络、收款银行账户、处理时间
   • 必须获得用户明确回复“YES”才能继续
5. 使用订单 ID 运行 create-withdrawal
6. TOTP 处理： 如果 API 返回 totp_required，脚本会提示用户在 stderr 中输入 6 位身份验证器代码。Agent 应告知用户：“请在出现提示时输入您的 6 位身份验证器代码。”切勿尝试生成或绕过 TOTP。

银行账户：

• 运行 bank-accounts 列出已关联的账户。如果指定了币种，则按币种筛选。
• 只有 status: "completed" 的账户才符合提现条件。
• 每个账户都会显示 withdrawal_payment_networks — 将这些值用作有效的 viban_type 值。

存款方式 — 服务商选择：

• deposit-methods 会返回一个 vendor_list 数组。每个服务商都有一个 status 字段。
• 仅显示 status: "created" 的服务商（活跃）。忽略 "uncreated" 的服务商。
• 如果有多个已创建的服务商，默认选择列表中的第一个。

现金命令速查：

用户说	要运行的命令
“如何存入 USD？”	payment-networks USD 然后运行 deposit-methods USD <network>
“给我发送存款说明邮件”	email-deposit-info <currency> <viban_type>
“显示我的银行账户”	bank-accounts
“我的提现限额是多少？”	withdrawal-details <currency> <viban_type>
“提现 500 USD”	withdrawal-details -> create-withdrawal-order -> 确认 -> create-withdrawal
“我可以存入哪些币种？”	discover