opensea-cli

Query the OpenSea API from the command line or programmatically. Designed for both AI agents and developers.

Table of Contents

• Install
• Authentication
• Quick Start
• Commands
• Programmatic SDK
• Output Formats
• Exit Codes
• Requirements
• Development
• Docs

Install

npm install -g @opensea/cli

Or use without installing:

npx @opensea/cli collections get mfers

Authentication

Set your API key via environment variable or flag:

# Get an instant free-tier API key (no signup needed)export OPENSEA_API_KEY=$(curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key')
opensea collections get mfers
# or pass inline
opensea --api-key your-api-key collections get mfers

Get an API key instantly via the command above, or get a full key at opensea.io/settings/developer for higher rate limits. See API key docs for details.

Wallet-authenticated endpoints also require a scoped token:

export OPENSEA_PRIVATE_KEY="..."
opensea login --private-key --scopes read:favorites,write:wallets
WALLET=$(opensea --format json whoami | jq -r '.address')
opensea api request GET "/api/v2/account/$WALLET/favorites" --params '{"limit":1}'
opensea accounts mark-agent "$WALLET"
opensea accounts remove-agent "$WALLET"
opensea auth revoke

Private-key login uses SIWE and requires an explicit --scopes list. The private key signs locally and is not stored. The CLI keeps the session needed to revoke the personal access token (PAT), and api request sends the stored wallet JWT alongside OPENSEA_API_KEY. Use opensea auth refresh after the JWT expires. For interactive login, run opensea login without --private-key. See the wallet-auth guide.

Quick Start

# Get collection details
opensea collections get mfers
# Get floor price and volume stats
opensea collections stats mfers
# List NFTs in a collection
opensea nfts list-by-collection mfers --limit 5
# Get best listings
opensea listings best mfers --limit 5
# Search across OpenSea
opensea search collections "cool cats"# Get trending tokens
opensea tokens trending --limit 5
# Get materialized token activity for selected windows
opensea tokens activity-stats base 0x4200000000000000000000000000000000000006 --windows 1h,24h
# Human-readable table output
opensea --format table collections stats mfers

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 listings
offers	Get all, collection, best-for-nft, and trait offers
drops	Query drops and build same-chain or cross-chain mint transactions
transactions	Poll transaction and cross-chain receipt status
events	List marketplace events (sales, transfers, mints, etc.)
search	Search collections, NFTs, tokens, and accounts
tokens	Get trending tokens, top tokens, token details, and activity stats
swaps	Get swap quotes for token trading
accounts	Get account details and manage agent wallet designations
whoami	Show the current wallet, scopes, and scope source
api request	Call any API v2 endpoint with the active API key and wallet JWT

This table is a high-level summary; run opensea --help for the current command list and docs/cli-reference.md for the full reference.

Global options: --api-key, --chain (default: ethereum), --format (json/table/toon), --base-url

Programmatic SDK

import{OpenSeaCLI,OpenSeaAPIError}from"@opensea/cli"constclient=newOpenSeaCLI({apiKey: process.env.OPENSEA_API_KEY})constcollection=awaitclient.collections.get("mfers")const{ nfts }=awaitclient.nfts.listByCollection("mfers",{limit: 5})const{ listings }=awaitclient.listings.best("mfers",{limit: 10})const{ asset_events }=awaitclient.events.byCollection("mfers",{eventType: "sale",})const{ tokens }=awaitclient.tokens.trending({chains: ["base"],limit: 5})constactivity=awaitclient.tokens.activityStats("base","0x4200000000000000000000000000000000000006",{windows: ["1h","24h"]},)constresults=awaitclient.search.collections("mfers",{limit: 5})constmarkedAgent=awaitclient.accounts.markAgent("0x123...")constclearedAgent=awaitclient.accounts.removeAgent("0x123...")// Error handlingtry{awaitclient.collections.get("nonexistent")}catch(error){if(errorinstanceofOpenSeaAPIError){console.error(error.statusCode)// e.g. 404console.error(error.responseBody)// raw API responseconsole.error(error.path)// request path}}

Full SDK reference: docs/sdk.md

Output Formats

JSON (default) - structured output for agents and scripts:

opensea collections get mfers

Table - human-readable output:

opensea --format table collections list --limit 5

TOON - Token-Oriented Object Notation, a compact format that uses ~40% fewer tokens than JSON. Ideal for piping output into LLM / AI agent context windows:

opensea --format toon tokens trending --limit 5

Example TOON output for a list of tokens:

tokens[3]{name,symbol,chain,market_cap,price_usd}:
Ethereum,ETH,ethereum,250000000000,2100.50
Bitcoin,BTC,bitcoin,900000000000,48000.00
Solana,SOL,solana,30000000000,95.25
next: abc123

TOON collapses uniform arrays of objects into CSV-like tables with a single header row, while nested objects use YAML-like indentation. The encoding is performed server-side via the Accept: text/markdown header — no client-side encoder is needed.

Exit Codes

• 0 - Success
• 1 - API error (non-429)
• 2 - Authentication error
• 3 - Rate limited (HTTP 429)

Requirements

• Node.js >= 18.0.0
• OpenSea API key — get one instantly: curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key' or from opensea.io/settings/developer

Development

npm install # Install dependencies
npm run build # Build CLI + SDK
npm run dev # Build in watch mode
npm run test# Run tests
npm run lint # Lint with Biome
npm run format # Format with Biome
npm run type-check # TypeScript type checking

Docs

Document	Description
CLI Reference	Full command reference with all options and flags
Examples	Real-world usage examples for every command
SDK Reference	Full programmatic SDK API with all methods
Pagination	Cursor-based pagination patterns for CLI and SDK
Event Types	Event type values and filtering

Contributing

This repository is a read-only mirror synced from an internal monorepo. We can't merge pull requests directly, but we review every one — if your fix or idea is solid, we'll recreate it internally and it will ship in the next release.

Issues and bug reports are the best way to contribute. See CONTRIBUTING.md for details.

License

MIT