Skip to content

docs: restructure README into concise overview with docs/ reference pages #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanio merged 2 commits into from
Feb 25, 2026
Merged

docs: restructure README into concise overview with docs/ reference pages #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7557860
docs: improve README and add docs/ folder with SDK, pagination, and e…
Feb 25, 2026
1dba121
docs: slim down README, move detailed reference and examples to docs/
Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
317 changes: 77 additions & 240 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,14 @@ Query the OpenSea API from the command line or programmatically. Designed for bo

- [Install](#install)
- [Authentication](#authentication)
- [CLI Usage](#cli-usage)
- [Global Options](#global-options)
- [Collections](#collections)
- [NFTs](#nfts)
- [Listings](#listings)
- [Offers](#offers)
- [Events](#events)
- [Search](#search)
- [Tokens](#tokens)
- [Swaps](#swaps)
- [Accounts](#accounts)
- [Quick Start](#quick-start)
- [Commands](#commands)
- [Programmatic SDK](#programmatic-sdk)
- [Output Formats](#output-formats)
- [Examples](#examples)
- [Exit Codes](#exit-codes)
- [Requirements](#requirements)
- [Development](#development)
- [Docs](#docs)

## Install

Expand Down Expand Up @@ -58,109 +50,78 @@ opensea --api-key your-api-key collections get mfers

Get an API key at [docs.opensea.io](https://docs.opensea.io/reference/api-keys).

## CLI Usage

### Global Options

```
--api-key <key> OpenSea API key (or set OPENSEA_API_KEY env var)
--chain <chain> Default chain (default: ethereum)
--format <format> Output format: json or table (default: json)
--base-url <url> API base URL override
```

### Collections

```bash
opensea collections get <slug>
opensea collections list [--chain <chain>] [--order-by <field>] [--limit <n>]
opensea collections stats <slug>
opensea collections traits <slug>
```

### NFTs
## Quick Start

```bash
opensea nfts get <chain> <contract> <token-id>
opensea nfts list-by-collection <slug> [--limit <n>]
opensea nfts list-by-contract <chain> <contract> [--limit <n>]
opensea nfts list-by-account <chain> <address> [--limit <n>]
opensea nfts refresh <chain> <contract> <token-id>
opensea nfts contract <chain> <address>
```

### Listings

```bash
opensea listings all <collection> [--limit <n>]
opensea listings best <collection> [--limit <n>]
opensea listings best-for-nft <collection> <token-id>
```
# Get collection details
opensea collections get mfers

### Offers
# Get floor price and volume stats
opensea collections stats mfers

```bash
opensea offers all <collection> [--limit <n>]
opensea offers collection <collection> [--limit <n>]
opensea offers best-for-nft <collection> <token-id>
opensea offers traits <collection> --type <type> --value <value>
```
# List NFTs in a collection
opensea nfts list-by-collection mfers --limit 5

### Events
# Get best listings
opensea listings best mfers --limit 5

```bash
opensea events list [--event-type <type>] [--chain <chain>] [--limit <n>]
opensea events by-account <address> [--event-type <type>]
opensea events by-collection <slug> [--event-type <type>]
opensea events by-nft <chain> <contract> <token-id> [--event-type <type>]
```
# Search across OpenSea
opensea search collections "cool cats"

### Search
# Get trending tokens
opensea tokens trending --limit 5

```bash
opensea search collections <query> [--chains <chains>] [--limit <n>]
opensea search nfts <query> [--collection <slug>] [--chains <chains>] [--limit <n>]
opensea search tokens <query> [--chain <chain>] [--limit <n>]
opensea search accounts <query> [--limit <n>]
# Human-readable table output
opensea --format table collections stats mfers
```

### Tokens
## Commands

```bash
opensea tokens trending [--chains <chains>] [--limit <n>] [--cursor <cursor>]
opensea tokens top [--chains <chains>] [--limit <n>] [--cursor <cursor>]
opensea tokens get <chain> <address>
```
| 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 |

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

```bash
opensea swaps quote --from-chain <chain> --from-address <address> --to-chain <chain> --to-address <address> --quantity <quantity> --address <address> [--slippage <slippage>] [--recipient <recipient>]
```

### Accounts

```bash
opensea accounts get <address>
```
Full command reference with all options and flags: [docs/cli-reference.md](docs/cli-reference.md)

## Programmatic SDK

Use as a TypeScript/JavaScript library:

```typescript
import { OpenSeaCLI } from "@opensea/cli"
import { OpenSeaCLI, OpenSeaAPIError } from "@opensea/cli"

const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY })

const collection = await client.collections.get("mfers")
const stats = await client.collections.stats("mfers")
const nfts = await client.nfts.listByCollection("mfers", { limit: 5 })
const listings = await client.listings.best("mfers", { limit: 10 })
const events = await client.events.byCollection("mfers", { eventType: "sale" })
const account = await client.accounts.get("0x21130e908bba2d41b63fbca7caa131285b8724f8")
const searchResults = await client.search.collections("mfers", { limit: 5 })
```
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](docs/sdk.md)

## Output Formats

Expand All @@ -176,152 +137,6 @@ Table - human-readable output:
opensea --format table collections list --limit 5
```

## Examples

Here are real-world examples using the [tiny dinos](https://opensea.io/collection/tiny-dinos-eth) and [mfers](https://opensea.io/collection/mfers) collections:

### Collections

```bash
# Get collection details
opensea collections get tiny-dinos-eth

# List collections with a limit
opensea collections list --limit 2

# Get collection stats (volume, floor price, etc.)
opensea collections stats tiny-dinos-eth

# Get collection traits
opensea collections traits tiny-dinos-eth
```

### NFTs

```bash
# Get a specific NFT by chain/contract/token-id
opensea nfts get ethereum 0xd9b78a2f1dafc8bb9c60961790d2beefebee56f4 1

# List NFTs in a collection
opensea nfts list-by-collection tiny-dinos-eth --limit 2

# List NFTs by contract address
opensea nfts list-by-contract ethereum 0xd9b78a2f1dafc8bb9c60961790d2beefebee56f4 --limit 2

# List NFTs owned by an account
opensea nfts list-by-account ethereum 0x21130e908bba2d41b63fbca7caa131285b8724f8 --limit 2

# Get contract details
opensea nfts contract ethereum 0xd9b78a2f1dafc8bb9c60961790d2beefebee56f4

# Refresh NFT metadata
opensea nfts refresh ethereum 0xd9b78a2f1dafc8bb9c60961790d2beefebee56f4 1
```

### Listings

```bash
# Get all listings for a collection
opensea listings all tiny-dinos-eth --limit 2

# Get best (cheapest) listings
opensea listings best tiny-dinos-eth --limit 2

# Get the best listing for a specific NFT
opensea listings best-for-nft mfers 3490
```

### Offers

```bash
# Get all offers for a collection
opensea offers all tiny-dinos-eth --limit 2

# Get collection offers
opensea offers collection tiny-dinos-eth --limit 2

# Get best offer for a specific NFT
opensea offers best-for-nft tiny-dinos-eth 1

# Get trait offers (type and value are required)
opensea offers traits tiny-dinos-eth --type background --value blue --limit 2
```

### Events

```bash
# List recent events across all collections
opensea events list --limit 2

# Get events for a collection
opensea events by-collection tiny-dinos-eth --limit 2

# Get events for a specific NFT
opensea events by-nft ethereum 0xd9b78a2f1dafc8bb9c60961790d2beefebee56f4 1 --limit 2

# Get events for an account
opensea events by-account 0x21130e908bba2d41b63fbca7caa131285b8724f8 --limit 2
```

### Search

```bash
# Search for collections
opensea search collections mfers

# Search for NFTs
opensea search nfts "cool cat" --limit 5

# Search for NFTs within a specific collection
opensea search nfts "rare" --collection tiny-dinos-eth --limit 5

# Search for tokens/currencies
opensea search tokens eth --limit 5

# Search for tokens on a specific chain
opensea search tokens usdc --chain base --limit 5

# Search for accounts
opensea search accounts vitalik --limit 5
```

### Tokens

```bash
# Get trending tokens
opensea tokens trending --limit 2

# Get trending tokens on a specific chain
opensea tokens trending --chains base --limit 2

# Get top tokens by 24-hour volume
opensea tokens top --limit 2

# Get top tokens on a specific chain
opensea tokens top --chains base --limit 2

# Get details for a specific token (DebtReliefBot on Base)
opensea tokens get base 0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2
```

### Swaps

```bash
# Get a swap quote for USDC to DRB on Base
opensea swaps quote \
--from-chain base --from-address 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 \
--to-chain base --to-address 0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2 \
--quantity 1000000 \
--address 0x21130e908bba2d41b63fbca7caa131285b8724f8
```

### Accounts

```bash
# Get account details
opensea accounts get 0x21130e908bba2d41b63fbca7caa131285b8724f8
```

## Exit Codes

- `0` - Success
Expand All @@ -333,6 +148,28 @@ opensea accounts get 0x21130e908bba2d41b63fbca7caa131285b8724f8
- Node.js >= 18.0.0
- OpenSea API key ([get one here](https://docs.opensea.io/reference/api-keys))

## Development

```bash
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](docs/cli-reference.md) | Full command reference with all options and flags |
| [Examples](docs/examples.md) | Real-world usage examples for every command |
| [SDK Reference](docs/sdk.md) | Full programmatic SDK API with all methods |
| [Pagination](docs/pagination.md) | Cursor-based pagination patterns for CLI and SDK |
| [Event Types](docs/events.md) | Event type values and filtering |

[version-badge]: https://img.shields.io/github/package-json/v/ProjectOpenSea/opensea-cli
[version-link]: https://github.com/ProjectOpenSea/opensea-cli/releases
[npm-badge]: https://img.shields.io/npm/v/@opensea/cli?color=red
Expand Down
Loading