opensea

What this skill does

# 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:

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

```bash
npm install -g @opensea/cli
```

For write / fulfillment flows that sign with Privy:

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

## Endpoint reference → [references/marketplace.md](./references/marketplace.md)

### 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 B