DECK-0 Agents API

概述

DECK-0 是一个数字收藏品平台，用户可在其中收集按相册组织的交易卡牌。本技能使 Agent 能够执行以下操作：

• 浏览 商店并查看收藏详情
• 购买 卡包（通过智能合约交易）
• 开启 卡包以揭晓其中卡牌
• 追踪 收藏进度及排行榜排名
• 发布 —— 申请创建您自己的卡牌收藏

基础 URL：https://app.deck-0.com
OpenAPI 规范：GET /api/agents/v1/openapi（无需认证）

配置

钱包来源优先级

在签署 API 请求或发送交易时，请按以下顺序解析钱包：

1. 运行时提供的现有 Agent 钱包
2. 运行时提供的现有 Base 钱包
3. DECK0_PRIVATE_KEY 回退方案（仅当上述两种钱包均不存在时使用）

第 3 步的回退配置方式如下：

export DECK0_PRIVATE_KEY="0x..."

可选：回退链 ID 覆盖（仅用于 API 认证签名验证；合约操作将使用收藏/价格响应中返回的链 ID 及您所选的 RPC）：

export DECK0_CHAIN_ID=8453

请使用经审核的方式安装 Foundry（例如通过 Homebrew），然后验证 cast 是否可用：

brew install foundry
cast --version

此外还需使用：curl、jq、shasum（macOS/Linux 系统默认已安装）。

注意： 声明的依赖项（cast、curl、jq、shasum、DECK0_PRIVATE_KEY）仅在启用 回退 签名机制或执行购买/开启流程时必需。若仅进行浏览操作且使用运行时提供的钱包，则可能无需 DECK0_PRIVATE_KEY 或 cast。

钱包需持有原生代币（Apechain 上为 APE，Base 上为 ETH）方可购买卡包。

安全须知

• 应始终优先使用运行时提供的钱包。
• DECK0_PRIVATE_KEY 敏感性极高，仅可在用户明确授权且任务确实需要签名或交易时作为回退手段使用。
• 切勿打印、记录或回显私钥值。

快速参考

完整请求/响应结构定义请参阅 endpoints.md。

认证

所有端点（/openapi 除外）均需通过自定义请求头提供 EIP-191 钱包签名：

待签名的规范载荷格式如下：

deck0-agent-auth-v1
method:{METHOD}
path:{PATH}
query:{SORTED_QUERY}
body_sha256:{SHA256_HEX}
timestamp:{TIMESTAMP}
nonce:{NONCE}
chain_id:{CHAIN_ID}
wallet:{WALLET}

完整的签名流程（含代码示例）详见 auth.md。

智能合约

购买与开启卡包均为链上操作：

1. 购买卡包：调用 GET /api/agents/v1/collections/{address}/price 获取已签名价格，再在对应相册合约上调用 mintPacks() 方法，并传入该签名与支付金额。
2. 开启卡包：在相册合约上调用 openPacks(packIds) 方法以揭晓卡牌，随后每隔 5 秒轮询 GET /api/agents/v1/me/pack-opening/{txHash}?chainId=...，直至获得包含卡牌详情与徽章的开启回顾结果。

支付金额计算公式：value = (packPrice * priceInNative * quantity) / 100

ABI 定义、支付金额计算逻辑及代码示例详见 smart-contracts.md。

支持的网络

响应格式

所有响应均遵循统一信封结构：

// 成功响应
{ "success": true, "data": { ... }, "share": { "url": "...", "imageUrl": "..." } }

// 错误响应
{ "success": false, "error": { "code": "AGENT_...", "message": "...", "details": { ... } } }

全部错误码及排障指南详见 errors.md。

分享链接

多数响应中均包含指向 DECK-0 网页应用的链接。请务必向用户展示这些链接，以便其在浏览器中查看、分享或进一步探索。

• share.url — 出现在大多数响应中，指向对应页面（如收藏页、排行榜页、商店页、卡包开启回顾页等）。请将其作为可分享链接呈现给用户。
• share.imageUrl — 若存在，为图片预览链接（例如收藏封面图），可用于富媒体嵌入或缩略图预览。
• data.cards[].url — 在卡包开启回顾响应中，每张卡牌均附带其详情页直链。请向用户展示这些链接，使其可查看或分享单张卡牌。

速率限制

• 按钱包：每分钟最多 60 次请求
• 按 IP：每分钟最多 120 次请求

429 响应中会包含速率限制相关头部字段（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、Retry-After）。

意图映射

当用户表达如下语句时：

• “显示可用的卡牌收藏” → 浏览商店相册
• “介绍一下收藏 0x...” → 获取收藏详情
• “从收藏 0x... 购买 3 个卡包” → 获取已签名价格，调用 mintPacks
• “开启我的卡包” → 在合约上调用 openPacks，随后轮询卡包开启回顾
• “我获得了哪些卡牌？” / “展示我的卡包开启结果” → 获取卡包开启回顾
• “我的收藏进度如何？” → 获取我的相册列表
• “展示我的卡包” / “我有哪些卡包？” → 列出我的卡包
• “展示我的卡牌” / “我有哪些卡牌？” → 列出我的卡牌
• “展示排行榜” → 获取收藏排行榜
• “分享我的卡包开启结果” / “给我看这张卡牌的链接” → 使用响应中的 share.url 或 cards[].url
• “我想创建自己的卡牌收藏” → 提交发布者申请

配套文档

• auth.md — 完整认证流程、签名代码实现、载荷构造说明
• endpoints.md — 完整 API 参考文档，含全部请求/响应结构定义
• smart-contracts.md — 链上操作说明：卡包铸造、卡包开启、ABI 定义、代码示例
• examples.md — 端到端工作流示例（含请求/响应配对）
• errors.md — 错误码列表、速率限制策略、故障排查指南