opensea

Query NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.

# OpenSea API

Query NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.

## Quick start

1. Set `OPENSEA_API_KEY` in your environment
2. **Preferred:** Use the `opensea` CLI (`@opensea/cli`) for all queries and operations
3. Alternatively, use the shell scripts in `scripts/` or the MCP server

```bash
export OPENSEA_API_KEY="your-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

# Get best listings for a collection
opensea listings best boredapeyachtclub --limit 5

# Search across OpenSea
opensea search "cool cats"

# Get trending tokens
opensea tokens trending --limit 5

# Get a swap quote
opensea swaps quote \
  --from-chain base --from-address 0x0000000000000000000000000000000000000000 \
  --to-chain base --to-address 0xTokenAddress \
  --quantity 0.02 --address 0xYourWallet
```

## Task guide

> **Recommended:** Use the `opensea` CLI (`@opensea/cli`) as your primary tool. It covers all the operations below with a consistent interface, structured output, and built-in pagination. Install with `npm install -g @opensea/cli` or use `npx @opensea/cli`. The shell scripts in `scripts/` remain available as alternatives.

### Token swaps

OpenSea's API includes a cross-chain DEX aggregator for swapping ERC20 tokens with optimal routing across all supported chains.

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get swap quote with calldata | `opensea swaps quote --from-chain <chain> --from-address <addr> --to-chain <chain> --to-address <addr> --quantity <qty> --address <wallet>` | `get_token_swap_quote` (MCP) or `opensea-swap.sh` |
| 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) |
| Search tokens | `opensea search <query> --types token` | `search_tokens` (MCP) |
| Check token balances | `get_token_balances` (MCP) | — |

### 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>` |
| List NFTs in collection | `opensea nfts list-by-collection <slug> [--limit <n>]` | `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>` | — |

### Marketplace queries

| Task | CLI Command | Alternative |
|------|------------|-------------|
| Get best listings for collection | `opensea listings best <slug> [--limit <n>]` | `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>` |

### Marketplace actions (POST)

| Task | Script |
|------|--------|
| Get fulfillment data (buy NFT) | `opensea-fulfill-listing.sh <chain> <order_hash> <buyer>` |
| Get fulfillment data (accept offer) | `opensea-fulfill-offer.sh <chain> <order_hash> <seller> <contract> <token_id>` |
| Generic POST request | `opensea-post.sh <path> <json_body>` |

### 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>]` | `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`

### Accounts

| Task | CLI Command |
|------|------------|
| Get account details | `opensea accounts get <address>` |

### Generic requests

| Task | Script |
|------|--------|
| Any GET endpoint | `opensea-get.sh <path> [query]` |
| Any POST endpoint | `opensea-post.sh <path> <json_body>` |

## Buy/Sell workflows

### Buying an NFT

1. Find the NFT and check its listing:
   ```bash
   ./scripts/opensea-best-listing.sh cool-cats-nft 1234
   ```

2. Get the order hash from the response, then get fulfillment data:
   ```bash
   ./scripts/opensea-fulfill-listing.sh ethereum 0x_order_hash 0x_your_wallet
   ```

3. The response contains transaction data to execute on-chain

### Selling an NFT (accepting an offer)

1. Check offers on your NFT:
   ```bash
   ./scripts/opensea-best-offer.sh cool-cats-nft 1234
   ```

2. Get fulfillment data for the offer:
   ```bash
   ./scripts/opensea-fulfill-offer.sh ethereum 0x_offer_hash 0x_your_wallet 0x_nft_contract 1234
   ```

3. Execute the returned transaction data

### Creating listings/offers

Creating new listings and offers requires wallet signatures. Use `opensea-post.sh` with the Seaport order structure - see `references/marketplace-api.md` for full details.

## OpenSea CLI (`@opensea/cli`)

The [OpenSea CLI](https://github.com/ProjectOpenSea/opensea-cli) is the recommended way for AI agents to interact with OpenSea. It provides a consistent command-line interface and a programmatic TypeScript/JavaScript SDK.

### Installation

```bash
# Install globally
npm install -g @opensea/cli

# Or use without installing
npx @opensea/cli collections get mfers
```

### Authentication

```bash
# Set via environment variable (recommended)
export OPENSEA_API_KEY="your-api-key"
opensea collections get mfers

# Or pass inline
opensea --api-key your-api-key collections get mfers
```

### CLI Commands

| Command | Description |
|---|---|
| `collections` | Get, list, stats, and traits for NFT collections |
| `nfts` | Get, list, refresh metadata, and contract details for NFTs |
| `listings` | Get all, best, or best-for-nft listing