> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensea.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Analytics and Events

Build dashboards and analytics using OpenSea collection stats, trending data, and historical events.

The OpenSea API provides 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](https://docs.opensea.io/reference/api-keys), or use the [instant API key endpoint](https://docs.opensea.io/reference/create_instant_api_key))

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

### Setup

```bash
npm install @opensea/sdk viem
```

```typescript
import { createPublicClient, createWalletClient, http } from "viem";
import { mainnet } from "viem/chains";
import { OpenSeaSDK, Chain } from "@opensea/sdk/viem";

const publicClient = createPublicClient({ chain: mainnet, transport: http("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: mainnet, transport: http("https://your-rpc-url"), account: "0x..." });

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

> The examples below use viem. The SDK also supports ethers.js (v6+); see [Buy and Sell NFTs](https://docs.opensea.io/docs/buy-and-sell-nfts) for the ethers setup. All SDK methods work the same with either library.

## Collection stats

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

#### SDK

```typescript
const stats = await sdk.api.getCollectionStats("boredapeyachtclub");
console.log("Floor price:", stats.total.floorPrice);
console.log("Total volume:", stats.total.volume);
console.log("Num owners:", stats.total.numOwners);
console.log("Sales:", stats.total.sales);
```

#### curl

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

## Trending collections

See which collections are trending over different time windows.

#### SDK

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

#### curl

```bash
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

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

#### curl

```bash
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](https://docs.opensea.io/docs/swap-tokens#step-1-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

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

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

#### curl

```bash
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

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

```bash
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

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

```bash
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:

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

```bash
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.

```typescript
let cursor = undefined;

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

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

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

```bash
# 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 <Anchor label="OpenSea CLI" target="_blank" href="https://github.com/ProjectOpenSea/opensea-cli">OpenSea CLI</Anchor> provides quick access to analytics data:

```bash
# 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](https://docs.opensea.io/docs/stream-real-time-events): get events in real time via WebSocket
* [Search and Discovery](https://docs.opensea.io/docs/search-and-discovery): find collections and NFTs
* <Anchor label="Events API reference" target="_blank" href="https://docs.opensea.io/reference/list_events_by_collection">Events API reference</Anchor>
* <Anchor label="OpenSea SDK" target="_blank" href="https://github.com/ProjectOpenSea/opensea-js">@opensea/sdk on GitHub</Anchor>