coinank-openapi

概述

CoinAnk OpenAPI 提供加密货币衍生品市场数据，包括 K 线、ETF、未平仓合约、看多／看空比例、资金费率、强平、订单流、大户活动及相关分析。可用时使用 API 密钥直接进行身份验证；如果 CoinAnk 返回支付质询，则通过最新版 OKX 支付技能使用 Agent Payments Protocol / x402 按次付费访问。

使用前检查

使用此技能前，请确保：

1. 查看用户请求的市场数据任务；需要端点详情时，从 references/ 下选择匹配的参考 OpenAPI 文件。
2. 如果有 COINANK_API_KEY，请使用 API 密钥模式，并且仅在 apikey 请求标头中发送该密钥。
3. 如果没有 API 密钥，先发送原始请求；只有在收到真实的 HTTP 402 Payment Required 质询或 OKX 支付技能要求 charge 时，才开始处理 Agent Payments Protocol / x402 支付。
4. 对于付费质询，使用 okx-agent-payments-protocol；不要在此技能中手动实现钱包签名。
5. 执行金额大于零的任何支付前，都要向用户确认。金额为零的质询有效，必须保持为零。

命令

这是一个仅包含技能的插件。以下命令名称描述的是 Agent 工作流，而非随插件发布的本地二进制文件。

coinank-openapi quickstart

当用户刚开始使用此插件或尚未选择访问模式时使用。说明 API 密钥访问、Agent Payments Protocol / x402 按次付费访问，以及 OKX 支付技能要求时使用的 OKX charge 支付方式。

输出：推荐的访问模式、所需前提条件，以及最安全的下一项请求。

示例：在首次请求 CoinAnk 数据前，请 Agent 运行 coinank-openapi quickstart 流程。

coinank-openapi query-market-data

当用户请求 CoinAnk 市场数据时使用，例如 K 线、资金费率、强平、未平仓合约、看多／看空比例、订单流、ETF 数据、大户活动或热门交易对。

输出：根据所选 CoinAnk 端点生成简明答复，包括使用的关键参数，以及遇到的访问或支付要求。

示例：请求 BTC 资金费率、ETH 强平热力图数据，或 Binance BTCUSDT 未平仓合约。

coinank-openapi use-api-key

当有 COINANK_API_KEY 或用户希望直接使用会员访问权限时使用。使用 apikey 标头发送请求；除非用户明确要求，否则不要启动按次付费流程。

输出：最终 API 响应摘要，或清晰的身份验证／API 级错误。

示例：使用用户的 CoinAnk API 密钥查询 /api/fundingRate/current。

coinank-openapi pay-per-call

仅在 CoinAnk 返回真实的 HTTP 402 Payment Required 质询，或 OKX 支付技能指出需要支付流程后使用。将支付执行委托给 okx-agent-payments-protocol，包括生成 x402 证明，或在需要时使用较新的 charge 方法。

输出：面向用户的支付摘要；金额大于零时请求确认；支付成功后返回重新发送请求所得的 API 响应。

示例：完成金额为零的支付质询时，不要将 0 强行改为 0.000001；然后使用生成的支付数据重新发送相同请求。

访问模式

此技能支持两种访问方式：

1. 直接模式 —— 在 apikey 请求标头中使用 COINANK_API_KEY。
2. 按次付费模式 —— 当 CoinAnk 返回 HTTP 402 Payment Required 质询时，通过 Agent Payments Protocol 或 x402 付款，然后重新发送相同请求。

COINANK_API_KEY 是可选项。如果没有该密钥，技能仍必须尝试发现可用的访问方式，并在可用时使用 Agent Payments Protocol 或 x402。

新用户引导

新用户开始使用此技能时，请明确说明可用的访问方式：

• 如果用户已有 CoinAnk API 会员资格，请告知他们提供 COINANK_API_KEY。
• 如果用户没有 CoinAnk API 会员资格，请告知他们仍可在 CoinAnk 返回支付质询时尝试使用 Agent Payments Protocol 或 x402 按次付费访问。
• 不要将 API 会员资格说成使用此技能的唯一方式。

Agent Payments Protocol / x402 的依赖项

Agent Payments Protocol / x402 按次付费模式依赖 OKX Onchain OS 支付技术栈：

• okx-agent-payments-protocol
• okx-agentic-wallet

请使用最新版本的 okx-agent-payments-protocol 技能。它支持为 Agent Payments Protocol / x402 质询生成支付证明，也支持较新的 charge 支付方式。不要将较旧的、仅支持 x402 的流程写死；请将支付执行交由 okx-agent-payments-protocol 处理，并遵循该技能返回或要求的支付方式。

如果需要使用 Agent Payments Protocol、x402 或 charge 支付流程，但这些技能不可用，请告知用户先安装或更新 okx/onchainos-skills。

零金额支付质询

金额为 0 的 Agent Payments Protocol / x402 质询有效，必须予以支持。不要将零金额质询视为格式错误、未支付或不受支持。

当质询金额为 0 时：

• 明确告知用户，此请求需要支付证明，但费用为零。
• 继续使用 okx-agent-payments-protocol，按照原始零金额生成所需的证明或授权。
• 使用生成的支付标头重新发送完全相同的请求。
• 不要将 0 替换为任何备用金额、最低金额、微小金额或小额金额，例如 0.000001 USDC/USDT。
• 不要仅因为金额为零就要求确认付费调用，但仍须遵循钱包或协议对签署／授权证明的任何确认要求。

Agent Payments Protocol / x402 签名方案限制

对支付质询进行签名时，签名方案必须与签名者类型匹配：

• EOA 私钥 -> 使用 exact 方案。
• OKX 合约钱包 / OKX 钱包会话签名 -> 使用 aggr_deferred 方案。

请勿混用这两种方式：

• 对 EOA 私钥签名，不要使用 aggr_deferred。
• 对 OKX 合约钱包签名，不要使用 exact。

运行模式

此技能必须按需加载。默认情况下不要读取所有 OpenAPI 文件。只加载处理用户请求所需的架构。

必需工作流

处理用户请求时，请严格遵循以下顺序：

1. 阅读项目 README 在发出任何请求之前阅读 README.md，以遵循文档中说明的约定、访问模式和边缘情况。

2. 确定相关 API 类别 扫描 {baseDir}/references/ 下的文件名，确定与用户请求匹配的 OpenAPI 文件。

3. 仅读取所需架构 仅打开选定的 .json 文件，并检查其 paths、参数、响应结构和端点专属限制。在 paths 对象中，每个键都是一个 API 路径。

4. 验证请求参数 确认必需参数、受支持的枚举值，以及端点是否接受 endTime、size、interval 或 exchanges 等可选字段。

5. 选择访问策略

   • 如果存在 COINANK_API_KEY，优先使用直接模式。
   • 如果不存在 COINANK_API_KEY，则使用发现模式：不带 API 密钥发送原始请求，并由服务告知该路由是公开的、可通过 Agent Payments Protocol 或 x402 付费访问的，还是仍需会员资格才能使用的。

6. 构造原始请求 构造用户要求的确切请求。

   • 基础 URL：除非架构指定了其他服务器，否则使用 https://open-api.coinank.com。
   • 身份验证：
     • 直接模式：发送 apikey: $COINANK_API_KEY
     • 发现模式：不要发送 apikey，在看到真实的 402 之前不要伪造任何付款标头
   • 时间戳：如果端点接受 endTime，除非用户明确指定了其他时间，否则优先使用当前的毫秒时间戳。
   • 示例：OpenAPI 示例字段中的时间戳仅为历史示例，不得直接复用。

7. 先发送原始请求 在尝试钱包登录、付款签名或构造付款标头之前，务必先发送原始请求。

8. 解读响应

   • HTTP 2xx + 业务代码 "1"：返回结果。
   • HTTP 402：此路由需要付款。切换到 Agent Payments Protocol / x402 付款流程。
   • HTTP 2xx + 业务代码 "-3"：
     • 如果提供了 API 密钥，将其视为无效或权限不足，并告知用户修复其 CoinAnk 访问权限。
     • 如果未提供 API 密钥，且未返回 HTTP 402 挑战，则说明请求未进入 Agent Payments Protocol / x402 付款流程，仍需有效权限才能完成请求。
   • 其他失败：清楚说明失败，并指出关键技术原因。

9. 仅在确认确实需要付款后运行 Agent Payments Protocol / x402 付款流程 使用 okx-agent-payments-protocol，并遵循其确认、登录、签名、扣款和重放流程。

   • 对于 HTTP 402 Payment Required 挑战，生成所需的 Agent Payments Protocol / x402 付款凭证，并重放相同请求。
   • 如果最新的 OKX 付款技能表明或要求使用更新的 charge 付款方式，则使用该 charge 流程，而不是强行采用旧版的纯 x402 凭证流程。
   • 在确认存在实际付款要求之前，不要检查钱包状态。
   • 不要提前登录。
   • 不要试探性扣款。
   • 如果挑战金额为 0，将其视为有效的零金额付款挑战，并仍使用精确的 0 生成所需凭证或授权；绝不要将其强制转换为 0.000001 或任何其他非零最低金额。
   • 使用 EOA 私钥签名时，如果 OKX 付款流程采用 x402 凭证签名，请使用 exact 方案。
   • 使用 OKX 合约钱包 / 钱包会话签名时，如果 OKX 付款流程采用 x402 凭证签名，请使用 aggr_deferred 方案。

10. 重放完全相同的请求 OKX 付款流程完成后，使用相同的方法、URL、查询参数和请求正文重放请求。只添加所选 Agent Payments Protocol / x402 或 charge 流程所需的付款标头或授权数据。

11. 返回最终的付费响应 返回重放请求的成功结果，而不是中间的 402 负载。

多次调用防护

如果用户要求进行范围较广的分析，且很可能需要多次付费 API 调用，同时没有有效的 COINANK_API_KEY，则停止操作并提醒用户此任务可能产生多笔 Agent Payments Protocol / x402 付款。在触发多次调用的付费工作流之前，先征求用户确认。

关键规则

• 不要批量加载架构 除非用户明确要求进行跨类别分析，否则不要一次打开多个 OpenAPI JSON 文件。

• 不要臆造参数 只传入所选架构中定义的参数。添加额外参数可能会导致某些端点返回空结果。

• 不要臆造付款支持 只有当 CoinAnk 实际返回 HTTP 402 Payment Required 挑战时，才将请求视为可通过 Agent Payments Protocol / x402 付款。挑战金额为 0 仍是有效的付款挑战，在生成证明的整个过程中必须始终保持为零。

• 不要混用签名方案 EOA 私钥签名使用 exact，OKX 合约钱包或 OKX 钱包会话签名使用 aggr_deferred。

• 不要绕过挑战 除非已经收到针对当前确切请求的真实 402 响应，否则绝不要尝试进行 Agent Payments Protocol / x402 签名。

• 不要修改付费请求 重放的请求必须与原始请求完全一致，唯一区别是付款标头。

• 先验证必需参数 发出请求前，确保所有必需参数均已提供并符合架构要求。

• 遵循文档规定的响应结构 CoinAnk 成功响应中的 "code": "1" 是字符串，不是数字。

• 清楚地处理失败 如果请求或付款流程失败，请用用户易懂的语言说明问题，并保留技术原因以便排查。

API 密钥模式

拥有 CoinAnk 会员资格的用户可以配置直接访问：

export COINANK_API_KEY="your_api_key"

只要有有效的 API 密钥，就使用直接模式，除非用户明确要求改用 Agent Payments Protocol 或 x402 按次付费。

时间戳规则

endTime 必须是当前毫秒级时间戳

# Correct
NOW=$(python3 -c "import time; print(int(time.time()*1000))")

# Wrong on macOS: %3N is not supported
NOW=$(date +%s%3N)

如果端点要求提供 endTime，则使用当前毫秒级时间戳，除非用户明确指定了其他有效时间范围。

参数规则

不要发送不受支持的参数

某些端点不接受 endTime 或 size。例如，清算热力图端点（如 getLiqHeatMap）在包含不受支持的参数时可能会返回空数据。请严格遵循所选架构。

聚合端点必须提供 exchanges

对于聚合市场订单端点，如 getAggCvd、getAggBuySellCount、getAggBuySellValue 和 getAggBuySellVolume，必须提供 exchanges 参数。使用 exchanges= 可聚合所有交易所的数据。

interval 的取值因端点而异

不同 API 系列支持的 interval 取值各不相同。请务必确认所选架构的参数说明中列出的允许值。

端点类型	支持的 interval 取值
K 线 / 市场订单统计 / 多空比 / 未平仓量	1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d
清算热力图（getLiqHeatMap）	12h, 1d, 3d, 1w, 2w, 1M, 3M, 6M, 1Y
RSI 筛选器	1H, 4H, 1D
资金费率热力图	1D, 1W, 1M, 6M

响应处理

CoinAnk 的成功响应使用 "code": "1"。某些端点会在 data 中返回嵌套的有效负载，例如：

{"success": true, "code": "1", "data": {"success": true, "code": "1", "data": [...]}}

检查实际响应结构，并在必要时解包嵌套的 data 字段。

关于 Agent Payments Protocol / x402 可用性的说明

CoinAnk 支持通过 Agent Payments Protocol 或 x402 按次付费访问。实际使用时，该技能仍必须依据服务器对每个请求的真实 HTTP 响应。如果请求未返回 HTTP 402 挑战，该技能不得伪造付款流程。

关于 OpenAPI 示例的说明

references/*.json 中展示的值，尤其是 example 字段中的时间戳，仅为历史示例。构建请求时请将其替换为实时值。

错误处理

错误	原因	解决方法
HTTP 401	缺少、无效或被拒绝的 apikey，或网关／上游服务拒绝了支付数据	检查预期使用的是 API 密钥模式还是按次付费模式。不要使用伪造的凭据重试。如果使用按次付费模式，请求新的挑战，并使用生成的支付数据重放同一请求。
HTTP 402 Payment Required	CoinAnk 要求通过 Agent Payments Protocol / x402 为此请求付款	将支付处理委托给 okx-agent-payments-protocol。对于非零金额，请先向用户确认；对于零金额挑战，请严格按返回内容处理；并在提供支付证明或完成 charge 后重放原始请求。
缺少或不受支持的端点参数	所选 CoinAnk 端点所需的查询参数缺失、已过期或不被接受	查阅相关的 OpenAPI 参考文件，向用户询问缺失的值，并遵循时间戳和交易对格式规则。
支付技能不可用	未安装或无法访问所需的 OKX 支付辅助工具	说明按次付费模式需要 okx-agent-payments-protocol；请用户安装或启用它，或在可用时使用 API 密钥模式。
速率限制、超时或上游服务不可用	CoinAnk 或 CDN／缓存层暂时拒绝了请求或处理失败	清楚报告失败情况；未经用户确认，不要重复提交可能收费的请求；仅在安全时重试。

安全提示

• 此插件仅用于获取市场数据和协调支付；不会自行执行交易或转移资产。
• 切勿请求、打印、持久化或泄露私钥、助记词、API 密钥、支付证明、授权标头或钱包会话凭据。
• 仅从用户配置的环境或密钥存储中读取 COINANK_API_KEY，并且只将其作为 CoinAnk 的 apikey 标头发送。
• 将 Agent Payments Protocol / x402 证明生成、OKX 钱包签名和 charge 处理委托给 okx-agent-payments-protocol；不要绕过其确认流程。
• 执行前，务必向用户确认每笔非零金额的支付。切勿在未确认的情况下扣款。
• 将零金额支付挑战视为有效，但切勿将零金额强制转换为非零的备用金额。