opensea-api

OpenSea API

Overview

Interact with OpenSea's NFT marketplace through their REST API and real-time Stream API. Fetch NFT metadata, collection information, listings, offers, and events across multiple blockchains including Ethereum, Polygon, Base, Arbitrum, and more.

When to Use

• Fetching NFT metadata, traits, and ownership information
• Getting collection details and statistics
• Retrieving active listings and offers
• Tracking NFT events (sales, transfers, listings)
• Building NFT dashboards and analytics tools
• Real-time monitoring of marketplace activity
• Integrating NFT data into applications

Prerequisites

• OpenSea API key (free tier available)
• curl for HTTP requests
• jq for JSON parsing (brew install jq on macOS, apt install jq on Linux)
• For Stream API: Node.js with @opensea/stream-js or Python with opensea-stream

Getting an API Key

1. Visit OpenSea Developer Portal
2. Create a developer account
3. Generate an API key
4. Set the environment variable:

export OPENSEA_API_KEY="your-api-key"

Add to your shell profile (~/.zshrc or ~/.bashrc) for persistence:

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

API Base URL

https://api.opensea.io

All requests require the API key in the header:

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

Rate Limits

Request Type	Rate Limit
GET requests	4/second per API key
POST requests	2/second per API key

For higher limits, apply at the OpenSea Developer Portal.

Supported Blockchains

Chain	API Name
Ethereum	ethereum
Polygon	matic
Arbitrum	arbitrum
Optimism	optimism
Base	base
Avalanche	avalanche
Blast	blast
Zora	zora
Solana	solana

Quick Start

Fetch an NFT:

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

Get collection info:

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

NFT Endpoints

Get Single NFT

Fetch metadata, traits, ownership, and rarity for a single 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"

Example:

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

Response includes:

• identifier - Token ID
• name - NFT name
• description - NFT description
• image_url - Image URL
• metadata_url - Token URI
• owners - Current owner(s)
• traits - Array of trait objects
• rarity - Rarity information

List NFTs by Collection

Fetch multiple NFTs for a collection with pagination.

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

Parameters:

• limit - Max results (1-200, default 50)
• next - Cursor for pagination

Example:

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

List NFTs by Contract

Fetch NFTs for a specific contract address.

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

List NFTs by Account

Fetch NFTs owned by a wallet address.

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

Example:

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

Collection Endpoints

Get Collection

Fetch collection details including description, fees, and social links.

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

Response includes:

• collection - Collection slug
• name - Collection name
• description - Description
• image_url - Collection image
• banner_image_url - Banner image
• owner - Collection owner address
• total_supply - Total NFTs in collection
• created_date - Creation date
• fees - Creator fees and platform fees

Example:

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

Get Collection Stats

Fetch floor price, volume, and other statistics.

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

Response includes:

• total - All-time stats (volume, sales, average_price, etc.)
• intervals - Stats by time period (1d, 7d, 30d)

Example:

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

Get Collection Traits

Fetch all traits and their value counts for a collection.

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

Listings Endpoints

Get Best Listing for NFT

Fetch the cheapest active listing for a specific 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"

Example:

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

Get All Listings for NFT

Fetch all active listings for a specific 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"

Get All Listings for Collection

Fetch all active listings for a collection.

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

Offers Endpoints

Get Best Offer for NFT

Fetch the highest active offer for a specific 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"

Get All Offers for Collection

Fetch all active offers (individual and collection offers).

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

Get Trait Offers

Fetch offers for NFTs with specific trait values.

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

Events Endpoints

Get Events by NFT

Fetch events (sales, transfers, listings) for a specific 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"

Event Types:

• sale - NFT was sold
• transfer - NFT was transferred
• listing - NFT was listed for sale
• offer - Offer was made on NFT
• cancel - Listing/offer was cancelled

Example:

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

Get Events by Collection

Fetch events for an entire collection.

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"

Get Events by Account

Fetch events for a specific wallet address.

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

Account Endpoints

Get Account

Fetch an OpenSea account profile.

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

Response includes:

• address - Wallet address
• username - OpenSea username
• profile_image_url - Profile image
• banner_image_url - Banner image
• bio - User bio
• social_media_accounts - Linked social accounts

Stream API (Real-time WebSocket)

Overview

The Stream API provides real-time events via WebSocket. Use it for:

• Push notifications for NFT activity
• Live activity feeds
• Real-time price monitoring

Supported Events

Event	Description
item.listed	NFT listed for sale
item.sold	NFT was sold
item.transferred	NFT transferred between wallets
item.metadata_updated	NFT metadata changed
item.cancelled	Listing/offer cancelled
item.received_bid	Bid received on NFT

JavaScript/TypeScript Setup

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 Setup

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 Protocol (Orders)

OpenSea uses the Seaport protocol for all orders. To create or fulfill orders programmatically:

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
});

Helper Scripts

Fetch NFT Metadata

./scripts/fetch_nft.sh ethereum 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D 1234

Get Collection Stats

./scripts/collection_stats.sh boredapeyachtclub

Monitor Collection Activity

./scripts/monitor_collection.sh boredapeyachtclub

Get NFTs by Wallet

./scripts/wallet_nfts.sh ethereum 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Common Use Cases

Check Floor Price

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

Get Recent Sales

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}'

Find Cheapest Listings

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]'

Export Collection Traits to JSON

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

Get Owner's Portfolio Value

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

Error Handling

Status Code	Meaning	Action
400	Bad Request	Check request parameters
401	Unauthorized	Verify API key
403	Forbidden	Check API key permissions
404	Not Found	Verify contract/token/collection exists
429	Rate Limited	Reduce request frequency
500	Server Error	Retry with backoff

Retry with Exponential Backoff

#!/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

Troubleshooting

"Invalid API Key"

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

"Rate Limit Exceeded"

• Reduce request frequency to under 4/second
• Add delays between requests
• Use the Stream API for real-time data instead of polling
• Apply for rate limit increase

"Collection/NFT Not Found"

• Verify the collection slug (check OpenSea URL)
• Ensure the contract address is correct
• Check if the NFT exists on the specified chain

Stream API Connection Issues

// 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();

Best Practices

• Cache responses - NFT metadata rarely changes, cache aggressively
• Use pagination - Always handle next cursor for large datasets
• Prefer Stream API - Use WebSocket for real-time data instead of polling
• Handle rate limits - Implement exponential backoff for 429 errors
• Validate input - Check addresses and token IDs before API calls
• Secure API keys - Never expose keys in frontend code; use a backend proxy
• Use appropriate chain - Always specify the correct blockchain for multi-chain NFTs

Resources

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