Query Analytics and Events

The OpenSea API provides rich analytics data — collection stats, trending rankings, and historical marketplace events. Use these endpoints to build dashboards, alert systems, and analytics tools.

Prerequisites

Node.js >= 20.0.0
OpenSea API key (get one here, or use the instant API key endpoint)

Security Warning: Do not use the SDK in client-side code — your API key would be exposed. Use it on a backend server and return transaction data to your frontend.

Setup

npm install @opensea/sdk ethers

import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";

const provider = new ethers.JsonRpcProvider("https://your-rpc-url");

const sdk = new OpenSeaSDK(provider, {
  chain: Chain.Mainnet,
  apiKey: "YOUR_API_KEY",
});

The examples below use ethers.js. For viem setup, see Buy and Sell NFTs — With viem. All SDK methods work the same with either library.

Collection Stats

Get floor price, total volume, number of owners, total supply, and more for any collection.

SDK

const stats = await sdk.api.getCollectionStats("boredapeyachtclub");
console.log("Floor price:", stats.total.floor_price);
console.log("Total volume:", stats.total.volume);
console.log("Num owners:", stats.total.num_owners);
console.log("Total supply:", stats.total.supply);

curl

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

Trending Collections

Discover which collections are trending over different time windows.

SDK

const trending = await sdk.api.getTrendingCollections();
console.log(trending);

curl

curl -X GET "https://api.opensea.io/api/v2/collections/trending" \
  -H "X-API-KEY: YOUR_API_KEY"

Top Collections

Get the highest-ranked collections by volume or floor price.

SDK

const top = await sdk.api.getTopCollections();
console.log(top);

curl

curl -X GET "https://api.opensea.io/api/v2/collections/top" \
  -H "X-API-KEY: YOUR_API_KEY"

Trending and Top Tokens

Track token market activity alongside NFT collections. See Swap Tokens — Discover Tokens for SDK and curl examples using the trending and top token endpoints.

Querying Historical Events

Retrieve marketplace events filtered by collection, NFT, or account. Events include sales, transfers, listings, offers, cancellations, and more.

Event Types

Type	Description
`sale`	An item was sold
`transfer`	An item was transferred
`listing`	A new listing was created
`offer`	An offer was made
`cancel`	An order was cancelled
`redemption`	An item was redeemed

Events by Collection

SDK

const events = await sdk.api.getEventsByCollection("boredapeyachtclub", {
  event_type: "sale",
  limit: 10,
});

for (const event of events.asset_events) {
  console.log(event);
}

curl

curl -X GET "https://api.opensea.io/api/v2/events/collection/boredapeyachtclub?event_type=sale&limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"

Events by NFT

const nftEvents = await sdk.api.getEventsByNFT(
  "ethereum",
  "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  "1234",
  { event_type: "sale" },
);

curl -X GET "https://api.opensea.io/api/v2/events/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts/1234?event_type=sale" \
  -H "X-API-KEY: YOUR_API_KEY"

Events by Account

const accountEvents = await sdk.api.getEventsByAccount("0xWALLET_ADDRESS", {
  event_type: "sale",
  limit: 20,
});

curl -X GET "https://api.opensea.io/api/v2/events/accounts/0xWALLET_ADDRESS?event_type=sale&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"

Global Events

Query across all collections:

const globalEvents = await sdk.api.getEvents({
  event_type: "sale",
  after: Math.floor(Date.now() / 1000) - 3600, // last hour
  limit: 50,
});

curl -X GET "https://api.opensea.io/api/v2/events?event_type=sale&limit=50" \
  -H "X-API-KEY: YOUR_API_KEY"

Pagination

Event endpoints use cursor-based pagination. The response includes a next cursor — pass it to fetch the next page.

let cursor = undefined;

do {
  const response = await sdk.api.getEventsByCollection("boredapeyachtclub", {
    event_type: "sale",
    limit: 50,
    next: cursor,
  });

  for (const event of response.asset_events) {
    console.log(event);
  }

  cursor = response.next;
} while (cursor);

# First page
curl -X GET "https://api.opensea.io/api/v2/events/collection/boredapeyachtclub?event_type=sale&limit=50" \
  -H "X-API-KEY: YOUR_API_KEY"

# Next page (use the "next" value from the previous response)
curl -X GET "https://api.opensea.io/api/v2/events/collection/boredapeyachtclub?event_type=sale&limit=50&next=CURSOR_VALUE" \
  -H "X-API-KEY: YOUR_API_KEY"

CLI

The OpenSea CLI provides quick access to analytics data:

# Collection stats
opensea collections stats boredapeyachtclub

# Trending tokens
opensea tokens trending --limit 5

# Collection details
opensea collections get boredapeyachtclub

# Events
opensea events collection boredapeyachtclub --limit 10

Next Steps

Stream Real-Time Events — get events in real time via WebSocket
Search and Discovery — find collections and NFTs
Events API reference
@opensea/sdk on GitHub