概述
OpenSea Tool SDK 用于在链上构建、注册和门控 AI 可调用工具端点,底层采用 OpenSea Tool Registry(ERC-8257),部署在 Base 等受支持链上。SDK 同时面向工具提供方和工具调用方。
主要用途
- 为 Vercel、Cloudflare 或 Express 搭建 AI 可调用的工具端点,使用 HTTPS、JSON Schema 和 .well-known 清单。
- 在 Base 的 ToolRegistry 合约上链注册工具,使其他智能体可以发现它。
- 通过 x402 按次付费(USDC)或谓词进行访问门控,谓词包括 ERC-721/ERC-1155 持有、订阅、特征门控、ERC-20 余额及组合条件。
- 调用受门控或付费的工具,支持 402 支付、谓词门控认证,或两者结合。
- 通过 OpenSea REST API 搜索和发现已注册工具。
核心概念
- Tool:单个 REST API 端点,接口由 JSON Schema 描述,通过 /.well-known/ai-tool/<slug>.json 发现。每个工具只执行一项聚焦操作。
- Manifest:经 JCS 规范化后的 JSON,描述工具名称、端点、输入、输出、定价与访问策略。
- ToolRegistry:Base 链上合约,记录工具的清单哈希和可选访问谓词。
- Access Predicate:IAccessPredicate 合约,决定谁可以调用工具。
- x402:基于 HTTP 402 的按次付费协议,调用方签署 USDC TransferWithAuthorization,服务端执行后结算。
- EIP-3009 auth:使用零值 USDC TransferWithAuthorization 签名对调用方进行认证,用于谓词门控工具。
- Facilitator:验证并结算 x402 支付的第三方服务(PayAI 或 Coinbase CDP)。
使用方式
创建工具
- 脚手架项目:
npx @opensea/tool-sdk init --runtime vercel # 或 cloudflare、express
生成 src/manifest.ts、src/handler.ts、api/index.ts、public/llms.txt 及 api/well-known/[slug].ts 等文件。
-
使用
defineManifest定义清单,包含 name、description、endpoint、creatorAddress、inputs、outputs,可选 pricing 与 access。 -
使用
createToolHandler创建处理器,传入 manifest、inputSchema、outputSchema、handler,可选 gates 与 usageReporting。 -
通过
toVercelHandler、toExpressHandler或 Cloudflare 的 fetch 导出接入框架。
链上注册
CLI 方式需设置 PRIVATE_KEY 与 RPC_URL,然后运行:
npx @opensea/tool-sdk register --metadata https://my-tool.example.com/.well-known/ai-tool/my-tool.json --network base
可加 --access-predicate 0xPREDICATE_ADDRESS 指定谓词,或用 --dry-run 试运行。CLI 会拉取并校验清单、核对 creatorAddress、计算 JCS keccak256 哈希,并调用 ToolRegistry.registerTool,返回 toolId。
SDK 方式使用 ToolRegistryClient 与 computeManifestHash,通过 registerTool 提交 metadataURI、manifest 与 accessPredicate。
门控
支持三类门控:x402 付费墙、谓词门控(NFT、订阅、特征、ERC-20 余额、组合)以及两者结合(先谓词后 x402)。
钱包
签名使用 @opensea/wallet-adapters,支持 Privy、Fireblocks、Turnkey、Bankr 或本地 PRIVATE_KEY,按顺序自动检测,也可用 --wallet-provider 指定。
响应码
200 成功;400 输入无效;401 支付签名无效或过期;402 需要支付或身份;403 访问被拒;405 方法不允许;500 工具内部错误;502 谓词或 facilitator 错误。
CLI 命令
包括 init、validate、hash、export、register、update-metadata、inspect、verify、deploy、auth、pay、smoke、dry-run-gate、dry-run-predicate-gate、set-collections、get-collections、set-collection-tokens、configure-subscription、configure-trait-gating、get-trait-config、configure-erc20-gate、get-erc20-config。
使用量上报
usageReporting 会在每次成功调用后向 POST /api/v2/tools/usage 上报经过验证的调用方:付费调用上报 x402 结算信息,谓词认证调用转发调用方的 EIP-3009 授权。工具服务端不会代替调用方签名。
重要约束
- 一个工具对应一个端点,清单 URL 应指向执行单一操作的 API 路由。
- 清单与端点的 origin(协议、主机、端口)必须完全一致,子域不算同源,注册时会强制校验。
- 哈希按原样计算,扩展字段必须使用反向 DNS 命名空间或以 x- 前缀。
已部署合约
在 Ethereum 主网、Base、Shape、Abstract、Monad、Robinhood Chain 上部署 v0.2 合约,使用相同的 CREATE2 地址,包括 ToolRegistry、ERC721OwnerPredicate、ERC1155OwnerPredicate、SubscriptionPredicate、TraitGatedPredicate、ERC20BalancePredicate。
工具发现(Beta)
通过 OpenSea REST API 与 OPENSEA_API_KEY 查询,提供 GET /api/v2/tools、/api/v2/tools/search、/api/v2/tools/{registry_chain}/{registry_addr}/{tool_id} 及其 activity 接口。也可使用 OpenSea CLI 的 tools 子命令。
适用边界
本 SDK 不用于查询 NFT/代币数据、买卖 NFT、兑换 ERC-20 代币或设置钱包签名提供方,这些场景应使用对应的 opensea-api、opensea-marketplace、opensea-swaps、opensea-wallet 技能。