Release v1.9.0

Origin-SHA: bbe72b6405aad02845d2b39d2706d893c4b165de

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,39 @@
 # @opensea/cli
 
+## 1.9.0
+
+### Minor Changes
+
+- 8fa9fb5: Expose the new `token/{chain}/{address}/holders` and `token/{chain}/{address}/liquidity-pools` endpoints across SDK, CLI, and skill.
+
+  ## SDK (`@opensea/sdk`)
+
+  - `OpenSeaAPI.getTokenHolders(chain, address, args?)` → `TokenHoldersResponse` — paginated holders (`limit`, `cursor`, `sortBy: "QUANTITY"`, `sortDirection`) plus aggregate distribution health (`STRONG | HEALTHY | CONCERNING | BAD`).
+  - `OpenSeaAPI.getTokenLiquidityPools(chain, address, args?)` → `TokenLiquidityPoolsResponse` — pools with pool type, USD reserves, bonding-curve progress, graduation flag.
+  - New type exports: `TokenHoldersResponse`, `TokenHoldersArgs`, `TokenLiquidityPoolsResponse`, `TokenLiquidityPoolsArgs`.
+  - New path helpers in `apiPaths.ts`: `getTokenHoldersPath`, `getTokenLiquidityPoolsPath`.
+
+  ## CLI (`@opensea/cli`)
+
+  - `opensea tokens holders <chain> <address> [--limit] [--next] [--sort-by] [--sort-direction]`
+  - `opensea tokens liquidity-pools <chain> <address> [--limit]`
+  - SDK class additions: `OpenSeaCLI.tokens.holders(...)`, `OpenSeaCLI.tokens.liquidityPools(...)`.
+  - New type re-exports: `TokenHoldersResponse`, `TokenLiquidityPoolsResponse`.
+
+  ## Skill (`@opensea/skill`)
+
+  - `tokens/opensea-token-holders.sh <chain> <address> [limit] [cursor] [sort_by] [sort_direction]`
+  - `tokens/opensea-token-liquidity-pools.sh <chain> <address> [limit]`
+  - Documentation: added rows to `SKILL.md` (Investigation Scripts) and `references/rest-api.md` (Tokens).
+
+  Bumps consume `@opensea/api-types` 0.4.3 (released alongside, see the spec-sync PR for full schema details).
+
+### Patch Changes
+
+- Updated dependencies [96928f4]
+- Updated dependencies [90702a7]
+  - @opensea/api-types@0.4.3
+
 ## 1.8.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@opensea/api-types": "^0.4.2",
+    "@opensea/api-types": "^0.4.3",
     "@opensea/wallet-adapters": "^0.3.0",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

src/commands/tokens.ts

@@ -187,5 +187,62 @@ export function tokensCommand(
       },
     )
 
+  cmd
+    .command("holders")
+    .description(
+      "Get paginated holders for a token (with aggregate distribution health)",
+    )
+    .argument("<chain>", "Chain")
+    .argument("<address>", "Token contract address")
+    .option("--limit <limit>", "Number of results (max 100)", "20")
+    .option("--next <cursor>", "Pagination cursor")
+    .option("--sort-by <field>", "Sort field (QUANTITY)")
+    .option("--sort-direction <direction>", "Sort direction (asc|desc)")
+    .action(
+      async (
+        chain: string,
+        address: string,
+        options: {
+          limit: string
+          next?: string
+          sortBy?: string
+          sortDirection?: string
+        },
+      ) => {
+        const client = getClient()
+        await outputGet(
+          client,
+          getFormat(),
+          `/api/v2/chain/${chain as Chain}/token/${address}/holders`,
+          {
+            limit: parseIntOption(options.limit, "--limit"),
+            cursor: options.next,
+            sort_by: options.sortBy,
+            sort_direction: options.sortDirection,
+          },
+        )
+      },
+    )
+
+  cmd
+    .command("liquidity-pools")
+    .description("Get liquidity pools for a token")
+    .argument("<chain>", "Chain")
+    .argument("<address>", "Token contract address")
+    .option("--limit <limit>", "Number of results (max 50)", "20")
+    .action(
+      async (chain: string, address: string, options: { limit: string }) => {
+        const client = getClient()
+        await outputGet(
+          client,
+          getFormat(),
+          `/api/v2/chain/${chain as Chain}/token/${address}/liquidity-pools`,
+          {
+            limit: parseIntOption(options.limit, "--limit"),
+          },
+        )
+      },
+    )
+
   return cmd
 }

src/sdk.ts

@@ -56,6 +56,8 @@ import type {
   TokenBalanceSortBy,
   TokenBatchResponse,
   TokenDetails,
+  TokenHoldersResponse,
+  TokenLiquidityPoolsResponse,
   TokenSwapActivityPaginatedResponse,
   TraitFilter,
   TransactionReceiptRequest,
@@ -883,6 +885,37 @@ class TokensAPI {
       cursor: options?.next,
     })
   }
+
+  async holders(
+    chain: Chain,
+    address: string,
+    options?: {
+      limit?: number
+      next?: string
+      sortBy?: "QUANTITY"
+      sortDirection?: "asc" | "desc"
+    },
+  ): Promise<TokenHoldersResponse> {
+    return this.client.get(`/api/v2/chain/${chain}/token/${address}/holders`, {
+      limit: options?.limit,
+      cursor: options?.next,
+      sort_by: options?.sortBy,
+      sort_direction: options?.sortDirection,
+    })
+  }
+
+  async liquidityPools(
+    chain: Chain,
+    address: string,
+    options?: { limit?: number },
+  ): Promise<TokenLiquidityPoolsResponse> {
+    return this.client.get(
+      `/api/v2/chain/${chain}/token/${address}/liquidity-pools`,
+      {
+        limit: options?.limit,
+      },
+    )
+  }
 }
 
 class SearchAPI {

src/types/api.ts

@@ -92,6 +92,8 @@ export type PriceHistoryResponse = Schemas["PriceHistoryResponse"]
 export type OhlcvResponse = Schemas["OhlcvResponse"]
 export type TokenSwapActivityPaginatedResponse =
   Schemas["TokenSwapActivityPaginatedResponse"]
+export type TokenHoldersResponse = Schemas["TokenHoldersResponse"]
+export type TokenLiquidityPoolsResponse = Schemas["TokenLiquidityPoolsResponse"]
 export type OwnersPaginatedResponse = Schemas["OwnersPaginatedResponse"]
 export type NftAnalyticsResponse = Schemas["NftAnalyticsResponse"]
 export type PortfolioStatsResponse = Schemas["PortfolioStatsResponse"]

test/commands/tokens.test.ts

@@ -20,6 +20,8 @@ describe("tokensCommand", () => {
     expect(subcommands).toContain("trending")
     expect(subcommands).toContain("top")
     expect(subcommands).toContain("get")
+    expect(subcommands).toContain("holders")
+    expect(subcommands).toContain("liquidity-pools")
   })
 
   it("trending subcommand passes options", async () => {
@@ -73,4 +75,51 @@ describe("tokensCommand", () => {
       "/api/v2/chain/ethereum/token/0xabc",
     )
   })
+
+  it("holders subcommand passes pagination + sort options", async () => {
+    ctx.mockClient.get.mockResolvedValue({ holders: [] })
+
+    const cmd = tokensCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(
+      [
+        "holders",
+        "ethereum",
+        "0xabc",
+        "--limit",
+        "50",
+        "--next",
+        "page-2",
+        "--sort-by",
+        "QUANTITY",
+        "--sort-direction",
+        "desc",
+      ],
+      { from: "user" },
+    )
+
+    expect(ctx.mockClient.get).toHaveBeenCalledWith(
+      "/api/v2/chain/ethereum/token/0xabc/holders",
+      expect.objectContaining({
+        limit: 50,
+        cursor: "page-2",
+        sort_by: "QUANTITY",
+        sort_direction: "desc",
+      }),
+    )
+  })
+
+  it("liquidity-pools subcommand passes limit", async () => {
+    ctx.mockClient.get.mockResolvedValue({ pools: [] })
+
+    const cmd = tokensCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(
+      ["liquidity-pools", "ethereum", "0xabc", "--limit", "30"],
+      { from: "user" },
+    )
+
+    expect(ctx.mockClient.get).toHaveBeenCalledWith(
+      "/api/v2/chain/ethereum/token/0xabc/liquidity-pools",
+      expect.objectContaining({ limit: 30 }),
+    )
+  })
 })

test/sdk.test.ts

@@ -436,6 +436,34 @@ describe("OpenSeaCLI", () => {
       await sdk.tokens.get("ethereum", "0xabc")
       expect(mockGet).toHaveBeenCalledWith("/api/v2/chain/ethereum/token/0xabc")
     })
+
+    it("holders calls correct endpoint with pagination + sort", async () => {
+      mockGet.mockResolvedValue({ holders: [] })
+      await sdk.tokens.holders("ethereum", "0xabc", {
+        limit: 50,
+        next: "page-2",
+        sortBy: "QUANTITY",
+        sortDirection: "desc",
+      })
+      expect(mockGet).toHaveBeenCalledWith(
+        "/api/v2/chain/ethereum/token/0xabc/holders",
+        {
+          limit: 50,
+          cursor: "page-2",
+          sort_by: "QUANTITY",
+          sort_direction: "desc",
+        },
+      )
+    })
+
+    it("liquidityPools calls correct endpoint", async () => {
+      mockGet.mockResolvedValue({ pools: [] })
+      await sdk.tokens.liquidityPools("ethereum", "0xabc", { limit: 30 })
+      expect(mockGet).toHaveBeenCalledWith(
+        "/api/v2/chain/ethereum/token/0xabc/liquidity-pools",
+        { limit: 30 },
+      )
+    })
   })
 
   describe("search", () => {