opensea-api

OpenSea API

概述

通过 OpenSea 的 REST API 和实时 Stream API 与其 NFT 市场交互。获取跨多个区块链（包括 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 开发者门户
2. 创建开发者账号
3. 生成 API 密钥
4. 设置环境变量：

export OPENSEA_API_KEY="your-api-key"

将其添加到 shell 配置文件（~/.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 开发者门户申请。

支持的区块链

链	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"

“超出速率限制”

• 将请求频率降至每秒 4 次以下
• 在请求之间添加延迟
• 使用 Stream API 获取实时数据，而非轮询
• 申请提高速率限制

“未找到合集/NFT”

• 确认合集 slug（检查 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