opensea

OpenSea（NFT 市场数据 + Seaport 交易）

OpenSea 是主流的 NFT 市场。此技能可查询市场数据——挂单、报价、销售 / 事件、地板价、发行活动、特征——并通过官方 @opensea/cli 执行 Seaport 交易。若要查询市场场景之外的 NFT 元数据（名称、图片、特征、所有权），请改用 Alchemy 的 NFT API。若要进行纯跨链代币兑换（不涉及市场场景），请使用 lifi 生态技能。

主要工具	npx @opensea/cli@latest <command>（或 npm install -g @opensea/cli）
REST API 基础 URL	https://api.opensea.io/api/v2
身份验证	OPENSEA_API_KEY 请求头——通过 POST /api/v2/auth/keys 即时获取，或在开发者门户注册
可选 Privy	写入 / 履约流程需要 PRIVY_APP_ID / PRIVY_APP_SECRET / PRIVY_WALLET_ID
链	Ethereum、Base、Arbitrum、Optimism、Polygon 等

适用场景

满足以下任一条件时，请使用 opensea：

• 用户需要市场数据——挂单、报价、地板价、销售历史、系列统计数据
• 用户想通过 Seaport 买入 / 卖出 NFT（履行挂单或接受报价）
• 用户想在 OpenSea 上搜索（系列 / NFT / 代币 / 账户）
• 用户想监控事件——系列或 NFT 的销售、转移、铸造、挂单、报价
• 用户想探索发行活动，或为 SeaDrop 合约构建铸造交易
• 用户需要 OpenSea 筛选范围内的代币发现（热门、趋势、按组）

不适用场景（转交）

需求	改用
市场场景之外的 NFT 元数据（名称、图片、特征、所有权查询）	alchemy-api（NFT API）——覆盖范围更广，速率限制更少
纯跨链代币兑换（不涉及 NFT 市场）	lifi（生态技能）——桥接 / DEX 聚合覆盖范围更广
用于估值的代币现货价格	alchemy-api（Prices API）
代币元数据、搜索、按链列出（通用）	alchemy-api（Token API）
当前钱包余额（代币 + 原生资产）	alchemy-api（Portfolio / Token API）
交易历史（转入 / 转出）	alchemy-api（Transfers API）
实时区块链读取（区块编号、Gas、eth_call）	alchemy-cli（实时查询）或 alchemy-api（JSON-RPC）
执行前模拟	alchemy-api（Simulation API）
账户抽象（打包器、Gas 管理器）	alchemy-api
智能钱包 / 嵌入式钱包流程	alchemy-api（Wallets / Account Kit）

范围约定

此技能涵盖（scope_in）：

• 市场数据： opensea listings best、opensea listings best-for-nft、opensea offers best-for-nft、opensea offers all、opensea collections stats、opensea collections trending、opensea collections top、opensea collections traits
• Seaport 交易： 用于买入（opensea-fulfill-listing.sh）和卖出（opensea-fulfill-offer.sh）的履约数据；使用 Seaport 订单结构，通过 opensea-post.sh 创建挂单 / 报价
• 事件 / 监控： opensea events list、events by-collection、events by-nft、events by-account — sale / transfer / mint / listing / offer / trait_offer / collection_offer
• Drops + 铸造： opensea drops list、opensea drops get、opensea drops mint
• 搜索： 使用 opensea search 搜索藏品 / NFT / 代币 / 账户
• 账户实用工具： opensea accounts resolve（ENS / 用户名 / 地址）

此技能不涵盖（scope_out）：

• 市场场景之外的通用 NFT 元数据读取（名称、图片、特征、所有权、合约元数据）→ 转交给：alchemy-api（NFT API）。OpenSea 的 NFT 数据偏向市场用途且有速率限制；对于纯元数据需求，Alchemy 的 NFT API 覆盖范围更广、成本更低。
• 纯跨链代币兑换（不涉及 NFT 市场场景）→ 转交给：lifi（生态技能）。OpenSea 的兑换聚合器可用，但 lifi 支持更多桥和链。
• 用于估值 / 显示的代币现货价格 → 转交给：alchemy-api（Prices API）
• 通用代币元数据、搜索、列表 → 转交给：alchemy-api（Token API）
• 钱包余额（代币 + 原生代币）→ 转交给：alchemy-api（Portfolio / Token API）
• 交易转账历史 → 转交给：alchemy-api（Transfers API）
• 实时 RPC 读取 → 转交给：alchemy-cli 或 alchemy-api（JSON-RPC）
• 执行前模拟 → 转交给：alchemy-api（Simulation API）
• 账户抽象 → 转交给：alchemy-api（Wallets / Bundler / Gas Manager）
• 嵌入式 / 智能钱包引导流程 → 转交给：alchemy-api（Account Kit）
• 签名交易提交 → 用户钱包（或在为 OpenSea 写入流程配置 Privy 时使用 Privy）

设置

需要 API 密钥。可通过 auth 端点即时获取（无需注册），也可在开发者门户注册以获得更高限额：

# Instant key (no signup needed)
export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')

# Or set an existing key
# export OPENSEA_API_KEY="..."

全局安装 CLI（可选 — 无需安装即可使用 npx @opensea/cli）：

npm install -g @opensea/cli

用于通过 Privy 签名的写入 / 履约流程：

export PRIVY_APP_ID="..."
export PRIVY_APP_SECRET="..."
export PRIVY_WALLET_ID="..."

安全： 切勿在客户端代码中暴露 OPENSEA_API_KEY 或 Privy 凭据。仅限服务端使用。

端点参考 → references/marketplace.md

市场查询（最常用）

任务	CLI
获取某个藏品的最佳挂单	opensea listings best <slug> [--limit <n>]
获取某个特定 NFT 的最佳挂单	opensea listings best-for-nft <slug> <token_id>
获取某个 NFT 的最佳报价	opensea offers best-for-nft <slug> <token_id>
获取某个藏品的所有挂单	opensea listings all <slug> [--limit <n>]
获取某个藏品的所有报价	opensea offers all <slug> [--limit <n>]
特征报价	opensea offers traits <slug> --type <type> --value <value>
藏品统计数据（地板价、交易量）	opensea collections stats <slug>
趋势藏品	opensea collections trending [--timeframe <tf>] [--chains <chains>]
按排序方式获取热门藏品	opensea collections top [--sort-by <field>] [--chains <chains>]
藏品特征	opensea collections traits <slug>

Seaport 交易执行

任务	脚本
获取买入 NFT 的履约数据	opensea-fulfill-listing.sh <chain> <order_hash> <buyer>
获取卖出 NFT（接受报价）的履约数据	opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>
向 OpenSea API 发送通用 POST 请求	opensea-post.sh <path> <json_body>

事件 / 监控

任务	CLI
最近的事件（可按类型筛选）	opensea events list [--event-type <type>]
某个系列的事件	opensea events by-collection <slug> [--event-type <type>]
某个 NFT 的事件	opensea events by-nft <chain> <contract> <token_id>
某个账户的事件	opensea events by-account <address>

事件类型：sale、transfer、mint、listing、offer、trait_offer、collection_offer。

实时流式传输事件：opensea-stream-collection.sh <slug>（需要 websocat）。

Drops + 铸造

任务	CLI
列出 Drops（精选 / 即将推出 / 最近）	opensea drops list [--type <type>]
Drop 详情 + 阶段	opensea drops get <slug>
构建铸造交易	opensea drops mint <slug> --minter <address> [--quantity <n>]

搜索

任务	CLI
搜索系列	opensea search <query> --types collection
搜索 NFT	opensea search <query> --types nft
搜索代币	opensea search <query> --types token
搜索账户	opensea search <query> --types account
多类型搜索	opensea search <query> --types collection,nft,token

快速示例

获取 Bored Apes 的地板价 + 24 小时交易量

opensea collections stats boredapeyachtclub

查找某个系列中价格最低的挂单

opensea listings best boredapeyachtclub --limit 1

购买 NFT（完成挂单交易）

# 1. Get the best listing for a specific NFT
opensea listings best-for-nft boredapeyachtclub 1234

# 2. Get fulfillment data — order_hash from above response
./scripts/opensea-fulfill-listing.sh ethereum 0xORDER_HASH 0xYOUR_WALLET

# 3. Sign + submit the returned tx data via your wallet

实时追踪某个系列的销售

./scripts/opensea-stream-collection.sh boredapeyachtclub
# Filters to sale events; pipe through jq to format

跨类型搜索

opensea search "cool cats" --types collection,nft --chains ethereum,base

常见注意事项

• 必须使用 API 密钥——即使是“即时”层级也需要密钥。直接调用 REST API 时，如果没有 X-API-KEY，将返回 401。
• OpenSea 的 NFT 数据与 Alchemy 的 NFT API 存在重叠，都可用于读取元数据。读取通用 NFT 元数据（名称、图片、特征、多个钱包的所有权）时，优先使用 Alchemy——OpenSea 的速率限制更严格，而且会加入你可能不需要的市场信息。仅当确实需要市场背景信息（挂单、报价、销售历史、Drops）时，才使用 OpenSea。
• OpenSea API 中提供代币兑换聚合器（opensea swaps quote），但对于不涉及市场背景的纯兑换流程，lifi 聚合的桥接和 DEX 更多，是更合适的默认选择。如果用户正在进行涉及代币兑换的 NFT 购买流程，则使用 OpenSea swaps。
• Privy 是可选的，但端到端写入流程需要它。该技能会返回完成交易所需的 calldata；如何签名由应用决定（用户钱包、Privy 或任何其他签名器）。
• 完成交易需要使用 listings best-for-nft / offers best-for-nft 返回的订单哈希。在 API 调用之间不要丢失这些哈希。
• 事件流式传输需要 websocat；如果未安装，可使用相同的筛选条件轮询 events by-collection。
• Slug 与地址：系列通过 slug（例如 boredapeyachtclub）指定；NFT 通过 (chain, contract, tokenId) 指定。不要混用。

路由回 Alchemy

如果会话期间用户的需求转向了本技能未涵盖的领域：

• 读取 NFT 元数据（名称、图片、特征、所有权）——使用 alchemy-api（NFT API）。OpenSea 的 NFT API 更偏向市场场景，且速率限制更严格；Alchemy 的覆盖范围更广、速度更快。
• 代币价格、余额、转账历史、通用代币元数据——alchemy-api
• 实时 RPC、Gas、模拟、AA、Account Kit——alchemy-cli（实时操作）、alchemy-api（应用代码）或 agentic-gateway（无需 API 密钥）
• 纯跨链代币兑换——lifi（生态系统技能）；覆盖 60 多条链上的 27 个桥接服务 + 31 个 DEX

---

维护说明： OpenSea 负责维护 @opensea/cli 和底层 API；本技能由 Alchemy 与 OpenSea 联合维护。请在 alchemyplatform/skills 中提交 issue，并在标题中添加 [ecosystem/opensea]。