opensea-api

What this skill does

# OpenSea API

Query NFT and token data, browse drops, stream events, and search across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.

## When to use this skill (`scope_in`)

Use `opensea-api` for **read-only** operations:

- Collection details, stats, traits, trending, and top collections
- NFT details, ownership, metadata refresh
- Token details, trending tokens, top tokens, token groups
- Search across collections, NFTs, tokens, and accounts
- Reading marketplace listings, offers, and orders (not executing them)
- Events and activity monitoring (including real-time WebSocket streams)
- Drops and mint eligibility
- Account lookups and ENS resolution

## When NOT to use this skill (`scope_out`, handoff)

| Need | Use instead |
|---|---|
| Buy/sell NFTs (fulfill listings or offers) | `opensea-marketplace` |
| Create new listings or offers | `opensea-marketplace` |
| Cross-chain NFT purchases | `opensea-marketplace` |
| Swap ERC20 tokens | `opensea-swaps` |
| Set up wallet signing providers | `opensea-wallet` |
| Build/register/gate AI agent tools | `opensea-tool-sdk` |

## Quick start

```bash
# Get an instant free-tier API key (no signup needed)
export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')

# Install the CLI globally (or use npx)
npm install -g @opensea/cli

# Get collection info
opensea collections get boredapeyachtclub

# Get floor price and volume stats
opensea collections stats boredapeyachtclub

# Get NFT details
opensea nfts get ethereum 0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d 1234

# Search across OpenSea
opensea search "cool cats"

# Get trending tokens
opensea tokens trending --limit 5
```

## Task guide

> **Recommended:** Use the `opensea` CLI (`@opensea/cli`) as your primary tool. Install with `npm install -g @opensea/cli` or use `npx @opensea/cli`. The shell scripts in `scripts/` remain available as alternatives.

### Reading NFT data

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get collection details | `opensea collections get <slug>` | `opensea-collection.sh <slug>` |
| Get collection stats | `opensea collections stats <slug>` | `opensea-collection-stats.sh <slug>` |
| Get trending collections | `opensea collections trending [--timeframe <tf>] [--chains <chains>]` | `opensea-collections-trending.sh [timeframe] [limit] [chains] [category]` |
| Get top collections | `opensea collections top [--sort-by <field>] [--chains <chains>]` | `opensea-collections-top.sh [sort_by] [limit] [chains] [category]` |
| List NFTs in collection | `opensea nfts list-by-collection <slug> [--limit <n>] [--traits <json>]` | `opensea-collection-nfts.sh <slug> [limit] [next]` |
| Get single NFT | `opensea nfts get <chain> <contract> <token_id>` | `opensea-nft.sh <chain> <contract> <token_id>` |
| List NFTs by wallet | `opensea nfts list-by-account <chain> <address> [--limit <n>]` | `opensea-account-nfts.sh <chain> <address> [limit]` |
| List NFTs by contract | `opensea nfts list-by-contract <chain> <contract> [--limit <n>]` | |
| Get collection traits | `opensea collections traits <slug>` | |
| Get contract details | `opensea nfts contract <chain> <address>` | |
| Refresh NFT metadata | `opensea nfts refresh <chain> <contract> <token_id>` | |

### Reading token data

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get trending tokens | `opensea tokens trending [--chains <chains>] [--limit <n>]` | `get_trending_tokens` (MCP) |
| Get top tokens by volume | `opensea tokens top [--chains <chains>] [--limit <n>]` | `get_top_tokens` (MCP) |
| Get token details | `opensea tokens get <chain> <address>` | `get_tokens` (MCP) |
| List token groups | `opensea token-groups list [--limit <n>] [--next <cursor>]` | `opensea-token-groups.sh [limit] [cursor]` |
| Get token group by slug | `opensea token-groups get <slug>` | `opensea-token-group.sh <slug>` |
| Search tokens | `opensea search <query> --types token` | `search_tokens` (MCP) |
| Check token balances | `get_token_balances` (MCP) | |
| Request instant API key | `opensea auth request-key` | `opensea-auth-request-key.sh` |

### Marketplace queries (read-only)

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get best listings for collection | `opensea listings best <slug> [--limit <n>] [--traits <json>]` | `opensea-best-listing.sh <slug> <token_id>` |
| Get best listing for specific NFT | `opensea listings best-for-nft <slug> <token_id>` | `opensea-best-listing.sh <slug> <token_id>` |
| Get best offer for NFT | `opensea offers best-for-nft <slug> <token_id>` | `opensea-best-offer.sh <slug> <token_id>` |
| List all collection listings | `opensea listings all <slug> [--limit <n>]` | `opensea-listings-collection.sh <slug> [limit]` |
| List all collection offers | `opensea offers all <slug> [--limit <n>]` | `opensea-offers-collection.sh <slug> [limit]` |
| Get collection offers | `opensea offers collection <slug> [--limit <n>]` | `opensea-offers-collection.sh <slug> [limit]` |
| Get trait offers | `opensea offers traits <slug> --type <type> --value <value>` | |
| Get order by hash | | `opensea-order.sh <chain> <order_hash>` |

### Server-side trait filtering

Three collection-scoped endpoints accept a `traits` query parameter for server-side filtering:

| Endpoint | CLI | SDK |
|---|---|---|
| List NFTs in collection | `opensea nfts list-by-collection <slug> --traits <json>` | `client.nfts.listByCollection(slug, { traits })` |
| Best listings for collection | `opensea listings best <slug> --traits <json>` | `client.listings.best(slug, { traits })` |
| Events for collection | `opensea events by-collection <slug> --traits <json>` | `client.events.byCollection(slug, { traits })` |

`--traits` takes a JSON-encoded array of `{ "traitType": string, "value": string }` objects. Multiple entries are AND-combined:

```bash
opensea nfts list-by-collection doodles-official \
  --traits '[{"traitType":"Background","value":"Red"}]'
```

Always prefer server-side filtering over client-side: paginating the unfiltered set wastes rate-limit budget.

### Search

| Task | CLI Command |
|------|------------|
| Search collections | `opensea search <query> --types collection` |
| Search NFTs | `opensea search <query> --types nft` |
| Search tokens | `opensea search <query> --types token` |
| Search accounts | `opensea search <query> --types account` |
| Search multiple types | `opensea search <query> --types collection,nft,token` |
| Search on specific chain | `opensea search <query> --chains base,ethereum` |

### Events and monitoring

| Task | CLI Command | Alternative |
|------|------------|-------------|
| List recent events | `opensea events list [--event-type <type>] [--limit <n>]` | |
| Get collection events | `opensea events by-collection <slug> [--event-type <type>] [--traits <json>]` | `opensea-events-collection.sh <slug> [event_type] [limit]` |
| Get events for specific NFT | `opensea events by-nft <chain> <contract> <token_id>` | |
| Get events for account | `opensea events by-account <address>` | |
| Stream real-time events | | `opensea-stream-collection.sh <slug>` (requires websocat) |

Event types: `sale`, `transfer`, `mint`, `listing`, `offer`, `trait_offer`, `collection_offer`

### Drops & minting

| Task | CLI Command | Alternative |
|------|------------|-------------|
| List drops (featured/upcoming/recent) | `opensea drops list [--type <type>] [--chains <chains>]` | `opensea-drops.sh [type] [limit] [chains]` |
| Get drop details and stages | `opensea drops get <slug>` | `opensea-drop.sh <slug>` |
| Build mint transaction | `opensea drops mint <slug> --minter <address> [--quantity <n>]` | `opensea-drop-mint.sh <slug> <minter> [quantity]` |
| Deploy a new SeaDrop contract | | `deploy_seadrop_contract` (MCP) |
| Check deployment status | | `get_deploy_receipt` (MCP) |

### Accounts

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get account details |