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:

export OPENSEA_API_KEY=your-api-key
opensea collections get mfers

# or pass inline
opensea --api-key your-api-key collections get mfers

Get an API key at docs.opensea.io.

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

# 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
events	List marketplace events (sales, transfers, mints, etc.)
search	Search collections, NFTs, tokens, and accounts
tokens	Get trending tokens, top tokens, and token details
swaps	Get swap quotes for token trading
accounts	Get account details

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

Full command reference with all options and flags: docs/cli-reference.md

Programmatic SDK

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 { asset_events } = await client.events.byCollection("mfers", {
  eventType: "sale",
})
const { tokens } = await client.tokens.trending({ chains: ["base"], limit: 5 })
const results = await client.search.collections("mfers", { limit: 5 })

// 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 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 encoder follows the TOON v3.0 spec and is implemented without external dependencies.

TOON is also available programmatically via the SDK:

import { formatToon } from "@opensea/cli"

const data = await client.tokens.trending({ limit: 5 })
console.log(formatToon(data))

Exit Codes

• 0 - Success
• 1 - API error
• 2 - Authentication error

Requirements

• Node.js >= 18.0.0
• OpenSea API key (get one here)

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