Query NFT data, trade on the Seaport marketplace, and swap ERC20 tokens across Ethereum, Base, Arbitrum, Optimism, Polygon, and more.
This is an Agent Skill 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, shell scripts, or the MCP server.
OPENSEA_API_KEYenvironment variable — for CLI, SDK, REST API scripts, and MCP server- Node.js >= 18.0.0 — for
@opensea/cli curl— for REST shell scriptsjq(recommended) — for parsing JSON responses
Get your API key at opensea.io/settings/developer. The same key works for the REST API, CLI, and MCP server.
For write operations (swaps, Seaport fulfillment), you'll need a wallet that can sign transactions. Use whatever fits your security model — Privy, Fireblocks, a backend signing proxy, etc.
npx skills add ProjectOpenSea/opensea-skillClone this repository to your skills directory:
git clone https://github.com/ProjectOpenSea/opensea-skill.git ~/.skills/openseaRefer to your AI tool's documentation for skills directory configuration.
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.
The @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.
opensea collections get mfers
opensea listings best mfers --limit 5
opensea tokens trending --limit 5
opensea search "cool cats"
opensea swaps quote --from-chain base --from-address 0x0000000000000000000000000000000000000000 \
--to-chain base --to-address 0xTokenAddress --quantity 0.02 --address 0xYourWalletSupports JSON, table, and TOON output formats. TOON uses ~40% fewer tokens than JSON, ideal for AI agent context windows (--format toon).
See SKILL.md for the full CLI command reference and SDK usage.
Ready-to-use scripts in scripts/ for common operations (alternative to the CLI):
| Script | Purpose |
|---|---|
opensea-collection.sh |
Fetch collection by slug |
opensea-nft.sh |
Fetch single NFT by chain/contract/token |
opensea-best-listing.sh |
Get lowest listing for an NFT |
opensea-best-offer.sh |
Get highest offer for an NFT |
opensea-swap.sh |
Swap tokens via OpenSea DEX aggregator |
opensea-fulfill-listing.sh |
Get buy transaction data |
opensea-fulfill-offer.sh |
Get sell transaction data |
See SKILL.md for the full scripts reference and usage examples.
Detailed API documentation in references/:
rest-api.md— REST endpoint families and paginationmarketplace-api.md— Buy/sell workflows and Seaport detailsstream-api.md— WebSocket event streamingseaport.md— Seaport protocol and NFT purchase executiontoken-swaps.md— Token swap workflows via MCP
An official MCP server provides direct LLM integration for token swaps and NFT operations. Add to your MCP config:
{
"mcpServers": {
"opensea": {
"url": "https://mcp.opensea.io/mcp",
"headers": {
"X-API-KEY": "OPENSEA_API_KEY"
}
}
}
}See SKILL.md for the full list of available MCP tools.
Once installed, prompt your AI assistant:
Get me the floor price for the Pudgy Penguins collection on OpenSea
Swap 0.02 ETH to USDC on Base using OpenSea
Show me the best offer on BAYC #1234
The agent will use the opensea CLI to query the API directly.
This skill supports all chains available on OpenSea, including ethereum, solana, abstract, ape_chain, arbitrum, avalanche, b3, base, bera_chain, blast, flow, gunzilla, hyperevm, hyperliquid, ink, megaeth, monad, optimism, polygon, ronin, sei, shape, somnia, soneium, unichain, and zora.
- OpenSea CLI — CLI and SDK for OpenSea API
- OpenSea Developer Docs
- OpenSea Developer Portal
- Agent Skills Directory