Agent Skills: 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