Query the OpenSea API from your terminal or from TypeScript. Output defaults to JSON for scripts and agents, with table and TOON formats available.
- Install
- Authentication
- Quick start
- Commands
- Programmatic SDK
- Output formats
- Exit codes
- Development
- Docs
Requires Node.js 18 or newer.
npm install -g @opensea/cli
Or run it without installing:
npx @opensea/cli collections get mfers
API commands need a key. The CLI reads it from --api-key, then OPENSEA_API_KEY, then the key saved in ~/.opensea/api_key.
# Get an instant free-tier API key (no signup needed) and save it to ~/.opensea/api_key opensea auth request-key --save --if-missing # no-op when a key is already set or saved opensea collections get mfers # or set it in the environment, which takes precedence over the saved key export OPENSEA_API_KEY=your-api-key # or pass inline opensea --api-key your-api-key collections get mfers
auth request-key returns a free-tier key with no signup. For higher rate limits, create a key at opensea.io/settings/developer. See the API key docs.
Wallet-authenticated endpoints also need a scoped token:
export OPENSEA_PRIVATE_KEY="..." opensea login --private-key --scopes read:favorites,read:wallets,write:wallets WALLET=$(opensea --format json whoami | jq -r '.address') opensea api request GET "/api/v2/account/$WALLET/favorites" --params '{"limit":1}' opensea agent declare opensea agent list opensea auth revoke
login --private-key signs in with SIWE and requires an explicit --scopes list. The key signs locally and is never stored. Run opensea login without --private-key to log in interactively. See the wallet-auth guide.
The CLI stores the session it needs to revoke the personal access token (PAT), and api request sends the stored wallet JWT along with OPENSEA_API_KEY.
When the stored JWT has expired, or a request with it returns 401, the CLI refreshes it once, prints a one-line notice to stderr, and continues. This only happens against OpenSea's own servers, not with --base-url or --auth-base-url. Turn it off with --no-auth-refresh, or refresh on demand with opensea auth refresh. If the refresh token itself is rejected, the error names the login command to run.
# 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 "cool cats" --types collection # 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
| Command | Description |
|---|---|
collections |
Get, list, stats, and traits for NFT collections; manage a collection page, its pricing currency and creator fee enforcement |
nfts |
Get, list, refresh metadata, and contract details for NFTs |
listings |
Query listings and create listing or fulfillment actions |
offers |
Query offers and create offer or fulfillment actions |
orders |
Cancel orders offchain or create onchain cancellation actions |
drops |
Query drops, build same-chain or cross-chain mint transactions, deploy a drop contract, publish or unpublish a drop, and upload its files |
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 |
signals |
Read public signals about a currency, NFT or collection, and post or delete your own |
accounts |
Get account details |
agent |
Declare an agent account and run the ownership handshake |
whoami |
Show the current wallet, the wallets its token covers, scopes, and scope source |
api request |
Call any API v2 endpoint with the active API key and wallet JWT |
Run opensea --help for the current list, and see docs/cli-reference.md for every option.
Global options include --api-key, --chain (default ethereum), --format (json, table or toon), --base-url, --fields, --max-lines, --timeout, --max-retries, --no-retry and --verbose. A --chain you pass, before or after the subcommand, reaches subcommands that accept --chain. The ethereum default never does.
import { OpenSeaCLI, OpenSeaAPIError } from "@opensea/cli" const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY }) const collection = await client.collections.get("mfers") const { nfts } = await client.nfts.listByCollection("mfers", { limit: 5 }) const { listings } = await client.listings.best("mfers", { limit: 10 }) const fulfillment = await client.listings.fulfillmentActions({ listing: { hash: "<svm_order.id>", chain: "solana", protocol_address: "<protocol address>", }, fulfiller: { address: "<buyer address>" }, include_optional_creator_fees: false, }) const { asset_events } = await client.events.byCollection("mfers", { eventType: "sale", }) const { tokens } = await client.tokens.trending({ chains: ["base"], limit: 5 }) const activity = await client.tokens.activityStats( "base", "0x4200000000000000000000000000000000000006", { windows: ["1h", "24h"] }, ) const results = await client.search.query("mfers", { assetTypes: ["collection"], limit: 5, }) const declared = await client.agent.declare() const { relationships } = await client.agent.list() // Error handling try { await client.collections.get("nonexistent") } catch (error) { if (error instanceof OpenSeaAPIError) { console.error(error.statusCode) // e.g. 404 console.error(error.responseBody) // raw API response console.error(error.path) // request path } }
Full reference: docs/sdk.md.
JSON is the default:
opensea collections get mfers
Table output is easier to read:
opensea --format table collections list --limit 5
TOON (Token-Oriented Object Notation) uses about 40% fewer tokens than JSON, which helps when output goes into an LLM context window:
opensea --format toon tokens trending --limit 5
Uniform arrays of objects become CSV-like rows under one header, and nested objects use YAML-like indentation:
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
The API does the encoding (the CLI sends Accept: text/markdown), so there is no client-side encoder.
0: success1: API error other than 401 or 429, or any other failure such as a network error2: authentication error (missing API key, HTTP 401, or a rejected token refresh)3: rate limited (HTTP 429)
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
| Document | Description |
|---|---|
| CLI reference | Every command, option and flag |
| Examples | Usage examples for every command |
| SDK reference | Every method in the programmatic SDK |
| Pagination | Cursor-based pagination patterns for CLI and SDK |
| Event types | Event type values and filtering |
Read-only mirror of a private monorepo, updated on each release. Pull requests are welcome, and we bring accepted changes into the monorepo. See CONTRIBUTING.md for details.
Found a vulnerability? Report it through OpenSea's Bugcrowd program at https://bugcrowd.com/engagements/opensea rather than opening a public issue. See SECURITY.md.