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 が必要です。まだキーを持っていない場合、登録不要でインスタントの無料ティアキーを取得できます。唯一の重要なルールは：インスタントキーを取得したら、必ずディスクに保存して再利用すること。リクエストごとに再取得しないでください。2回目の取得は失敗し、キーがなくなる可能性があります。以前の成功したリクエストはキーを保持していません。

フロー（毎回この順序で手順を実行）

まず環境変数を確認。 OPENSEA_API_KEY がすでに設定され、空でない場合は、そのまま使用します。これは自身のキーを提供するユーザー向けのパスです — 絶対に上書きまたは再取得しないでください。
次にディスクを確認。 環境変数がない場合、~/.opensea/api_key にキャッシュされたキーを探します（ディレクトリは $OPENSEA_CONFIG_DIR で上書き可能）。ファイルが存在し空でない場合は、OPENSEA_API_KEY に読み込んで使用します。
不足している場合のみ取得。 環境変数もキャッシュキーもない場合、POST /api/v2/auth/keys から新しいインスタントキーをリクエストします。
取得後すぐに保存。 取得したキーを ~/.opensea/api_key（モード 600）に書き込み、API呼び出しを行う前に保存します。これにより、次の手順と将来のすべてのリクエストで再取得せずに再利用されます。

scripts/auth/opensea-resolve-key.sh ヘルパーは上記4つの手順をすべて実行し、解決されたキーを出力します。生の 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 レート制限、またはネットワークエラー）：タイトループでリトライしないでください。キャッシュキーがある場合はそのまま使用し続けてください。それ以外の場合は、後で再度試すか、Settings → Developer でフルキーを作成してください。インスタント無料ティアよりも高いレート制限が必要な場合は、フルキーを使用します。

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/ 内のシェルスクリプトも代替として利用可能です。

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]`
コレクション内のNFT一覧	`opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]`	`collections/opensea-collection-nfts.sh <slug> [limit] [next]`
単一NFTの取得	`opensea nfts get <chain> <contract> <token_id>`	`nfts/opensea-nft.sh <chain> <contract> <token_id>`
ウォレット別NFT一覧	`opensea nfts list-by-account <chain> <address> [--limit <n>]`	`accounts/opensea-account-nfts.sh <chain> <address> [limit]`
コントラクト別NFT一覧	`opensea 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]`
スラッグ別トークングループの取得	`opensea token-groups get <slug>`	`tokens/opensea-token-group.sh <slug>`
トークンの検索	`opensea search <query> --types token`	`search_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>`

サーバーサイド特性フィルタリング

3つのコレクションスコープのエンドポイントが、サーバーサイドフィルタリング用の traits クエリパラメータを受け入れます：

エンドポイント	CLI	SDK
コレクション内のNFT一覧	`opensea 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 は、{ "traitType": string, "value": string } オブジェクトのJSONエンコード配列を受け取ります。複数のエントリはAND結合されます：

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

常にサーバーサイドフィルタリングをクライアントサイドより優先してください：フィルタリングされていないセットをページングするとレート制限の予算を無駄にします。

検索

タスク	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`
特定チェーンでの検索	`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>]`
ドロップメディアとメタデータをIPFSにアップロード	`opensea 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]' で1つの要素をパイプしてください。upload-metadata-ipfs --wait は、アップロードが失敗した場合、見つからない場合、または --wait-timeout を超えた場合に終了コード1を返します。

クロスチェーンミントの場合、返されたすべてのトランザクションを順番に送信してください。返された receipt_request オブジェクトをそのまま保存し、ステータスが SUCCESS になるまでポーリングしてください。

アカウントとENS

タスク	CLIコマンド	代替
アカウント詳細の取得	`opensea accounts get <address>`	`accounts/opensea-account.sh <address>`
ENS名の解決	`opensea accounts resolve-ens <name>`
NFT保有量の取得	`opensea accounts nft-count <address>`
アカウントのお気に入り一覧	`opensea accounts favorites <address> [--limit <n>]`	`accounts/opensea-account-favorites.sh <address>`
アカウントのアクティビティ	`opensea accounts activity <address> [--limit <n>]`

認証済み操作（ウォレットが必要）

これらの操作には認証されたウォレット接続が必要です。認証リファレンスの手順に従って認証情報ルーチンを設定してください。以下の表のCLIコマンドは opensea バイナリの一部ですが、適切なウォレット署名なしでは動作しません。

プロフィール

タスク	CLIコマンド
自分のプロフィールの取得	`opensea accounts me`
プロフィールの更新	`opensea accounts update --display-name <name> --bio <text> --profile-image-url <url> --banner-image-url <url>`
ソーシャルリンクの追加	`opensea accounts add-social <platform> <url>`
ソーシャルリンクの削除	`opensea accounts remove-social <platform>`

コレクション設定

タスク	CLIコマンド
自分のコレクションの取得	`opensea collections my`
コレクション設定の更新	`opensea collections update <slug> --display-name <name> --description <text> --image-url <url> --banner-url <url>`
コレクション安全性属性の設定	`opensea collections set-safe <slug> [--safe]`

ウォッチリスト

タスク	CLIコマンド
ウォッチリストの追加	`opensea watchlist add <collection_slug>`
ウォッチリストからの削除	`opensea watchlist remove <collection_slug>`
ウォッチリストステータスの確認	`opensea watchlist status <collection_slug>`
自分のウォッチリスト一覧	`opensea watchlist list [--limit <n>]`

注文管理

タスク	CLIコマンド
自分のアクティブなリスティング一覧	`opensea listings mine [--limit <n>]`
自分のアクティブなオファー一覧	`opensea offers mine [--limit <n>]`
注文のキャンセル（リスティング/オファー）	`opensea orders cancel <order_hash> [--send] [--wallet-provider <provider>]`
購入トランザクションの署名（履行）	`opensea orders fulfill <order_hash> [--send] [...]`

MCPサーバー

OpenSea MCPサーバーは、上記のCLIコマンドとほぼ同じ操作をModel Context Protocol経由でAIエージェントに提供します。

インストール

# npx経由で使用（推奨）
npx @opensea/mcp --api-key <key>

# または設定経由で
# Claude Desktopの場合、claude_desktop_config.jsonに追加：
{
  "mcpServers": {
    "opensea": {
      "command": "npx",
      "args": ["-y", "@opensea/mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

使用可能なMCPツール

# コレクション
get_collection         # スラッグでコレクション詳細を取得
get_collection_stats   # コレクションのフロア価格とボリューム統計を取得
get_trending_collections  # トレンドコレクションを取得
get_top_collections    # トップコレクションを取得
search_collections     # コレクションを検索

# NFT
get_nft                # 単一NFTの詳細を取得（チェーン、コントラクト、トークンID）
get_nfts_by_collection # コレクション別NFT一覧
get_nfts_by_account    # ウォレット別NFT一覧
get_nfts_by_contract   # コントラクト別NFT一覧
search_nfts            # NFTを検索

# トークン
get_tokens             # トークン詳細を取得
get_trending_tokens    # トレンドトークンを取得
get_top_tokens         # トップトークンを取得
search_tokens          # トークンを検索
get_token_balances     # トークンバランスを確認
get_token_transfers    # トークン転送履歴を取得

# 検索（全タイプ）
search                 # コレクション、NFT、トークン、アカウントを横断検索

# イベント
get_events             # イベントを一覧
get_events_by_collection  # コレクション別イベント
get_events_by_nft      # NFT別イベント
get_events_by_account  # アカウント別イベント

# ドロップ
get_drops              # ドロップ一覧
get_drop               # ドロップ詳細

# アカウント
get_account            # アカウント詳細を取得（アドレスまたはENS）
resolve_ens            # ENS名を解決

MCPリソース

opensea://collection/{slug}           # 各コレクションを構造化リソースとして利用可能
opensea://nft/{chain}/{contract}/{id}  # 各NFTを構造化リソースとして利用可能

MCPサーバーは2つのエントリポイントを持つ静的MCPサーバーです：stdio（デフォルト）と streamable-http（--transport streamable-http で有効化）。

シェルスクリプト

CLI @opensea/cli は推奨されるインターフェースですが、scripts/ ディレクトリには依存関係の少ないスタンドアロンのシェルスクリプトも含まれています。これらは代替として機能し、古いワークフローとの互換性を確保します。

# コレクション詳細
./scripts/collections/opensea-collection.sh boredapeyachtclub

# コレクションNFT一覧
./scripts/collections/opensea-collection-nfts.sh boredapeyachtclub 5

# アカウントNFT一覧
./scripts/accounts/opensea-account-nfts.sh ethereum 0x123... 10

これらのスクリプトは OPENSEA_API_KEY を必要とします。CLIが設定されていないが curl と jq が利用可能な環境で役立ちます。

JavaScript/TypeScript SDK

@opensea/sdk パッケージは、上記のすべてのエンドポイントのプログラムによるアクセスを提供します。

import { OpenSeaSDK } from '@opensea/sdk'

const client = new OpenSeaSDK({
  apiKey: 'your-api-key',
  // ウォレット認証操作には walletProvider が必要
})

// コレクション詳細を取得
const collection = await client.collections.get('boredapeyachtclub')

// コレクション内のNFTを一覧
const nfts = await client.nfts.listByCollection('boredapeyachtclub', { limit: 5 })

// トレンドトークンを取得
const tokens = await client.tokens.trending({ limit: 10 })

フルSDKのドキュメントは @opensea/sdk パッケージを参照してください。

リファレンス

ドキュメント	場所
ウォレット認証（REST + MCP）	`references/authentication.md`
ツール登録（ERC-8257）	`references/tool-registration.md`
設定と環境変数	`references/configuration.md`

注意事項とベストプラクティス

常にAPIキーを保存して再利用 — インスタントキーは非常に貴重で、再取得は信頼性が低いです。
可能な限りサーバーサイドフィルタリングを使用 — レート制限を節約するために、生の結果をクライアントサイドでフィルタリングしないでください。
実際の操作には opensea-marketplace を使用 — opensea-api はデータの読み取り専用であり、リスティングやオファーの作成/履行は行いません。
ウォレット認証が必要な場合 は、references/authentication.md を参照して認証情報ルーチンを設定してください。
ドロップミント — クロスチェーンミントトランザクションは常に順番に送信し、receipt_request をポーリングして完了を確認してください。
イベントストリーミング の場合は、websocat がシステムにインストールされていることを確認してください。
レート制限 — デフォルトのインスタントキーは1秒あたり10リクエストが上限です。より高いレートが必要な場合は、OpenSeaの開発者ポータルからフルAPIキーを取得してください。
MCPサーバー は、AIエージェントがOpenSeaデータと対話するためのネイティブな方法を提供します — エージェントワークフローにはCLIよりもこちらを優先してください。

お気に入りのAIに質問する

ドキュメント

OpenSea API

このスキルを使用するタイミング（scope_in）

このスキルを使用しないタイミング（scope_out、ハンドオフ）

クイックスタート

APIキーの解決（最初のリクエスト前にお読みください）

フロー（毎回この順序で手順を実行）

エッジケース

タスクガイド

NFTデータの読み取り

トークンデータの読み取り

ウォレット認証RESTとMCP

マーケットプレイスクエリ（読み取り専用）

サーバーサイド特性フィルタリング

検索

イベントと監視

ドロップとミント

アカウントとENS

認証済み操作（ウォレットが必要）

プロフィール

コレクション設定

ウォッチリスト

注文管理

MCPサーバー

インストール

使用可能なMCPツール

MCPリソース

シェルスクリプト

JavaScript/TypeScript SDK

リファレンス

注意事項とベストプラクティス

Individual skills in this repo

ProjectOpenSea/opensea-skill

ProjectOpenSea/opensea-skill

ProjectOpenSea/opensea-skill

ProjectOpenSea/opensea-skill

関連スキル

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

このスキルを使用するタイミング（`scope_in`）

このスキルを使用しないタイミング（`scope_out`、ハンドオフ）