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 |