From 7557860c918d06aeba2f9c3f6e4a19d80e81d29c Mon Sep 17 00:00:00 2001 From: unknown <> Date: Wed, 25 Feb 2026 19:14:42 +0000 Subject: [PATCH 1/2] docs: improve README and add docs/ folder with SDK, pagination, and events references Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- README.md | 105 +++++++++++++++++----- docs/events.md | 41 +++++++++ docs/pagination.md | 72 ++++++++++++++++ docs/sdk.md | 211 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 409 insertions(+), 20 deletions(-) create mode 100644 docs/events.md create mode 100644 docs/pagination.md create mode 100644 docs/sdk.md diff --git a/README.md b/README.md index 8812148..ba46879 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ Query the OpenSea API from the command line or programmatically. Designed for bo - [Examples](#examples) - [Exit Codes](#exit-codes) - [Requirements](#requirements) +- [Development](#development) ## Install @@ -66,25 +67,27 @@ Get an API key at [docs.opensea.io](https://docs.opensea.io/reference/api-keys). --api-key OpenSea API key (or set OPENSEA_API_KEY env var) --chain Default chain (default: ethereum) --format Output format: json or table (default: json) ---base-url API base URL override +--base-url API base URL override (for testing against staging or proxies) ``` ### Collections ```bash opensea collections get -opensea collections list [--chain ] [--order-by ] [--limit ] +opensea collections list [--chain ] [--order-by ] [--creator ] [--include-hidden] [--limit ] [--next ] opensea collections stats opensea collections traits ``` +`--order-by` values: `created_date`, `one_day_change`, `seven_day_volume`, `seven_day_change`, `num_owners`, `market_cap` + ### NFTs ```bash opensea nfts get -opensea nfts list-by-collection [--limit ] -opensea nfts list-by-contract [--limit ] -opensea nfts list-by-account
[--limit ] +opensea nfts list-by-collection [--limit ] [--next ] +opensea nfts list-by-contract [--limit ] [--next ] +opensea nfts list-by-account
[--limit ] [--next ] opensea nfts refresh opensea nfts contract
``` @@ -92,29 +95,31 @@ opensea nfts contract
### Listings ```bash -opensea listings all [--limit ] -opensea listings best [--limit ] +opensea listings all [--limit ] [--next ] +opensea listings best [--limit ] [--next ] opensea listings best-for-nft ``` ### Offers ```bash -opensea offers all [--limit ] -opensea offers collection [--limit ] +opensea offers all [--limit ] [--next ] +opensea offers collection [--limit ] [--next ] opensea offers best-for-nft -opensea offers traits --type --value +opensea offers traits --type --value [--limit ] [--next ] ``` ### Events ```bash -opensea events list [--event-type ] [--chain ] [--limit ] -opensea events by-account
[--event-type ] -opensea events by-collection [--event-type ] -opensea events by-nft [--event-type ] +opensea events list [--event-type ] [--after ] [--before ] [--chain ] [--limit ] [--next ] +opensea events by-account
[--event-type ] [--chain ] [--limit ] [--next ] +opensea events by-collection [--event-type ] [--limit ] [--next ] +opensea events by-nft [--event-type ] [--limit ] [--next ] ``` +Event types: `sale`, `transfer`, `mint`, `listing`, `offer`, `trait_offer`, `collection_offer` ([details](docs/events.md)) + ### Search ```bash @@ -144,24 +149,72 @@ opensea swaps quote --from-chain --from-address
--to-chain ``` +> All list commands support cursor-based pagination. See [docs/pagination.md](docs/pagination.md) for details. + ## 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 }) +// Collections 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 }) + +// NFTs +const { nfts } = await client.nfts.listByCollection("mfers", { limit: 5 }) + +// Listings & Offers +const { listings } = await client.listings.best("mfers", { limit: 10 }) +const { offers } = await client.offers.collection("mfers", { limit: 10 }) + +// Events +const { asset_events } = await client.events.byCollection("mfers", { + eventType: "sale", +}) + +// Tokens +const { tokens } = await client.tokens.trending({ chains: ["base"], limit: 5 }) +const tokenDetails = await client.tokens.get("base", "0x123...") + +// Search +const collections = await client.search.collections("mfers", { limit: 5 }) +const nftResults = await client.search.nfts("cool cat", { limit: 5 }) +const tokenResults = await client.search.tokens("usdc", { chain: "base" }) +const accounts = await client.search.accounts("vitalik", { limit: 5 }) + +// Swaps +const { quote, transactions } = await client.swaps.quote({ + fromChain: "base", + fromAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", + toChain: "base", + toAddress: "0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2", + quantity: "1000000", + address: "0x21130e908bba2d41b63fbca7caa131285b8724f8", +}) + +// Accounts +const account = await client.accounts.get( + "0x21130e908bba2d41b63fbca7caa131285b8724f8", +) + +// 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 JSON (default) - structured output for agents and scripts: @@ -333,6 +386,18 @@ 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 +``` + [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 diff --git a/docs/events.md b/docs/events.md new file mode 100644 index 0000000..2558305 --- /dev/null +++ b/docs/events.md @@ -0,0 +1,41 @@ +# Event Types + +The `events` commands accept an `--event-type` flag to filter by event type. + +## Valid event types + +| Type | Description | +|---|---| +| `sale` | NFT sold | +| `transfer` | NFT transferred between wallets | +| `mint` | NFT minted | +| `listing` | NFT listed for sale | +| `offer` | Offer made on an NFT | +| `trait_offer` | Offer made on NFTs with a specific trait | +| `collection_offer` | Offer made on any NFT in a collection | + +## CLI usage + +```bash +# Filter by event type +opensea events list --event-type sale --limit 5 + +# Combine with other filters +opensea events by-collection mfers --event-type transfer --limit 10 +opensea events by-account 0x123... --event-type mint --chain ethereum +opensea events by-nft ethereum 0x123... 1 --event-type listing + +# Time-based filtering (events list only) +opensea events list --event-type sale --after 1700000000 --before 1700100000 +``` + +## SDK usage + +```typescript +const { asset_events } = await client.events.byCollection("mfers", { + eventType: "sale", + limit: 10, +}) +``` + +Note: The CLI uses `--event-type` (kebab-case) while the SDK uses `eventType` (camelCase). diff --git a/docs/pagination.md b/docs/pagination.md new file mode 100644 index 0000000..cf8d71d --- /dev/null +++ b/docs/pagination.md @@ -0,0 +1,72 @@ +# Pagination + +The OpenSea API uses cursor-based pagination. Paginated responses include a `next` field containing an opaque cursor string. Pass this cursor back to fetch the next page. + +## CLI + +Most list commands support `--next ` (or `--cursor ` for tokens): + +```bash +# First page +opensea collections list --limit 5 + +# The response includes a "next" cursor — pass it to get the next page +opensea collections list --limit 5 --next "LXBrPTEwMDA..." + +# Tokens use --cursor instead of --next +opensea tokens trending --limit 5 +opensea tokens trending --limit 5 --cursor "abc123..." +``` + +### Commands that support pagination + +| Command | Cursor flag | +|---|---| +| `collections list` | `--next` | +| `nfts list-by-collection` | `--next` | +| `nfts list-by-contract` | `--next` | +| `nfts list-by-account` | `--next` | +| `listings all` | `--next` | +| `listings best` | `--next` | +| `offers all` | `--next` | +| `offers collection` | `--next` | +| `offers traits` | `--next` | +| `events list` | `--next` | +| `events by-account` | `--next` | +| `events by-collection` | `--next` | +| `events by-nft` | `--next` | +| `tokens trending` | `--cursor` | +| `tokens top` | `--cursor` | + +## SDK + +SDK methods return a `next` cursor in the response object: + +```typescript +const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY }) + +// First page +const page1 = await client.collections.list({ limit: 5 }) +console.log(page1.collections) + +// Next page +if (page1.next) { + const page2 = await client.collections.list({ limit: 5, next: page1.next }) +} +``` + +### Iterating through all pages + +```typescript +let cursor: string | undefined +do { + const result = await client.nfts.listByCollection("mfers", { + limit: 50, + next: cursor, + }) + for (const nft of result.nfts) { + // process each NFT + } + cursor = result.next +} while (cursor) +``` diff --git a/docs/sdk.md b/docs/sdk.md new file mode 100644 index 0000000..f50c151 --- /dev/null +++ b/docs/sdk.md @@ -0,0 +1,211 @@ +# SDK Reference + +The `@opensea/cli` package exports a programmatic SDK for use in TypeScript/JavaScript applications. + +## Setup + +```typescript +import { OpenSeaCLI } from "@opensea/cli" + +const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY }) +``` + +### Configuration + +| Option | Type | Default | Description | +|---|---|---|---| +| `apiKey` | `string` | *required* | OpenSea API key | +| `baseUrl` | `string` | `https://api.opensea.io` | API base URL override | +| `graphqlUrl` | `string` | `https://gql.opensea.io/graphql` | GraphQL URL override | +| `chain` | `string` | `"ethereum"` | Default chain | + +## Collections + +```typescript +const collection = await client.collections.get("mfers") + +const { collections, next } = await client.collections.list({ + chain: "ethereum", + limit: 10, + orderBy: "seven_day_volume", + creatorUsername: "some-user", + includeHidden: false, + next: "cursor_string", +}) + +const stats = await client.collections.stats("mfers") + +const traits = await client.collections.traits("mfers") +``` + +## NFTs + +```typescript +const { nft } = await client.nfts.get("ethereum", "0x123...", "1") + +const { nfts, next } = await client.nfts.listByCollection("mfers", { + limit: 10, + next: "cursor_string", +}) + +const { nfts, next } = await client.nfts.listByContract("ethereum", "0x123...", { + limit: 10, +}) + +const { nfts, next } = await client.nfts.listByAccount("ethereum", "0x123...", { + limit: 10, +}) + +await client.nfts.refresh("ethereum", "0x123...", "1") + +const contract = await client.nfts.getContract("ethereum", "0x123...") +``` + +## Listings + +```typescript +const { listings, next } = await client.listings.all("mfers", { limit: 10 }) + +const { listings, next } = await client.listings.best("mfers", { limit: 10 }) + +const listing = await client.listings.bestForNFT("mfers", "3490") +``` + +## Offers + +```typescript +const { offers, next } = await client.offers.all("mfers", { limit: 10 }) + +const { offers, next } = await client.offers.collection("mfers", { limit: 10 }) + +const offer = await client.offers.bestForNFT("mfers", "1") + +const { offers, next } = await client.offers.traits("mfers", { + type: "background", + value: "blue", + limit: 10, +}) +``` + +## Events + +```typescript +const { asset_events, next } = await client.events.list({ + eventType: "sale", + chain: "ethereum", + after: 1700000000, + before: 1700100000, + limit: 10, +}) + +const { asset_events, next } = await client.events.byAccount("0x123...", { + eventType: "transfer", + chain: "ethereum", + limit: 10, +}) + +const { asset_events, next } = await client.events.byCollection("mfers", { + eventType: "sale", + limit: 10, +}) + +const { asset_events, next } = await client.events.byNFT( + "ethereum", + "0x123...", + "1", + { eventType: "sale", limit: 10 }, +) +``` + +## Accounts + +```typescript +const account = await client.accounts.get("0x123...") +``` + +## Tokens + +```typescript +const { tokens, next } = await client.tokens.trending({ + chains: ["base", "ethereum"], + limit: 10, + cursor: "cursor_string", +}) + +const { tokens, next } = await client.tokens.top({ + chains: ["base"], + limit: 10, +}) + +const tokenDetails = await client.tokens.get("base", "0x123...") +``` + +## Search + +Search methods use GraphQL and return different result shapes than the REST API. + +```typescript +const collections = await client.search.collections("mfers", { + chains: ["ethereum"], + limit: 5, +}) + +const nfts = await client.search.nfts("cool cat", { + collection: "cool-cats-nft", + chains: ["ethereum"], + limit: 5, +}) + +const tokens = await client.search.tokens("usdc", { + chain: "base", + limit: 5, +}) + +const accounts = await client.search.accounts("vitalik", { limit: 5 }) +``` + +## Swaps + +```typescript +const { quote, transactions } = await client.swaps.quote({ + fromChain: "base", + fromAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", + toChain: "base", + toAddress: "0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2", + quantity: "1000000", + address: "0x21130e908bba2d41b63fbca7caa131285b8724f8", + slippage: 0.01, + recipient: "0x...", +}) +``` + +## Error Handling + +All API errors throw `OpenSeaAPIError` with structured fields: + +```typescript +import { OpenSeaCLI, OpenSeaAPIError } from "@opensea/cli" + +const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY }) + +try { + const collection = await client.collections.get("nonexistent") +} catch (error) { + if (error instanceof OpenSeaAPIError) { + console.error(error.statusCode) // e.g. 404 + console.error(error.responseBody) // raw response body + console.error(error.path) // e.g. "/api/v2/collections/nonexistent" + } +} +``` + +## Exports + +The package exports: + +| Export | Description | +|---|---| +| `OpenSeaCLI` | Main SDK class with all API domain methods | +| `OpenSeaClient` | Low-level HTTP client (for advanced usage) | +| `OpenSeaAPIError` | Error class thrown on API failures | +| All types from `types/api.ts` | TypeScript interfaces for all API responses | From 1dba121a29310b44ee65eb9de1d2fa10c566af97 Mon Sep 17 00:00:00 2001 From: unknown <> Date: Wed, 25 Feb 2026 19:18:46 +0000 Subject: [PATCH 2/2] docs: slim down README, move detailed reference and examples to docs/ Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- README.md | 314 ++++++------------------------------------ docs/cli-reference.md | 93 +++++++++++++ docs/examples.md | 145 +++++++++++++++++++ 3 files changed, 281 insertions(+), 271 deletions(-) create mode 100644 docs/cli-reference.md create mode 100644 docs/examples.md diff --git a/README.md b/README.md index ba46879..0ded891 100644 --- a/README.md +++ b/README.md @@ -15,23 +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 @@ -59,147 +50,64 @@ 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 OpenSea API key (or set OPENSEA_API_KEY env var) ---chain Default chain (default: ethereum) ---format Output format: json or table (default: json) ---base-url API base URL override (for testing against staging or proxies) -``` - -### Collections - -```bash -opensea collections get -opensea collections list [--chain ] [--order-by ] [--creator ] [--include-hidden] [--limit ] [--next ] -opensea collections stats -opensea collections traits -``` - -`--order-by` values: `created_date`, `one_day_change`, `seven_day_volume`, `seven_day_change`, `num_owners`, `market_cap` - -### NFTs +## Quick Start ```bash -opensea nfts get -opensea nfts list-by-collection [--limit ] [--next ] -opensea nfts list-by-contract [--limit ] [--next ] -opensea nfts list-by-account
[--limit ] [--next ] -opensea nfts refresh -opensea nfts contract
-``` +# Get collection details +opensea collections get mfers -### Listings +# Get floor price and volume stats +opensea collections stats mfers -```bash -opensea listings all [--limit ] [--next ] -opensea listings best [--limit ] [--next ] -opensea listings best-for-nft -``` +# List NFTs in a collection +opensea nfts list-by-collection mfers --limit 5 -### Offers +# Get best listings +opensea listings best mfers --limit 5 -```bash -opensea offers all [--limit ] [--next ] -opensea offers collection [--limit ] [--next ] -opensea offers best-for-nft -opensea offers traits --type --value [--limit ] [--next ] -``` +# Search across OpenSea +opensea search collections "cool cats" -### Events +# Get trending tokens +opensea tokens trending --limit 5 -```bash -opensea events list [--event-type ] [--after ] [--before ] [--chain ] [--limit ] [--next ] -opensea events by-account
[--event-type ] [--chain ] [--limit ] [--next ] -opensea events by-collection [--event-type ] [--limit ] [--next ] -opensea events by-nft [--event-type ] [--limit ] [--next ] +# Human-readable table output +opensea --format table collections stats mfers ``` -Event types: `sale`, `transfer`, `mint`, `listing`, `offer`, `trait_offer`, `collection_offer` ([details](docs/events.md)) - -### Search +## Commands -```bash -opensea search collections [--chains ] [--limit ] -opensea search nfts [--collection ] [--chains ] [--limit ] -opensea search tokens [--chain ] [--limit ] -opensea search accounts [--limit ] -``` +| 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 | -### Tokens +Global options: `--api-key`, `--chain` (default: ethereum), `--format` (json/table), `--base-url` -```bash -opensea tokens trending [--chains ] [--limit ] [--cursor ] -opensea tokens top [--chains ] [--limit ] [--cursor ] -opensea tokens get
-``` - -### Swaps - -```bash -opensea swaps quote --from-chain --from-address
--to-chain --to-address
--quantity --address
[--slippage ] [--recipient ] -``` - -### Accounts - -```bash -opensea accounts get
-``` - -> All list commands support cursor-based pagination. See [docs/pagination.md](docs/pagination.md) for details. +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, OpenSeaAPIError } from "@opensea/cli" const client = new OpenSeaCLI({ apiKey: process.env.OPENSEA_API_KEY }) -// Collections const collection = await client.collections.get("mfers") -const stats = await client.collections.stats("mfers") - -// NFTs const { nfts } = await client.nfts.listByCollection("mfers", { limit: 5 }) - -// Listings & Offers const { listings } = await client.listings.best("mfers", { limit: 10 }) -const { offers } = await client.offers.collection("mfers", { limit: 10 }) - -// Events const { asset_events } = await client.events.byCollection("mfers", { eventType: "sale", }) - -// Tokens const { tokens } = await client.tokens.trending({ chains: ["base"], limit: 5 }) -const tokenDetails = await client.tokens.get("base", "0x123...") - -// Search -const collections = await client.search.collections("mfers", { limit: 5 }) -const nftResults = await client.search.nfts("cool cat", { limit: 5 }) -const tokenResults = await client.search.tokens("usdc", { chain: "base" }) -const accounts = await client.search.accounts("vitalik", { limit: 5 }) - -// Swaps -const { quote, transactions } = await client.swaps.quote({ - fromChain: "base", - fromAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", - toChain: "base", - toAddress: "0x3ec2156d4c0a9cbdab4a016633b7bcf6a8d68ea2", - quantity: "1000000", - address: "0x21130e908bba2d41b63fbca7caa131285b8724f8", -}) - -// Accounts -const account = await client.accounts.get( - "0x21130e908bba2d41b63fbca7caa131285b8724f8", -) +const results = await client.search.collections("mfers", { limit: 5 }) // Error handling try { @@ -229,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 @@ -398,6 +160,16 @@ 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 diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..5fa5d41 --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,93 @@ +# CLI Reference + +Full command reference for all `opensea` CLI commands. + +## Global Options + +``` +--api-key OpenSea API key (or set OPENSEA_API_KEY env var) +--chain Default chain (default: ethereum) +--format Output format: json or table (default: json) +--base-url API base URL override (for testing against staging or proxies) +``` + +## Collections + +```bash +opensea collections get +opensea collections list [--chain ] [--order-by ] [--creator ] [--include-hidden] [--limit ] [--next ] +opensea collections stats +opensea collections traits +``` + +`--order-by` values: `created_date`, `one_day_change`, `seven_day_volume`, `seven_day_change`, `num_owners`, `market_cap` + +## NFTs + +```bash +opensea nfts get +opensea nfts list-by-collection [--limit ] [--next ] +opensea nfts list-by-contract [--limit ] [--next ] +opensea nfts list-by-account
[--limit ] [--next ] +opensea nfts refresh +opensea nfts contract
+``` + +## Listings + +```bash +opensea listings all [--limit ] [--next ] +opensea listings best [--limit ] [--next ] +opensea listings best-for-nft +``` + +## Offers + +```bash +opensea offers all [--limit ] [--next ] +opensea offers collection [--limit ] [--next ] +opensea offers best-for-nft +opensea offers traits --type --value [--limit ] [--next ] +``` + +## Events + +```bash +opensea events list [--event-type ] [--after ] [--before ] [--chain ] [--limit ] [--next ] +opensea events by-account
[--event-type ] [--chain ] [--limit ] [--next ] +opensea events by-collection [--event-type ] [--limit ] [--next ] +opensea events by-nft [--event-type ] [--limit ] [--next ] +``` + +Event types: `sale`, `transfer`, `mint`, `listing`, `offer`, `trait_offer`, `collection_offer` ([details](events.md)) + +## Search + +```bash +opensea search collections [--chains ] [--limit ] +opensea search nfts [--collection ] [--chains ] [--limit ] +opensea search tokens [--chain ] [--limit ] +opensea search accounts [--limit ] +``` + +## Tokens + +```bash +opensea tokens trending [--chains ] [--limit ] [--cursor ] +opensea tokens top [--chains ] [--limit ] [--cursor ] +opensea tokens get
+``` + +## Swaps + +```bash +opensea swaps quote --from-chain --from-address
--to-chain --to-address
--quantity --address
[--slippage ] [--recipient ] +``` + +## Accounts + +```bash +opensea accounts get
+``` + +> All list commands support cursor-based pagination. See [pagination.md](pagination.md) for details. diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..72710c4 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,145 @@ +# Examples + +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 +```