docs: improve README and add docs/ folder with SDK, pagination, and events references (#26)

* 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>

* 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>

---------

Co-authored-by: unknown <>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: ryanio

README.md

@@ -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
 
@@ -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
 
@@ -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
@@ -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