Standardize pagination with next cursor (#27)

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

Author: ryanio

docs/cli-reference.md

@@ -73,8 +73,8 @@ opensea search accounts <query> [--limit <n>]
 ## Tokens
 
 ```bash
-opensea tokens trending [--chains <chains>] [--limit <n>] [--cursor <cursor>]
-opensea tokens top [--chains <chains>] [--limit <n>] [--cursor <cursor>]
+opensea tokens trending [--chains <chains>] [--limit <n>] [--next <cursor>]
+opensea tokens top [--chains <chains>] [--limit <n>] [--next <cursor>]
 opensea tokens get <chain> <address>
 ```
 
@@ -90,4 +90,4 @@ opensea swaps quote --from-chain <chain> --from-address <address> --to-chain <ch
 opensea accounts get <address>
 ```
 
-> All list commands support cursor-based pagination. See [pagination.md](pagination.md) for details.
+> REST list commands support cursor-based pagination. Search commands return a flat list with no cursor. See [pagination.md](pagination.md) for details.

docs/pagination.md

@@ -4,7 +4,7 @@ The OpenSea API uses cursor-based pagination. Paginated responses include a `nex
 
 ## CLI
 
-Most list commands support `--next <cursor>` (or `--cursor <cursor>` for tokens):
+All paginated commands use `--next <cursor>`:
 
 ```bash
 # First page
@@ -13,16 +13,17 @@ 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
+# Tokens also use --next
 opensea tokens trending --limit 5
-opensea tokens trending --limit 5 --cursor "abc123..."
+opensea tokens trending --limit 5 --next "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` |
@@ -35,8 +36,10 @@ opensea tokens trending --limit 5 --cursor "abc123..."
 | `events by-account` | `--next` |
 | `events by-collection` | `--next` |
 | `events by-nft` | `--next` |
-| `tokens trending` | `--cursor` |
-| `tokens top` | `--cursor` |
+| `tokens trending` | `--next` |
+| `tokens top` | `--next` |
+
+> **Note:** Search commands (`search collections`, `search nfts`, `search tokens`, `search accounts`) do not support cursor-based pagination. The underlying GraphQL API returns a flat list with no `next` cursor.
 
 ## SDK
 

docs/sdk.md

@@ -129,7 +129,7 @@ const account = await client.accounts.get("0x123...")
 const { tokens, next } = await client.tokens.trending({
   chains: ["base", "ethereum"],
   limit: 10,
-  cursor: "cursor_string",
+  next: "cursor_string",
 })
 
 const { tokens, next } = await client.tokens.top({
@@ -142,7 +142,7 @@ const tokenDetails = await client.tokens.get("base", "0x123...")
 
 ## Search
 
-Search methods use GraphQL and return different result shapes than the REST API.
+Search methods use GraphQL and return different result shapes than the REST API. Search endpoints do not currently expose a `next` cursor for pagination; use `limit` to control result count.
 
 ```typescript
 const collections = await client.search.collections("mfers", {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",

package.json

@@ -16,16 +16,16 @@ export function tokensCommand(
     .description("Get trending tokens based on OpenSea's trending score")
     .option("--chains <chains>", "Comma-separated list of chains to filter by")
     .option("--limit <limit>", "Number of results (max 100)", "20")
-    .option("--cursor <cursor>", "Pagination cursor")
+    .option("--next <cursor>", "Pagination cursor")
     .action(
-      async (options: { chains?: string; limit: string; cursor?: string }) => {
+      async (options: { chains?: string; limit: string; next?: string }) => {
         const client = getClient()
         const result = await client.get<{ tokens: Token[]; next?: string }>(
           "/api/v2/tokens/trending",
           {
             chains: options.chains,
             limit: Number.parseInt(options.limit, 10),
-            cursor: options.cursor,
+            cursor: options.next,
           },
         )
         console.log(formatOutput(result, getFormat()))
@@ -37,16 +37,16 @@ export function tokensCommand(
     .description("Get top tokens ranked by 24-hour trading volume")
     .option("--chains <chains>", "Comma-separated list of chains to filter by")
     .option("--limit <limit>", "Number of results (max 100)", "20")
-    .option("--cursor <cursor>", "Pagination cursor")
+    .option("--next <cursor>", "Pagination cursor")
     .action(
-      async (options: { chains?: string; limit: string; cursor?: string }) => {
+      async (options: { chains?: string; limit: string; next?: string }) => {
         const client = getClient()
         const result = await client.get<{ tokens: Token[]; next?: string }>(
           "/api/v2/tokens/top",
           {
             chains: options.chains,
             limit: Number.parseInt(options.limit, 10),
-            cursor: options.cursor,
+            cursor: options.next,
           },
         )
         console.log(formatOutput(result, getFormat()))

src/commands/tokens.ts

@@ -317,24 +317,24 @@ class TokensAPI {
   async trending(options?: {
     limit?: number
     chains?: string[]
-    cursor?: string
+    next?: string
   }): Promise<{ tokens: Token[]; next?: string }> {
     return this.client.get("/api/v2/tokens/trending", {
       limit: options?.limit,
       chains: options?.chains?.join(","),
-      cursor: options?.cursor,
+      cursor: options?.next,
     })
   }
 
   async top(options?: {
     limit?: number
     chains?: string[]
-    cursor?: string
+    next?: string
   }): Promise<{ tokens: Token[]; next?: string }> {
     return this.client.get("/api/v2/tokens/top", {
       limit: options?.limit,
       chains: options?.chains?.join(","),
-      cursor: options?.cursor,
+      cursor: options?.next,
     })
   }
 

src/sdk.ts

@@ -250,11 +250,6 @@ export interface GetTraitsResponse {
   counts: { [traitType: string]: TraitCounts }
 }
 
-export interface PaginatedResponse<T> {
-  next?: string
-  results: T[]
-}
-
 export interface Token {
   address: string
   chain: string

src/types/api.ts

@@ -27,7 +27,15 @@ describe("tokensCommand", () => {
 
     const cmd = tokensCommand(ctx.getClient, ctx.getFormat)
     await cmd.parseAsync(
-      ["trending", "--chains", "ethereum,base", "--limit", "10"],
+      [
+        "trending",
+        "--chains",
+        "ethereum,base",
+        "--limit",
+        "10",
+        "--next",
+        "abc123",
+      ],
       { from: "user" },
     )
 
@@ -36,6 +44,7 @@ describe("tokensCommand", () => {
       expect.objectContaining({
         chains: "ethereum,base",
         limit: 10,
+        cursor: "abc123",
       }),
     )
   })
@@ -44,11 +53,13 @@ describe("tokensCommand", () => {
     ctx.mockClient.get.mockResolvedValue({ tokens: [] })
 
     const cmd = tokensCommand(ctx.getClient, ctx.getFormat)
-    await cmd.parseAsync(["top", "--limit", "5"], { from: "user" })
+    await cmd.parseAsync(["top", "--limit", "5", "--next", "cursor1"], {
+      from: "user",
+    })
 
     expect(ctx.mockClient.get).toHaveBeenCalledWith(
       "/api/v2/tokens/top",
-      expect.objectContaining({ limit: 5 }),
+      expect.objectContaining({ limit: 5, cursor: "cursor1" }),
     )
   })
 

test/commands/tokens.test.ts

@@ -294,6 +294,16 @@ describe("OpenSeaCLI", () => {
       })
     })
 
+    it("trending maps next option to cursor param", async () => {
+      mockGet.mockResolvedValue({ tokens: [] })
+      await sdk.tokens.trending({ next: "cursor1" })
+      expect(mockGet).toHaveBeenCalledWith("/api/v2/tokens/trending", {
+        limit: undefined,
+        chains: undefined,
+        cursor: "cursor1",
+      })
+    })
+
     it("trending with no options", async () => {
       mockGet.mockResolvedValue({ tokens: [] })
       await sdk.tokens.trending()
@@ -304,6 +314,16 @@ describe("OpenSeaCLI", () => {
       })
     })
 
+    it("top maps next option to cursor param", async () => {
+      mockGet.mockResolvedValue({ tokens: [] })
+      await sdk.tokens.top({ limit: 5, next: "cursor2" })
+      expect(mockGet).toHaveBeenCalledWith("/api/v2/tokens/top", {
+        limit: 5,
+        chains: undefined,
+        cursor: "cursor2",
+      })
+    })
+
     it("top calls correct endpoint", async () => {
       mockGet.mockResolvedValue({ tokens: [] })
       await sdk.tokens.top({ limit: 5 })