opensea

# 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>] [--limi...

# OpenSea Skill

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

## What is this?

This is an [Agent Skill](https://skills.sh/docs) for AI coding assistants. Once installed, your agent can interact with the OpenSea API to query NFT data, execute marketplace operations, and swap ERC20 tokens using the [OpenSea CLI](https://github.com/ProjectOpenSea/opensea-cli), shell scripts, or the MCP server.

## Prerequisites

- `OPENSEA_API_KEY` environment variable — for CLI, SDK, and REST API scripts
- `OPENSEA_MCP_TOKEN` environment variable — for the MCP server (separate from API key)
- Node.js >= 18.0.0 — for `@opensea/cli`
- `curl` for REST shell scripts
- `jq` (recommended) for parsing JSON responses

Get both credentials at [opensea.io/settings/developer](https://opensea.io/settings/developer).

## Installing the Skill

### Using npx

```bash
npx skills add ProjectOpenSea/opensea-skill
```

### Using Claude Code

```bash
/skill install ProjectOpenSea/opensea-skill
```

### Manual Installation

Clone this repository to your skills directory:

```bash
git clone https://github.com/ProjectOpenSea/opensea-skill.git ~/.skills/opensea
```

Refer to your AI tool's documentation for skills directory configuration.

## What's Included

### Skill Definition

[`SKILL.md`](SKILL.md) — the main skill file that teaches your agent how to use the OpenSea API, including the CLI, task guides, script references, MCP tool documentation, and end-to-end workflows for buying, selling, and swapping tokens.

### OpenSea CLI (Recommended)

The [`@opensea/cli`](https://github.com/ProjectOpenSea/opensea-cli) package provides a command-line interface and programmatic SDK for all OpenSea API operations. Install with `npm install -g @opensea/cli` or use `npx @opensea/cli`.

```bash
opensea collections get mfers
opensea listings best mfers --limit 5
opensea tokens trending --limit 5
opensea search "cool cats"
open...