Communitygithub.com

ProjectOpenSea/opensea-skill

通过官方CLI、SDK、MCP服务器或Shell脚本查询OpenSea市场数据。获取地板价、集合统计、NFT详情、代币数据、热门集合、空投、事件、搜索、收藏、个人资料和集合设置，以及其他钱包级操作。交易请使用opensea-marketplace，代币兑换请使用opensea-swaps。

opensea-skill 是什么？

该技能（opensea-api）允许开发者通过OpenSea官方CLI、SDK、MCP服务器或Shell脚本读取NFT和代币数据，并浏览空投与活动流。它支持在Ethereum、Base、Arbitrum、Optimism、Polygon等多条链上进行集合详情、统计、趋势、NFT所有权、代币详情、搜索以及实时WebSocket事件监控等只读操作。技能自动处理API密钥解析（从环境变量、磁盘缓存或即时获取），并强调缓存和复用密钥以避免速率限制失败。对于需要钱包签名的交易（如买卖NFT或代币兑换），该技能会自动将任务转交给专用的opensea-marketplace或opensea-swaps技能。它适用于任何通过CLI、SDK或MCP集成OpenSea数据的AI代理或自动化脚本。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/ProjectOpenSea/opensea-skill/tree/main/opensea-api
查看原文→浏览所有技能

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

文档

OpenSea API

查询NFT和代币数据，浏览空投，流式事件，并跨Ethereum、Base、Arbitrum、Optimism、Polygon等链进行搜索。

何时使用此技能（scope_in）

使用 opensea-api 用于：

  • 集合详情、统计、特征、趋势和热门集合
  • NFT详情、所有权、元数据刷新
  • 代币详情、趋势代币、热门代币、代币组
  • 跨集合、NFT、代币和账户的搜索
  • 搜索和发现已注册的AI代理工具（ERC-8257）
  • 读取市场列表、出价和订单（不执行）
  • 事件和活动监控（包括实时WebSocket流）
  • 空投和铸造资格
  • 账户查找和ENS解析
  • 经过身份验证的个人资料、集合设置、关注列表、空投、订单取消和钱包链接操作（详见 references/authentication.md）
  • 无头SIWE、作用域PAT创建、短期JWT交换以及钱包认证的REST或MCP

何时不使用此技能（scope_out，交接）

需求改用
买卖NFT（履行列表或出价）opensea-marketplace
创建新的列表或出价opensea-marketplace
跨链NFT购买opensea-marketplace
交换ERC20代币opensea-swaps
设置钱包签名提供者opensea-wallet
构建/注册/门控AI代理工具opensea-tool-sdk

快速入门

# 解析API密钥：复用你的环境变量/缓存的即时密钥，或获取一个新的即时密钥（无需注册）并保存到磁盘以供复用。请参阅下面的“API密钥解析”——始终保存并复用获取的密钥。
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

# 全局安装CLI（或使用npx）
npm install -g @opensea/cli

# 获取集合信息
opensea collections get boredapeyachtclub

# 获取地板价和成交量统计
opensea collections stats boredapeyachtclub

# 获取NFT详情
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234

# 跨OpenSea搜索
opensea search "cool cats"

# 获取趋势代币
opensea tokens trending --limit 5

API密钥解析（在首次请求前阅读）

每个OpenSea请求都需要 OPENSEA_API_KEY。如果你尚未拥有密钥，你可以获取一个即时免费层级密钥，无需注册。唯一重要的规则是：一旦你获取了即时密钥，请将其保存到磁盘并复用。 不要在每次请求时重新获取。第二次获取可能会失败，导致你无密钥可用。之前的成功请求不会为你持久化密钥。

流程（每次按顺序执行以下步骤）

  1. 首先检查环境变量。 如果 OPENSEA_API_KEY 已设置且非空，则直接使用。这是提供给自有密钥用户的路径——切勿覆盖或重新获取。
  2. 接下来检查磁盘。 如果没有环境变量，在 ~/.opensea/api_key 中查找缓存密钥（用 $OPENSEA_CONFIG_DIR 覆盖目录）。如果文件存在且非空，将其加载到 OPENSEA_API_KEY 中并使用。
  3. 仅当缺失时获取。 如果既没有环境变量也没有缓存密钥，从 POST /api/v2/auth/keys 请求一个新的即时密钥。
  4. 获取后立即保存。 将获取的密钥写入 ~/.opensea/api_key（模式 600）在 进行API调用之前，以便下一步——以及所有未来的请求——复用该密钥而非重新获取。

scripts/auth/opensea-resolve-key.sh 辅助脚本为你执行所有四个步骤并打印解析后的密钥。优先于裸 curl ... /auth/keys 调用，因为后者会获取但不保存，这正是导致密钥丢失的原因：

# 环境变量？->使用它。缓存密钥？->复用。否则获取+保存到磁盘。
export OPENSEA_API_KEY=$(scripts/auth/opensea-resolve-key.sh)

opensea collections get boredapeyachtclub

如果你无法使用辅助脚本，请显式复制相同的顺序逻辑：

KEY_FILE="${OPENSEA_CONFIG_DIR:-$HOME/.opensea}/api_key"
if [ -n "${OPENSEA_API_KEY:-}" ]; then
  :                                              # 1. 环境变量优先
elif [ -s "$KEY_FILE" ]; then
  export OPENSEA_API_KEY=$(cat "$KEY_FILE")      # 2. 复用缓存密钥
else
  api_key=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')  # 3. 获取
  mkdir -p "$(dirname "$KEY_FILE")"
  (umask 077; printf '%s\n' "$api_key" > "$KEY_FILE")  # 4. 在使用前保存
  export OPENSEA_API_KEY="${api_key}"
fi

边界情况

  • 密钥已存在（环境变量或缓存文件）： 复用；不要获取新密钥。重新获取会浪费速率限制并可能失败。
  • 密钥无效或过期（即时密钥在7天后过期；请求返回HTTP 401/403）：缓存密钥已过时。使用 scripts/auth/opensea-resolve-key.sh --force 重新获取并覆盖缓存（或删除 ~/.opensea/api_key 并重新运行流程）。--force 从不覆盖通过 OPENSEA_API_KEY 环境变量提供的密钥。
  • 获取失败（HTTP 429 速率限制，或网络错误）：不要 在紧密循环中重试。如果你有缓存密钥，继续使用它。否则稍后重试，或在 设置 → 开发者 创建完整密钥。对于比即时免费层级更高的速率限制，请使用完整密钥。

你也可以使用 opensea auth request-key 或 scripts/auth/opensea-auth-request-key.sh 获取原始密钥（JSON响应，无持久化）——但如果你使用这些，你必须按照上述步骤4自行保存密钥。

任务指南

推荐： 使用 opensea CLI（@opensea/cli）作为主要工具。通过 npm install -g @opensea/cli 安装，或使用 npx @opensea/cli。scripts/ 中的Shell脚本仍可作为备选方案。

读取NFT数据

任务CLI命令备选方案
获取集合详情opensea collections get <slug>collections/opensea-collection.sh <slug>
获取集合统计opensea collections stats <slug>collections/opensea-collection-stats.sh <slug>
获取趋势集合opensea collections trending [--timeframe <tf>] [--chains <chains>]collections/opensea-collections-trending.sh [timeframe] [limit] [chains] [category]
获取热门集合opensea collections top [--sort-by <field>] [--chains <chains>]collections/opensea-collections-top.sh [sort_by] [limit] [chains] [category]
列出集合中的NFTopensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]collections/opensea-collection-nfts.sh <slug> [limit] [next]
获取单个NFTopensea nfts get <chain> <contract> <token_id>nfts/opensea-nft.sh <chain> <contract> <token_id>
按钱包列出NFTopensea nfts list-by-account <chain> <address> [--limit <n>]accounts/opensea-account-nfts.sh <chain> <address> [limit]
按合约列出NFTopensea nfts list-by-contract <chain> <contract> [--limit <n>]
获取集合特征opensea collections traits <slug>
获取合约详情opensea nfts contract <chain> <address>
刷新NFT元数据opensea nfts refresh <chain> <contract> <token_id>

读取代币数据

任务CLI命令备选方案
获取趋势代币opensea tokens trending [--chains <chains>] [--limit <n>]get_trending_tokens (MCP)
按成交量获取热门代币opensea tokens top [--chains <chains>] [--limit <n>]get_top_tokens (MCP)
获取代币详情opensea tokens get <chain> <address>get_tokens (MCP)
获取代币交换活动opensea tokens activity <chain> <address> [--limit <n>] [--next <cursor>]tokens/opensea-token-activity.sh
获取账户代币活动opensea tokens account-activity <address> [--chains <chains>] [--tokens <tokens>] [--type <types>] [--limit <n>] [--next <cursor>]
列出代币组opensea token-groups list [--limit <n>] [--next <cursor>]tokens/opensea-token-groups.sh [limit] [cursor]
按slug获取代币组opensea token-groups get <slug>tokens/opensea-token-group.sh <slug>
搜索代币opensea search <query> --types tokensearch_tokens (MCP)
检查代币余额get_token_balances (MCP)

钱包认证的REST和MCP

在充当钱包之前，请阅读 钱包认证 参考。它包含CLI和SDK的愉快路径、REST和MCP头部、凭证生命周期和恢复规则。

市场查询（只读）

任务CLI命令备选方案
获取集合最佳列表opensea listings best <slug> [--limit <n>] [--traits <json>]listings/opensea-best-listing.sh <slug> <token_id>
获取特定NFT的最佳列表opensea listings best-for-nft <slug> <token_id>listings/opensea-best-listing.sh <slug> <token_id>
获取NFT的最佳出价opensea offers best-for-nft <slug> <token_id>offers/opensea-best-offer.sh <slug> <token_id>
列出所有集合列表opensea listings all <slug> [--limit <n>]listings/opensea-listings-collection.sh <slug> [limit]
列出所有集合出价opensea offers all <slug> [--limit <n>]offers/opensea-offers-collection.sh <slug> [limit]
获取集合出价opensea offers collection <slug> [--limit <n>]offers/opensea-offers-collection.sh <slug> [limit]
获取特征出价opensea offers traits <slug> --type <type> --value <value>
按哈希获取订单orders/opensea-order.sh <chain> <order_hash>

服务器端特征过滤

三个集合范围端点接受 traits 查询参数用于服务器端过滤：

端点CLISDK
列出集合中的NFTopensea nfts list-by-collection <slug> --traits <json>client.nfts.listByCollection(slug, { traits })
集合最佳列表opensea listings best <slug> --traits <json>client.listings.best(slug, { traits })
集合事件opensea events by-collection <slug> --traits <json>client.events.byCollection(slug, { traits })

--traits 接受一个JSON编码的 { "traitType": string, "value": string } 对象数组。多个条目以AND方式组合：

opensea nfts list-by-collection doodles-official \
  --traits '[{"traitType":"Background","value":"Red"}]'

始终优先使用服务器端过滤而不是客户端：对未过滤的集合进行分页会浪费速率限制预算。

搜索

任务CLI命令
搜索集合opensea search <query> --types collection
搜索NFTopensea search <query> --types nft
搜索代币opensea search <query> --types token
搜索账户opensea search <query> --types account
搜索多种类型opensea search <query> --types collection,nft,token
在特定链上搜索opensea search <query> --chains base,ethereum

事件与监控

任务CLI命令备选方案
列出最近事件opensea events list [--event-type <type>] [--limit <n>]
获取集合事件opensea events by-collection <slug> [--event-type <type>] [--traits <json>]events/opensea-events-collection.sh <slug> [event_type] [limit]
获取特定NFT的事件opensea events by-nft <chain> <contract> <token_id>
获取账户事件opensea events by-account <address>
流式实时事件stream/opensea-stream-collection.sh <slug> (需要 websocat)

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

空投与铸造

任务CLI命令备选方案
列出空投（精选/即将到来/最近）opensea drops list [--type <type>] [--chains <chains>]drops/opensea-drops.sh [type] [limit] [chains]
获取空投详情和阶段opensea drops get <slug>drops/opensea-drop.sh <slug>
构建铸造交易opensea drops mint <slug> --minter <address> [--quantity <n>]drops/opensea-drop-mint.sh <slug> <minter> [quantity]
构建跨链铸造交易opensea drops cross-chain-mint <slug> --payer <address> --minter <address> --payment-chain <chain> --payment-token <address> [--quantity <n>]drops/opensea-drop-cross-chain-mint.sh <slug> <payer> <minter> <payment_chain> <payment_token> [quantity]
构建或发送发布交易（拥有者钱包，write:drops）opensea drops publish <slug> [--send] [--wallet-provider <provider>]
构建或发送取消发布交易opensea drops unpublish <slug> [--send] [--wallet-provider <provider>]
上传空投媒体和元数据到IPFSopensea drops upload-metadata-ipfs <slug> [--wait] [--interval <s>] [--wait-timeout <s>]
检查IPFS上传进度opensea drops metadata-ipfs-status <slug> <workflow-execution-id>
请求元数据清单CSV上传opensea drops create-manifest-upload <slug>
上传文件到上传上下文`opensea drops upload-file --context <path-> --file [--index ]`
部署新的SeaDrop合约deploy_seadrop_contract (MCP)
检查部署状态get_deploy_receipt (MCP)

publish --send 使用配置的EVM钱包签名，并拒绝不是交易 from（合约的链上拥有者）的钱包，因为来自任何其他地址的交易都会回滚。upload-file 接受单个上传上下文；对于 create-item-media-upload 返回的数组，传递 --index <n> 或用 jq '.[0]' 管道输出一个元素。upload-metadata-ipfs --wait 在上传失败、未找到或超出 --wait-timeout 时退出1。

对于跨链铸造，按顺序提交每个返回的交易。完全按原样保存返回的 receipt_request 对象，然后轮询它直到状态变为 SUCCESS。确保包含所有必需的链上批准（例如，如果付款代币需要授权）。

账户操作

任务CLI命令备选方案
获取账户详情opensea account get <address>accounts/opensea-account.sh <address>
通过ENS解析账户opensea account resolve <ens_name>
获取账户NFTopensea nfts list-by-account <chain> <address> [--limit <n>]accounts/opensea-account-nfts.sh <chain> <address> [limit]
获取账户收藏opensea account favorites <address>
关注集合opensea account watch-collection <slug>
取消关注集合opensea account unwatch-collection <slug>
取消NFT列表listings/cancel-listing.sh <chain> <order_hash>
取消NFT出价offers/cancel-offer.sh <chain> <order_hash>

开发工具与MCP

opensea CLI 也可作为MCP服务器使用。要通过MCP使用，请将以下内容添加到你的MCP配置中：

{
  "mcpServers": {
    "opensea": {
      "command": "npx",
      "args": ["-y", "@opensea/cli", "mcp"],
      "env": {
        "OPENSEA_API_KEY": "your-api-key"
      }
    }
  }
}

CLI内置的MCP服务器公开了本指南中的所有CLI命令作为工具。每个CLI命令映射到一个MCP工具，参数相同。例如，opensea collections get boredapeyachtclub 变为 MCP 调用 collections_get 或等效工具。

MCP工具按类别分组：

  • 集合操作： get_collection, get_collection_stats, get_trending_collections, 等。
  • NFT操作： get_nft, list_nfts_by_collection, list_nfts_by_account, refresh_nft_metadata, 等。
  • 代币操作： get_trending_tokens, get_top_tokens, get_tokens, search_tokens, get_token_balances, 等。
  • 搜索操作： search, search_collections, search_nfts, search_tokens, search_accounts
  • 事件操作： list_events, get_collection_events, stream_events (WebSocket)
  • 空投操作： 列出、获取、铸造和发布空投
  • 账户操作： 获取账户详情，关注/取消关注集合

相关资源

脚本索引

scripts/ 目录包含每个API端点的独立Shell脚本。这些脚本设计为可管道化和可组合。每个脚本都记录了自己的用法。主脚本：

scripts/auth/

  • opensea-resolve-key.sh — 解析API密钥（环境变量→缓存→立即获取+保存）
  • opensea-auth-request-key.sh — 请求新的即时密钥（无持久化）

scripts/collections/

  • opensea-collection.sh <slug> — 获取集合详情
  • opensea-collection-stats.sh <slug> — 获取集合统计
  • opensea-collections-trending.sh [timeframe] [limit] [chains] [category] — 趋势集合
  • opensea-collections-top.sh [sort_by] [limit] [chains] [category] — 热门集合
  • opensea-collection-nfts.sh <slug> [limit] [next] — 列出集合中的NFT

scripts/nfts/

  • opensea-nft.sh <chain> <contract> <token_id> — 获取NFT详情

scripts/accounts/

  • opensea-account.sh <address> — 获取账户详情
  • opensea-account-nfts.sh <chain> <address> [limit] — 按账户列出NFT

scripts/tokens/

  • opensea-token-activity.sh <chain> <address> [limit] [next] — 代币活动
  • opensea-token-groups.sh [limit] [cursor] — 列出代币组
  • opensea-token-group.sh <slug> — 按slug获取代币组

scripts/events/

  • opensea-events-collection.sh <slug> [event_type] [limit] — 集合事件

scripts/stream/

  • opensea-stream-collection.sh <slug> — 集合的实时事件流（需要 websocat）

scripts/drops/

  • opensea-drops.sh [type] [limit] [chains] — 列出空投
  • opensea-drop.sh <slug> — 获取空投详情
  • opensea-drop-mint.sh <slug> <minter> [quantity] — 构建铸造交易
  • opensea-drop-cross-chain-mint.sh <slug> <payer> <minter> <payment_chain> <payment_token> [quantity] — 构建跨链铸造交易

scripts/listings/

  • opensea-best-listing.sh <slug> <token_id> — 最佳列表
  • opensea-listings-collection.sh <slug> [limit] — 集合的列表
  • cancel-listing.sh <chain> <order_hash> — 取消列表

scripts/offers/

  • opensea-best-offer.sh <slug> <token_id> — 最佳出价
  • opensea-offers-collection.sh <slug> [limit] — 集合的出价
  • cancel-offer.sh <chain> <order_hash> — 取消出价

scripts/orders/

  • opensea-order.sh <chain> <order_hash> — 按哈希获取订单

MCP工具参考

所有MCP工具（当通过@opensea/cli mcp启动时可用）：

# 集合
- get_collection
- get_collection_stats
- get_trending_collections
- get_top_collections
- get_collection_traits

# NFT
- get_nft
- list_nfts_by_collection
- list_nfts_by_account
- list_nfts_by_contract
- get_contract
- refresh_nft_metadata

# 代币
- get_trending_tokens
- get_top_tokens
- get_tokens
- get_token_balances
- search_tokens
- get_token_activity
- get_account_token_activity
- list_token_groups
- get_token_group

# 搜索
- search

# 事件
- list_events
- get_collection_events
- get_nft_events
- get_account_events

# 空投
- list_drops
- get_drop
- build_mint_transaction
- build_cross_chain_mint_transaction
- publish_drop
- unpublish_drop
- upload_metadata_to_ipfs
- get_ipfs_upload_status
- create_manifest_upload
- upload_file
- deploy_seadrop_contract
- get_deploy_receipt

# 账户
- get_account
- resolve_ens
- get_account_favorites
- watch_collection
- unwatch_collection

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

ProjectOpenSea/opensea-skill

Buy and sell NFTs through OpenSea on EVM chains and Solana. Fulfill listings, accept or create offers, cancel orders, make cross-chain purchases, and sweep listings. Requires wallet signing; for read-only queries use opensea-api instead.

ProjectOpenSea/opensea-skill

Swap ERC20 tokens across supported chains via OpenSea's cross-chain DEX aggregator. Get quotes with optimal routing, check token balances, and execute swaps. For NFT trading use opensea-marketplace, for querying token data use opensea-api.

ProjectOpenSea/opensea-skill

Build, register, and gate AI-callable tool endpoints using the OpenSea Tool Registry (ERC-8257) on Base. Scaffold HTTPS tools with JSON Schema interfaces, register them onchain, gate access via NFT ownership, subscriptions, trait gating, or x402 pay-per-call (USDC), and call gated tools. For querying OpenSea marketplace data use opensea-api instead.

ProjectOpenSea/opensea-skill

Set up and configure wallet signing providers for OpenSea transactions. Supports Privy, Turnkey, Fireblocks, Bankr, and local private keys. Required for executing trades (opensea-marketplace) and token swaps (opensea-swaps).

相关技能

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community