OpenSea (NFT Marketplace Data + Seaport Trades)
OpenSea is the dominant NFT marketplace. This skill queries marketplace data — listings, offers, sales / events, floor prices, drops, traits — and executes Seaport trades via the official @opensea/cli. For NFT metadata (name, image, traits, ownership) outside the marketplace context, use Alchemy's NFT API instead. For pure cross-chain token swaps (no marketplace context), use the lifi ecosystem skill.
|
|
| Primary tool |
npx @opensea/cli@latest <command> (or npm install -g @opensea/cli) |
| REST API base |
https://api.opensea.io/api/v2 |
| Auth |
OPENSEA_API_KEY header — instant via POST /api/v2/auth/keys, or signup at the developer portal |
| Optional Privy |
PRIVY_APP_ID / PRIVY_APP_SECRET / PRIVY_WALLET_ID for write / fulfillment flows |
| Chains |
Ethereum, Base, Arbitrum, Optimism, Polygon, and more |
When to use this skill
Use opensea when any of the following are true:
- The user wants marketplace data — listings, offers, floor prices, sales history, collection stats
- The user wants to buy / sell an NFT via Seaport (fulfill listing or accept offer)
- The user wants to search across OpenSea (collections / NFTs / tokens / accounts)
- The user wants to monitor events — sales, transfers, mints, listings, offers — for a collection or NFT
- The user wants to explore drops or build a mint transaction for a SeaDrop contract
- The user wants token discovery in the OpenSea-curated context (top, trending, by group)
When NOT to use this skill (handoff)
| Need |
Use instead |
| NFT metadata (name, image, traits, ownership lookup) outside a marketplace context |
alchemy-api (NFT API) — broader coverage, fewer rate limits |
| Pure cross-chain token swap (no NFT marketplace need) |
lifi (ecosystem skill) — broader bridge / DEX aggregation |
| Token spot prices for valuation |
alchemy-api (Prices API) |
| Token metadata, search, list by chain (general) |
alchemy-api (Token API) |
| Current wallet balances (token + native) |
alchemy-api (Portfolio / Token API) |
| Transaction history (transfers in / out) |
alchemy-api (Transfers API) |
Live blockchain reads (block #, gas, eth_call) |
alchemy-cli (live) or alchemy-api (JSON-RPC) |
| Pre-execution simulation |
alchemy-api (Simulation API) |
| Account abstraction (bundlers, gas managers) |
alchemy-api |
| Smart wallet / embedded wallet flows |
alchemy-api (Wallets / Account Kit) |
Scope contract
This skill covers (scope_in):
- Marketplace data:
opensea listings best, opensea listings best-for-nft, opensea offers best-for-nft, opensea offers all, opensea collections stats, opensea collections trending, opensea collections top, opensea collections traits
- Seaport trades: fulfillment data for buying (
opensea-fulfill-listing.sh) and selling (opensea-fulfill-offer.sh); creating listings / offers via opensea-post.sh with the Seaport order structure
- Events / monitoring:
opensea events list, events by-collection, events by-nft, events by-account — sale / transfer / mint / listing / offer / trait_offer / collection_offer
- Drops + minting:
opensea drops list, opensea drops get, opensea drops mint
- Search:
opensea search across collections / NFTs / tokens / accounts
- Account utilities:
opensea accounts resolve (ENS / username / address)
This skill does NOT cover (scope_out):
- General NFT metadata reads (name, image, traits, ownership, contract metadata) outside the marketplace context → handoff:
alchemy-api (NFT API). OpenSea's NFT data is marketplace-flavored and rate-limited; Alchemy's NFT API is broader and cheaper for pure metadata.
- Pure cross-chain token swaps (no NFT marketplace use case) → handoff:
lifi (ecosystem skill). OpenSea's swap aggregator works, but lifi covers more bridges and chains.
- Token spot prices for valuation / display → handoff:
alchemy-api (Prices API)
- General token metadata, search, list → handoff:
alchemy-api (Token API)
- Wallet balances (token + native) → handoff:
alchemy-api (Portfolio / Token API)
- Transaction transfer history → handoff:
alchemy-api (Transfers API)
- Live RPC reads → handoff:
alchemy-cli or alchemy-api (JSON-RPC)
- Pre-execution simulation → handoff:
alchemy-api (Simulation API)
- Account abstraction → handoff:
alchemy-api (Wallets / Bundler / Gas Manager)
- Embedded / smart wallet onboarding → handoff:
alchemy-api (Account Kit)
- Signed tx submission → user wallet (or Privy if configured for OpenSea write flows)
Setup
API key is required. Get one instantly via the auth endpoint (no signup) or register at the developer portal for higher limits:
# Instant key (no signup needed)
export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')
# Or set an existing key
# export OPENSEA_API_KEY="..."
Install the CLI globally (optional — npx @opensea/cli works without install):
npm install -g @opensea/cli
For write / fulfillment flows that sign with Privy:
export PRIVY_APP_ID="..."
export PRIVY_APP_SECRET="..."
export PRIVY_WALLET_ID="..."
Security: never expose OPENSEA_API_KEY or Privy credentials in client-side code. Server-side only.
Marketplace queries (most-used)
| Task |
CLI |
| Best listings for a collection |
opensea listings best <slug> [--limit <n>] |
| Best listing for a specific NFT |
opensea listings best-for-nft <slug> <token_id> |
| Best offer for an NFT |
opensea offers best-for-nft <slug> <token_id> |
| All listings on a collection |
opensea listings all <slug> [--limit <n>] |
| All offers on a collection |
opensea offers all <slug> [--limit <n>] |
| Trait offers |
opensea offers traits <slug> --type <type> --value <value> |
| Collection stats (floor, volume) |
opensea collections stats <slug> |
| Trending collections |
opensea collections trending [--timeframe <tf>] [--chains <chains>] |
| Top collections by sort |
opensea collections top [--sort-by <field>] [--chains <chains>] |
| Collection traits |
opensea collections traits <slug> |
Seaport trade execution
| Task |
Script |
| Get fulfillment data to buy an NFT |
opensea-fulfill-listing.sh <chain> <order_hash> <buyer> |
| Get fulfillment data to sell (accept offer) |
opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id> |
| Generic POST to OpenSea API |
opensea-post.sh <path> <json_body> |
Events / monitoring
| Task |
CLI |
| Recent events (filterable by type) |
opensea events list [--event-type <type>] |
| Events for a collection |
opensea events by-collection <slug> [--event-type <type>] |
| Events for a specific NFT |
opensea events by-nft <chain> <contract> <token_id> |
| Events for an account |
opensea events by-account <address> |
Event types: sale, transfer, mint, listing, offer, trait_offer, collection_offer.
For real-time event streaming: opensea-stream-collection.sh <slug> (requires websocat).
Drops + minting
| Task |
CLI |
| List drops (featured / upcoming / recent) |
opensea drops list [--type <type>] |
| Drop details + stages |
opensea drops get <slug> |
| Build mint tx |
opensea drops mint <slug> --minter <address> [--quantity <n>] |
Search
| Task |
CLI |
| 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 |
| Multi-type search |
opensea search <query> --types collection,nft,token |
Quick examples
Get the floor + 24h volume for Bored Apes
opensea collections stats boredapeyachtclub
Find the cheapest listing for a collection
opensea listings best boredapeyachtclub --limit 1
Buy an NFT (fulfill a listing)
# 1. Get the best listing for a specific NFT
opensea listings best-for-nft boredapeyachtclub 1234
# 2. Get fulfillment data — order_hash from above response
./scripts/opensea-fulfill-listing.sh ethereum 0xORDER_HASH 0xYOUR_WALLET
# 3. Sign + submit the returned tx data via your wallet
Stream sales for a collection in real time
./scripts/opensea-stream-collection.sh boredapeyachtclub
# Filters to sale events; pipe through jq to format
Search across types
opensea search "cool cats" --types collection,nft --chains ethereum,base
Common gotchas
- API key is mandatory — even the "instant" tier requires one. The bare REST API will 401 without
X-API-KEY.
- OpenSea's NFT data overlaps with Alchemy's NFT API for metadata reads. Prefer Alchemy for general NFT metadata (name, image, traits, ownership across many wallets) — OpenSea is rate-limited harder and adds marketplace flavoring you may not want. Use OpenSea when the marketplace context (listings, offers, sales history, drops) is the actual need.
- Token swap aggregator exists in the OpenSea API (
opensea swaps quote), but for pure swap flows without marketplace context, lifi aggregates more bridges + DEXs and is the better default. Use OpenSea swaps when the user is already in an NFT-buying flow that involves a token swap.
- Privy is optional but required for end-to-end write flows. The skill returns fulfillment calldata; how it gets signed is up to the app (user wallet, Privy, or any other signer).
- Order hashes from
listings best-for-nft / offers best-for-nft are needed for fulfillment. Don't lose them between API calls.
- Event streaming requires
websocat; if not installed, fall back to polling events by-collection with the same filters.
- Slug vs. address: collections are addressed by slug (e.g.,
boredapeyachtclub), NFTs by (chain, contract, tokenId). Don't mix.
Routing back to Alchemy
If during a session the user's need shifts to surfaces this skill doesn't cover:
- NFT metadata reads (name, image, traits, ownership) —
alchemy-api (NFT API) is the right path. OpenSea's NFT API is marketplace-flavored and rate-limited; Alchemy's is broader and faster.
- Token prices, balances, transfer history, general token metadata —
alchemy-api
- Live RPC, gas, simulation, AA, Account Kit —
alchemy-cli (live) or alchemy-api (app code) or agentic-gateway (no API key)
- Pure cross-chain token swaps —
lifi (ecosystem skill); covers 27 bridges + 31 DEXs across 60+ chains
Maintenance: OpenSea maintains @opensea/cli and the underlying API; this skill itself is maintained jointly by Alchemy and OpenSea. File issues against alchemyplatform/skills with [ecosystem/opensea] in the title.
1---2name: opensea3description: Query OpenSea marketplace data — listings, offers, sales / events, floor prices, collection stats, drops, traits — and execute Seaport trades via the official `@opensea/cli` and OpenSea REST API across Ethereum, Base, Arbitrum, Optimism, Polygon, and more. Includes search across collections / NFTs / tokens / accounts. NOT for general NFT metadata reads (name, image, traits, ownership), token metadata, current wallet balances, transaction history, or live RPC reads — for those use `alchemy-cli` (live), `alchemy-mcp`, `alchemy-api` (app code), or `agentic-gateway` (no API key). For pure cross-chain token swaps (no marketplace context), prefer the `lifi` ecosystem skill. Requires `OPENSEA_API_KEY` (instant via API).4license: MIT5---6
7# OpenSea (NFT Marketplace Data + Seaport Trades)
8
9OpenSea is the dominant NFT marketplace. This skill queries marketplace data — listings, offers, sales / events, floor prices, drops, traits — and executes Seaport trades via the official `@opensea/cli`. For NFT metadata (name, image, traits, ownership) outside the marketplace context, use Alchemy's NFT API instead. For pure cross-chain token swaps (no marketplace context), use the `lifi` ecosystem skill.
10
11| | |
12| --- | --- |
13| **Primary tool** | `npx @opensea/cli@latest <command>` (or `npm install -g @opensea/cli`) |
14| **REST API base** | `https://api.opensea.io/api/v2` |
15| **Auth** | `OPENSEA_API_KEY` header — instant via `POST /api/v2/auth/keys`, or signup at the developer portal |
16| **Optional Privy** | `PRIVY_APP_ID` / `PRIVY_APP_SECRET` / `PRIVY_WALLET_ID` for write / fulfillment flows |
17| **Chains** | Ethereum, Base, Arbitrum, Optimism, Polygon, and more |
18
19## When to use this skill
20
21Use `opensea` when **any** of the following are true:
22
23- The user wants **marketplace data** — listings, offers, floor prices, sales history, collection stats
24- The user wants to **buy / sell an NFT** via Seaport (fulfill listing or accept offer)
25- The user wants to **search** across OpenSea (collections / NFTs / tokens / accounts)
26- The user wants to **monitor events** — sales, transfers, mints, listings, offers — for a collection or NFT
27- The user wants to **explore drops** or build a mint transaction for a SeaDrop contract
28- The user wants **token discovery** in the OpenSea-curated context (top, trending, by group)
29
30## When NOT to use this skill (handoff)
31
32| Need | Use instead |
33| --- | --- |
34| NFT metadata (name, image, traits, ownership lookup) outside a marketplace context | `alchemy-api` (NFT API) — broader coverage, fewer rate limits |
35| Pure cross-chain token swap (no NFT marketplace need) | `lifi` (ecosystem skill) — broader bridge / DEX aggregation |
36| Token spot prices for valuation | `alchemy-api` (Prices API) |
37| Token metadata, search, list by chain (general) | `alchemy-api` (Token API) |
38| Current wallet balances (token + native) | `alchemy-api` (Portfolio / Token API) |
39| Transaction history (transfers in / out) | `alchemy-api` (Transfers API) |
40| Live blockchain reads (block #, gas, `eth_call`) | `alchemy-cli` (live) or `alchemy-api` (JSON-RPC) |
41| Pre-execution simulation | `alchemy-api` (Simulation API) |
42| Account abstraction (bundlers, gas managers) | `alchemy-api` |
43| Smart wallet / embedded wallet flows | `alchemy-api` (Wallets / Account Kit) |
44
45## Scope contract
46
47**This skill covers (`scope_in`):**
48
49- **Marketplace data:** `opensea listings best`, `opensea listings best-for-nft`, `opensea offers best-for-nft`, `opensea offers all`, `opensea collections stats`, `opensea collections trending`, `opensea collections top`, `opensea collections traits`
50- **Seaport trades:** fulfillment data for buying (`opensea-fulfill-listing.sh`) and selling (`opensea-fulfill-offer.sh`); creating listings / offers via `opensea-post.sh` with the Seaport order structure
51- **Events / monitoring:** `opensea events list`, `events by-collection`, `events by-nft`, `events by-account` — sale / transfer / mint / listing / offer / trait_offer / collection_offer
52- **Drops + minting:** `opensea drops list`, `opensea drops get`, `opensea drops mint`
53- **Search:** `opensea search` across collections / NFTs / tokens / accounts
54- **Account utilities:** `opensea accounts resolve` (ENS / username / address)
55
56**This skill does NOT cover (`scope_out`):**
57
58- General NFT metadata reads (name, image, traits, ownership, contract metadata) outside the marketplace context → handoff: `alchemy-api` (NFT API). OpenSea's NFT data is marketplace-flavored and rate-limited; Alchemy's NFT API is broader and cheaper for pure metadata.
59- Pure cross-chain token swaps (no NFT marketplace use case) → handoff: `lifi` (ecosystem skill). OpenSea's swap aggregator works, but `lifi` covers more bridges and chains.
60- Token spot prices for valuation / display → handoff: `alchemy-api` (Prices API)
61- General token metadata, search, list → handoff: `alchemy-api` (Token API)
62- Wallet balances (token + native) → handoff: `alchemy-api` (Portfolio / Token API)
63- Transaction transfer history → handoff: `alchemy-api` (Transfers API)
64- Live RPC reads → handoff: `alchemy-cli` or `alchemy-api` (JSON-RPC)
65- Pre-execution simulation → handoff: `alchemy-api` (Simulation API)
66- Account abstraction → handoff: `alchemy-api` (Wallets / Bundler / Gas Manager)
67- Embedded / smart wallet onboarding → handoff: `alchemy-api` (Account Kit)
68- Signed tx submission → user wallet (or Privy if configured for OpenSea write flows)
69
70## Setup
71
72API key is required. Get one instantly via the auth endpoint (no signup) or register at the developer portal for higher limits:
73
74```bash
75# Instant key (no signup needed)
76export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')
77
78# Or set an existing key
79# export OPENSEA_API_KEY="..."
80```
81
82Install the CLI globally (optional — `npx @opensea/cli` works without install):
83
84```bash
85npm install -g @opensea/cli
86```
87
88For write / fulfillment flows that sign with Privy:
89
90```bash
91export PRIVY_APP_ID="..."
92export PRIVY_APP_SECRET="..."
93export PRIVY_WALLET_ID="..."
94```
95
96> **Security:** never expose `OPENSEA_API_KEY` or Privy credentials in client-side code. Server-side only.
97
98## Endpoint reference → [references/marketplace.md](./references/marketplace.md)
99
100### Marketplace queries (most-used)
101
102| Task | CLI |
103| --- | --- |
104| Best listings for a collection | `opensea listings best <slug> [--limit <n>]` |
105| Best listing for a specific NFT | `opensea listings best-for-nft <slug> <token_id>` |
106| Best offer for an NFT | `opensea offers best-for-nft <slug> <token_id>` |
107| All listings on a collection | `opensea listings all <slug> [--limit <n>]` |
108| All offers on a collection | `opensea offers all <slug> [--limit <n>]` |
109| Trait offers | `opensea offers traits <slug> --type <type> --value <value>` |
110| Collection stats (floor, volume) | `opensea collections stats <slug>` |
111| Trending collections | `opensea collections trending [--timeframe <tf>] [--chains <chains>]` |
112| Top collections by sort | `opensea collections top [--sort-by <field>] [--chains <chains>]` |
113| Collection traits | `opensea collections traits <slug>` |
114
115### Seaport trade execution
116
117| Task | Script |
118| --- | --- |
119| Get fulfillment data to **buy** an NFT | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |
120| Get fulfillment data to **sell** (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |
121| Generic POST to OpenSea API | `opensea-post.sh <path> <json_body>` |
122
123### Events / monitoring
124
125| Task | CLI |
126| --- | --- |
127| Recent events (filterable by type) | `opensea events list [--event-type <type>]` |
128| Events for a collection | `opensea events by-collection <slug> [--event-type <type>]` |
129| Events for a specific NFT | `opensea events by-nft <chain> <contract> <token_id>` |
130| Events for an account | `opensea events by-account <address>` |
131
132Event types: `sale`, `transfer`, `mint`, `listing`, `offer`, `trait_offer`, `collection_offer`.
133
134For real-time event streaming: `opensea-stream-collection.sh <slug>` (requires `websocat`).
135
136### Drops + minting
137
138| Task | CLI |
139| --- | --- |
140| List drops (featured / upcoming / recent) | `opensea drops list [--type <type>]` |
141| Drop details + stages | `opensea drops get <slug>` |
142| Build mint tx | `opensea drops mint <slug> --minter <address> [--quantity <n>]` |
143
144### Search
145
146| Task | CLI |
147| --- | --- |
148| Search collections | `opensea search <query> --types collection` |
149| Search NFTs | `opensea search <query> --types nft` |
150| Search tokens | `opensea search <query> --types token` |
151| Search accounts | `opensea search <query> --types account` |
152| Multi-type search | `opensea search <query> --types collection,nft,token` |
153
154## Quick examples
155
156### Get the floor + 24h volume for Bored Apes
157
158```bash
159opensea collections stats boredapeyachtclub
160```
161
162### Find the cheapest listing for a collection
163
164```bash
165opensea listings best boredapeyachtclub --limit 1
166```
167
168### Buy an NFT (fulfill a listing)
169
170```bash
171# 1. Get the best listing for a specific NFT
172opensea listings best-for-nft boredapeyachtclub 1234
173
174# 2. Get fulfillment data — order_hash from above response
175./scripts/opensea-fulfill-listing.sh ethereum 0xORDER_HASH 0xYOUR_WALLET
176
177# 3. Sign + submit the returned tx data via your wallet
178```
179
180### Stream sales for a collection in real time
181
182```bash
183./scripts/opensea-stream-collection.sh boredapeyachtclub
184# Filters to sale events; pipe through jq to format
185```
186
187### Search across types
188
189```bash
190opensea search "cool cats" --types collection,nft --chains ethereum,base
191```
192
193## Common gotchas
194
195- **API key is mandatory** — even the "instant" tier requires one. The bare REST API will 401 without `X-API-KEY`.
196- **OpenSea's NFT data overlaps with Alchemy's NFT API** for metadata reads. Prefer Alchemy for *general* NFT metadata (name, image, traits, ownership across many wallets) — OpenSea is rate-limited harder and adds marketplace flavoring you may not want. Use OpenSea when the marketplace context (listings, offers, sales history, drops) is the actual need.
197- **Token swap aggregator** exists in the OpenSea API (`opensea swaps quote`), but for pure swap flows without marketplace context, `lifi` aggregates more bridges + DEXs and is the better default. Use OpenSea swaps when the user is already in an NFT-buying flow that involves a token swap.
198- **Privy is optional** but required for end-to-end write flows. The skill returns fulfillment calldata; how it gets signed is up to the app (user wallet, Privy, or any other signer).
199- **Order hashes** from `listings best-for-nft` / `offers best-for-nft` are needed for fulfillment. Don't lose them between API calls.
200- **Event streaming** requires `websocat`; if not installed, fall back to polling `events by-collection` with the same filters.
201- **Slug vs. address**: collections are addressed by slug (e.g., `boredapeyachtclub`), NFTs by `(chain, contract, tokenId)`. Don't mix.
202
203## Routing back to Alchemy
204
205If during a session the user's need shifts to surfaces this skill doesn't cover:
206
207- **NFT metadata reads** (name, image, traits, ownership) — `alchemy-api` (NFT API) is the right path. OpenSea's NFT API is marketplace-flavored and rate-limited; Alchemy's is broader and faster.
208- **Token prices, balances, transfer history, general token metadata** — `alchemy-api`
209- **Live RPC, gas, simulation, AA, Account Kit** — `alchemy-cli` (live) or `alchemy-api` (app code) or `agentic-gateway` (no API key)
210- **Pure cross-chain token swaps** — `lifi` (ecosystem skill); covers 27 bridges + 31 DEXs across 60+ chains
211
212---
213
214> **Maintenance:** OpenSea maintains `@opensea/cli` and the underlying API; this skill itself is maintained jointly by Alchemy and OpenSea. File issues against `alchemyplatform/skills` with `[ecosystem/opensea]` in the title.
alchemyplatform