GitHub - ProjectOpenSea/opensea-cli: Query the OpenSea API from the command line or programmatically

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

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 (non-429)
2 - Authentication error
3 - Rate limited (HTTP 429)

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

Table of Contents