opensea-api

OpenSea API

概要

OpenSea の NFT マーケットプレイスを、REST API とリアルタイムの Stream API を通じて利用できます。Ethereum、Polygon、Base、Arbitrum など複数のブロックチェーンにまたがる NFT のメタデータ、コレクション情報、出品、オファー、イベントを取得できます。

使用する場面

• NFT のメタデータ、特性、所有者情報を取得する
• コレクションの詳細や統計情報を取得する
• アクティブな出品やオファーを取得する
• NFT のイベント（販売、譲渡、出品）を追跡する
• NFT ダッシュボードや分析ツールを構築する
• マーケットプレイスの動向をリアルタイムで監視する
• アプリケーションに NFT データを統合する

前提条件

• OpenSea API キー（無料プランあり）
• HTTP リクエスト用の curl
• JSON 解析用の jq（macOS では brew install jq、Linux では apt install jq）
• Stream API の場合：@opensea/stream-js を使用する Node.js、または opensea-stream を使用する Python

API キーの取得

1. OpenSea Developer Portal にアクセスします
2. 開発者アカウントを作成します
3. API キーを生成します
4. 環境変数を設定します：

export OPENSEA_API_KEY="your-api-key"

永続化するには、シェルのプロファイル（~/.zshrc または ~/.bashrc）に追加します：

echo 'export OPENSEA_API_KEY="your-api-key"' >> ~/.zshrc

API ベース URL

https://api.opensea.io

すべてのリクエストで、ヘッダーに API キーが必要です：

-H "X-API-KEY: $OPENSEA_API_KEY"

レート制限

リクエストの種類	レート制限
GET リクエスト	API キーごとに 4/秒
POST リクエスト	API キーごとに 2/秒

上限の引き上げを希望する場合は、OpenSea Developer Portal から申請してください。

対応ブロックチェーン

チェーン	API 名
Ethereum	ethereum
Polygon	matic
Arbitrum	arbitrum
Optimism	optimism
Base	base
Avalanche	avalanche
Blast	blast
Zora	zora
Solana	solana

クイックスタート

NFT を取得します：

curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクション情報を取得します：

curl -X GET "https://api.opensea.io/api/v2/collections/boredapeyachtclub" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

NFT エンドポイント

単一の NFT を取得

単一の NFT のメタデータ、特性、所有者、レア度を取得します。

curl -X GET "https://api.opensea.io/api/v2/chain/{chain}/contract/{contract_address}/nfts/{token_id}" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

例：

# Get Bored Ape #1
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

レスポンスに含まれる項目：

• identifier - トークン ID
• name - NFT 名
• description - NFT の説明
• image_url - 画像 URL
• metadata_url - トークン URI
• owners - 現在の所有者
• traits - 特性オブジェクトの配列
• rarity - レア度情報

コレクション別に NFT を一覧表示

ページネーションを使用して、コレクションの複数の NFT を取得します。

curl -X GET "https://api.opensea.io/api/v2/collection/{collection_slug}/nfts?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

パラメーター：

• limit - 結果の最大数（1～200、デフォルトは 50）
• next - ページネーション用カーソル

例：

# Get first 50 Pudgy Penguins
curl -X GET "https://api.opensea.io/api/v2/collection/pudgypenguins/nfts?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コントラクト別に NFT を一覧表示

特定のコントラクトアドレスの NFT を取得します。

curl -X GET "https://api.opensea.io/api/v2/chain/{chain}/contract/{contract_address}/nfts?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

アカウント別に NFT を一覧表示

ウォレットアドレスが所有する NFT を取得します。

curl -X GET "https://api.opensea.io/api/v2/chain/{chain}/account/{address}/nfts?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

例：

# Get NFTs owned by an address on Ethereum
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/account/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/nfts?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションエンドポイント

コレクションを取得

説明、手数料、ソーシャルリンクなど、コレクションの詳細を取得します。

curl -X GET "https://api.opensea.io/api/v2/collections/{collection_slug}" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

レスポンスに含まれる項目：

• collection - コレクションのスラッグ
• name - コレクション名
• description - 説明
• image_url - コレクション画像
• banner_image_url - バナー画像
• owner - コレクション所有者のアドレス
• total_supply - コレクション内の NFT 総数
• created_date - 作成日
• fees - クリエイター手数料とプラットフォーム手数料

例：

curl -X GET "https://api.opensea.io/api/v2/collections/azuki" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションの統計情報を取得

フロア価格、取引量、その他の統計情報を取得します。

curl -X GET "https://api.opensea.io/api/v2/collections/{collection_slug}/stats" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

レスポンスに含まれる項目：

• total - 全期間の統計情報（取引量、販売数、平均価格など）
• intervals - 期間別の統計情報（1d、7d、30d）

例：

curl -X GET "https://api.opensea.io/api/v2/collections/boredapeyachtclub/stats" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションの特性を取得

コレクションのすべての特性と、それぞれの値の件数を取得します。

curl -X GET "https://api.opensea.io/api/v2/traits/{collection_slug}" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

出品エンドポイント

NFT の最安出品を取得

特定の NFT のアクティブな出品のうち、最も安いものを取得します。

curl -X GET "https://api.opensea.io/api/v2/listings/collection/{collection_slug}/nfts/{token_id}/best" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

例：

# Get best listing for Bored Ape #1234
curl -X GET "https://api.opensea.io/api/v2/listings/collection/boredapeyachtclub/nfts/1234/best" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

NFT のすべての出品を取得

特定の NFT のアクティブな出品をすべて取得します。

curl -X GET "https://api.opensea.io/api/v2/orders/{chain}/seaport/listings?asset_contract_address={contract}&token_ids={token_id}" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションのすべての出品を取得

コレクションのアクティブな出品をすべて取得します。

curl -X GET "https://api.opensea.io/api/v2/listings/collection/{collection_slug}/all?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

オファーエンドポイント

NFT の最高額オファーを取得

特定の NFT のアクティブなオファーのうち、最も高額なものを取得します。

curl -X GET "https://api.opensea.io/api/v2/offers/collection/{collection_slug}/nfts/{token_id}/best" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションのすべてのオファーを取得

有効なオファー（個別オファーとコレクションオファー）をすべて取得します。

curl -X GET "https://api.opensea.io/api/v2/offers/collection/{collection_slug}/all?limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

トレイトオファーを取得

特定のトレイト値を持つ NFT のオファーを取得します。

curl -X GET "https://api.opensea.io/api/v2/offers/collection/{collection_slug}/traits" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

イベントエンドポイント

NFT ごとにイベントを取得

特定の NFT のイベント（売却、転送、出品）を取得します。

curl -X GET "https://api.opensea.io/api/v2/events/chain/{chain}/contract/{contract}/nfts/{token_id}?event_type=sale&limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

イベントタイプ：

• sale - NFT が売却されました
• transfer - NFT が転送されました
• listing - NFT が売りに出されました
• offer - NFT にオファーが出されました
• cancel - 出品／オファーがキャンセルされました

例：

# Get sales history for Bored Ape #1234
curl -X GET "https://api.opensea.io/api/v2/events/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1234?event_type=sale" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

コレクションごとにイベントを取得

コレクション全体のイベントを取得します。

curl -X GET "https://api.opensea.io/api/v2/events/collection/{collection_slug}?event_type=sale&limit=50" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

アカウントごとにイベントを取得

特定のウォレットアドレスのイベントを取得します。

curl -X GET "https://api.opensea.io/api/v2/events/accounts/{address}?event_type=sale" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

アカウントエンドポイント

アカウントを取得

OpenSea のアカウントプロフィールを取得します。

curl -X GET "https://api.opensea.io/api/v2/accounts/{address}" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

レスポンスに含まれる情報：

• address - ウォレットアドレス
• username - OpenSea のユーザー名
• profile_image_url - プロフィール画像
• banner_image_url - バナー画像
• bio - ユーザーの自己紹介
• social_media_accounts - リンクされたソーシャルアカウント

Stream API（リアルタイム WebSocket）

概要

Stream API は WebSocket を通じてリアルタイムイベントを提供します。次の用途に使用します：

• NFT アクティビティのプッシュ通知
• ライブアクティビティフィード
• リアルタイムの価格監視

対応イベント

イベント	説明
item.listed	NFT が売りに出されました
item.sold	NFT が売却されました
item.transferred	NFT がウォレット間で転送されました
item.metadata_updated	NFT のメタデータが変更されました
item.cancelled	出品／オファーがキャンセルされました
item.received_bid	NFT に入札がありました

JavaScript/TypeScript のセットアップ

npm install @opensea/stream-js

import { OpenSeaStreamClient, Network } from '@opensea/stream-js';

const client = new OpenSeaStreamClient({
  network: Network.MAINNET,
  token: process.env.OPENSEA_API_KEY,
});

// Subscribe to collection events
client.onItemListed('boredapeyachtclub', (event) => {
  console.log('New listing:', event);
  console.log('Price:', event.payload.base_price);
  console.log('Token ID:', event.payload.item.nft_id);
});

client.onItemSold('boredapeyachtclub', (event) => {
  console.log('Sale:', event);
  console.log('Price:', event.payload.sale_price);
});

// Subscribe to all events globally
client.onItemListed('*', (event) => {
  console.log('Global listing:', event);
});

Python のセットアップ

pip install opensea-stream

import asyncio
from opensea_stream import OpenSeaStreamClient

async def main():
    client = OpenSeaStreamClient(api_key=os.environ['OPENSEA_API_KEY'])

    async def handle_listing(event):
        print(f"New listing: {event}")

    await client.subscribe_to_collection(
        collection_slug='boredapeyachtclub',
        event_type='item.listed',
        callback=handle_listing
    )

asyncio.run(main())

Seaport プロトコル（注文）

OpenSea はすべての注文に Seaport プロトコルを使用します。プログラムから注文を作成または約定するには：

JavaScript SDK

npm install opensea-js

import { OpenSeaSDK, Chain } from 'opensea-js';
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

const sdk = new OpenSeaSDK(wallet, {
  chain: Chain.Mainnet,
  apiKey: process.env.OPENSEA_API_KEY,
});

// Create a listing
const listing = await sdk.createListing({
  asset: {
    tokenId: '1234',
    tokenAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  },
  startAmount: 10, // 10 ETH
  expirationTime: Math.round(Date.now() / 1000 + 60 * 60 * 24 * 7), // 7 days
});

// Fulfill a listing (buy)
const order = await sdk.api.getOrder({
  side: 'ask',
  assetContractAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  tokenId: '1234',
});
await sdk.fulfillOrder({ order });

// Make an offer
const offer = await sdk.createOffer({
  asset: {
    tokenId: '1234',
    tokenAddress: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D',
  },
  startAmount: 5, // 5 WETH
});

ヘルパースクリプト

NFT メタデータを取得

./scripts/fetch_nft.sh ethereum 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D 1234

コレクションの統計情報を取得

./scripts/collection_stats.sh boredapeyachtclub

コレクションのアクティビティを監視

./scripts/monitor_collection.sh boredapeyachtclub

ウォレットごとに NFT を取得

./scripts/wallet_nfts.sh ethereum 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

よくあるユースケース

フロア価格を確認

curl -s "https://api.opensea.io/api/v2/collections/boredapeyachtclub/stats" \
  -H "X-API-KEY: $OPENSEA_API_KEY" | jq '.total.floor_price'

最近の売却を取得

curl -s "https://api.opensea.io/api/v2/events/collection/boredapeyachtclub?event_type=sale&limit=10" \
  -H "X-API-KEY: $OPENSEA_API_KEY" | jq '.asset_events[] | {token_id: .nft.identifier, price: .payment.quantity}'

最安の出品を検索

curl -s "https://api.opensea.io/api/v2/listings/collection/boredapeyachtclub/all?limit=10" \
  -H "X-API-KEY: $OPENSEA_API_KEY" | jq '.listings | sort_by(.price.current.value) | .[0:5]'

コレクションのトレイトを JSON にエクスポート

curl -s "https://api.opensea.io/api/v2/traits/boredapeyachtclub" \
  -H "X-API-KEY: $OPENSEA_API_KEY" > traits.json

所有者のポートフォリオ価値を取得

./scripts/wallet_nfts.sh ethereum 0xYOUR_ADDRESS | jq '[.nfts[].floor_price] | add'

エラー処理

ステータスコード	意味	対処方法
400	不正なリクエスト	リクエストパラメーターを確認します
401	認証されていません	API キーを確認します
403	許可されていません	API キーの権限を確認します
404	見つかりません	コントラクト／トークン／コレクションが存在することを確認します
429	レート制限	リクエスト頻度を下げます
500	サーバーエラー	間隔を空けて再試行します

指数バックオフで再試行

#!/usr/bin/env bash
max_retries=4
retry_count=0
base_delay=2

while [ "$retry_count" -lt "$max_retries" ]; do
  response=$(curl -s -w "%{http_code}" -o /tmp/response.json \
    "https://api.opensea.io/api/v2/collections/boredapeyachtclub" \
    -H "X-API-KEY: $OPENSEA_API_KEY")

  if [ "$response" = "200" ]; then
    cat /tmp/response.json
    exit 0
  elif [ "$response" = "429" ]; then
    delay=$((base_delay ** (retry_count + 1)))
    echo "Rate limited. Retrying in ${delay}s..." >&2
    sleep "$delay"
    retry_count=$((retry_count + 1))
  else
    echo "Error: HTTP $response" >&2
    exit 1
  fi
done
echo "Max retries exceeded" >&2
exit 1

トラブルシューティング

「無効な API キー」

# Verify your key is set
echo $OPENSEA_API_KEY

# Test with a simple request
curl -I "https://api.opensea.io/api/v2/collections/boredapeyachtclub" \
  -H "X-API-KEY: $OPENSEA_API_KEY"

「レート制限を超過しました」

• リクエスト頻度を 1 秒あたり 4 回未満に減らします
• リクエスト間に遅延を追加します
• ポーリングの代わりに、リアルタイムデータには Stream API を使用します
• レート制限の引き上げを申請します

「コレクション／NFT が見つかりません」

• コレクションのスラッグを確認します（OpenSea の URL を確認してください）
• コントラクトアドレスが正しいことを確認します
• 指定されたチェーン上に NFT が存在するか確認します

Stream API の接続に関する問題

// Add error handling and reconnection
client.onError((error) => {
  console.error('Stream error:', error);
});

// The client automatically reconnects, but you can also:
client.disconnect();
client.connect();

ベストプラクティス

• レスポンスをキャッシュする - NFT メタデータはほとんど変更されないため、積極的にキャッシュします
• ページネーションを使用する - 大規模なデータセットでは、常に next カーソルを処理します
• Stream API を優先する - ポーリングの代わりに、リアルタイムデータには WebSocket を使用します
• レート制限に対応する - 429 エラーに対して指数バックオフを実装します
• 入力を検証する - API 呼び出しの前にアドレスとトークン ID を確認します
• API キーを保護する - フロントエンドコードでキーを公開せず、バックエンドプロキシを使用します
• 適切なチェーンを使用する - マルチチェーン NFT では、常に正しいブロックチェーンを指定します

Resources

• OpenSea Developer Documentation
• API Reference
• Stream API Overview
• Seaport Protocol
• OpenSea JS SDK
• Stream JS SDK