Release v11.1.0

Origin-SHA: bbe72b6405aad02845d2b39d2706d893c4b165de

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,39 @@
 # @opensea/sdk
 
+## 11.1.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
+
 ## 11.0.0
 
 ### Major Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs, tokens, and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",
@@ -45,7 +45,7 @@
   "types": "lib/index.d.ts",
   "dependencies": {
     "@noble/hashes": "^2.0.1",
-    "@opensea/api-types": "^0.4.2",
+    "@opensea/api-types": "^0.4.3",
     "@opensea/seaport-js": "^4.1.1",
     "ethers": "^6.16.0"
   },

src/api/api.ts

@@ -116,6 +116,10 @@ import {
   type SweepCollectionResponse,
   type TokenActivityArgs,
   type TokenBatchResponse,
+  type TokenHoldersArgs,
+  type TokenHoldersResponse,
+  type TokenLiquidityPoolsArgs,
+  type TokenLiquidityPoolsResponse,
   type TokenSwapActivityPaginatedResponse,
   type TokenTimeSeriesArgs,
   type TraitFilter,
@@ -1078,6 +1082,30 @@ export class OpenSeaAPI {
     return this.tokensAPI.getTokenActivity(chain, address, args)
   }
 
+  /**
+   * Fetch paginated holders for a token, including quantity held, USD value,
+   * and aggregate distribution health (STRONG | HEALTHY | CONCERNING | BAD).
+   */
+  public async getTokenHolders(
+    chain: Chain,
+    address: string,
+    args?: TokenHoldersArgs,
+  ): Promise<TokenHoldersResponse> {
+    return this.tokensAPI.getTokenHolders(chain, address, args)
+  }
+
+  /**
+   * Fetch liquidity pools for a token (pool type, USD reserves, and
+   * bonding-curve progress / graduation flag where applicable).
+   */
+  public async getTokenLiquidityPools(
+    chain: Chain,
+    address: string,
+    args?: TokenLiquidityPoolsArgs,
+  ): Promise<TokenLiquidityPoolsResponse> {
+    return this.tokensAPI.getTokenLiquidityPools(chain, address, args)
+  }
+
   /**
    * Fetch multiple NFTs in a single request.
    */

src/api/apiPaths.ts

@@ -321,6 +321,14 @@ export const getTokenActivityPath = (chain: Chain, address: string) => {
   return `${API_V2_PREFIX}/chain/${chain}/token/${address}/activity`
 }
 
+export const getTokenHoldersPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/token/${address}/holders`
+}
+
+export const getTokenLiquidityPoolsPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/token/${address}/liquidity-pools`
+}
+
 // ── NFT analytics ───────────────────────────────────────────────────
 
 export const getNFTOwnersPath = (

src/api/tokens.ts

@@ -6,6 +6,8 @@ import {
   getTokenActivityPath,
   getTokenGroupPath,
   getTokenGroupsPath,
+  getTokenHoldersPath,
+  getTokenLiquidityPoolsPath,
   getTokenOhlcvPath,
   getTokenPath,
   getTokenPriceHistoryPath,
@@ -30,6 +32,10 @@ import type {
   SwapExecuteResponse,
   TokenActivityArgs,
   TokenBatchResponse,
+  TokenHoldersArgs,
+  TokenHoldersResponse,
+  TokenLiquidityPoolsArgs,
+  TokenLiquidityPoolsResponse,
   TokenSwapActivityPaginatedResponse,
   TokenTimeSeriesArgs,
 } from "./types"
@@ -161,4 +167,35 @@ export class TokensAPI {
       args,
     )
   }
+
+  /**
+   * Fetch paginated holders for a token, including quantity held, USD value,
+   * and an aggregate distribution health label (STRONG | HEALTHY |
+   * CONCERNING | BAD).
+   */
+  async getTokenHolders(
+    chain: Chain,
+    address: string,
+    args?: TokenHoldersArgs,
+  ): Promise<TokenHoldersResponse> {
+    return this.fetcher.get<TokenHoldersResponse>(
+      getTokenHoldersPath(chain, address),
+      args,
+    )
+  }
+
+  /**
+   * Fetch liquidity pools for a token (pool type, reserves in USD, and
+   * bonding-curve progress / graduation flag where applicable).
+   */
+  async getTokenLiquidityPools(
+    chain: Chain,
+    address: string,
+    args?: TokenLiquidityPoolsArgs,
+  ): Promise<TokenLiquidityPoolsResponse> {
+    return this.fetcher.get<TokenLiquidityPoolsResponse>(
+      getTokenLiquidityPoolsPath(chain, address),
+      args,
+    )
+  }
 }

src/api/types.ts

@@ -1193,6 +1193,8 @@ import type {
   ProfileCollectionsResponse as ApiProfileCollectionsResponse,
   SwapTransactionResponse as ApiSwapTransactionResponse,
   TokenBatchResponse as ApiTokenBatchResponse,
+  TokenHoldersResponse as ApiTokenHoldersResponse,
+  TokenLiquidityPoolsResponse as ApiTokenLiquidityPoolsResponse,
   TokenSwapActivityPaginatedResponse as ApiTokenSwapActivityPaginatedResponse,
   TransferRequest as ApiTransferRequest,
   TransferResponse as ApiTransferResponse,
@@ -1236,6 +1238,9 @@ export type PriceHistoryResponse = Camelize<ApiPriceHistoryResponse>
 export type ProfileCollectionsResponse = Camelize<ApiProfileCollectionsResponse>
 export type SwapTransactionResponse = Camelize<ApiSwapTransactionResponse>
 export type TokenBatchResponse = Camelize<ApiTokenBatchResponse>
+export type TokenHoldersResponse = Camelize<ApiTokenHoldersResponse>
+export type TokenLiquidityPoolsResponse =
+  Camelize<ApiTokenLiquidityPoolsResponse>
 export type TokenSwapActivityPaginatedResponse =
   Camelize<ApiTokenSwapActivityPaginatedResponse>
 export type TransferResponse = Camelize<ApiTransferResponse>
@@ -1295,6 +1300,26 @@ export interface TokenActivityArgs {
   cursor?: string
 }
 
+/**
+ * Query args for the token holders endpoint (paginated with `cursor`,
+ * sortable by `QUANTITY`).
+ * @category API Query Args
+ */
+export interface TokenHoldersArgs {
+  limit?: number
+  cursor?: string
+  sortBy?: "QUANTITY"
+  sortDirection?: "asc" | "desc"
+}
+
+/**
+ * Query args for the token liquidity-pools endpoint.
+ * @category API Query Args
+ */
+export interface TokenLiquidityPoolsArgs {
+  limit?: number
+}
+
 /**
  * Query args for the NFT owners endpoint (paginated with `next` cursor).
  * @category API Query Args

test/api/tokens.spec.ts

@@ -9,6 +9,7 @@ import type {
   GetTrendingTokensResponse,
   Token,
 } from "../../src/api/types"
+import { Chain } from "../../src/types"
 import { createMockFetcher } from "../fixtures/fetcher"
 
 const mockToken: Token = {
@@ -352,6 +353,68 @@ describe("API: TokensAPI", () => {
     })
   })
 
+  describe("getTokenHolders", () => {
+    test("fetches token holders without args", async () => {
+      mockGet.mockResolvedValue({ holders: [] })
+
+      await tokensAPI.getTokenHolders(
+        Chain.Mainnet,
+        "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+      )
+
+      expect(mockGet).toHaveBeenCalledTimes(1)
+      expect(mockGet.mock.calls[0][0]).toBe(
+        "/api/v2/chain/ethereum/token/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/holders",
+      )
+      expect(mockGet.mock.calls[0][1]).toBeUndefined()
+    })
+
+    test("passes limit/cursor/sortBy/sortDirection query args", async () => {
+      mockGet.mockResolvedValue({ holders: [] })
+
+      await tokensAPI.getTokenHolders(Chain.Mainnet, "0xabc", {
+        limit: 50,
+        cursor: "page-2",
+        sortBy: "QUANTITY",
+        sortDirection: "desc",
+      })
+
+      expect(mockGet.mock.calls[0][1]).toEqual({
+        limit: 50,
+        cursor: "page-2",
+        sortBy: "QUANTITY",
+        sortDirection: "desc",
+      })
+    })
+  })
+
+  describe("getTokenLiquidityPools", () => {
+    test("fetches token liquidity pools without args", async () => {
+      mockGet.mockResolvedValue({ pools: [] })
+
+      await tokensAPI.getTokenLiquidityPools(
+        Chain.Mainnet,
+        "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+      )
+
+      expect(mockGet).toHaveBeenCalledTimes(1)
+      expect(mockGet.mock.calls[0][0]).toBe(
+        "/api/v2/chain/ethereum/token/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/liquidity-pools",
+      )
+      expect(mockGet.mock.calls[0][1]).toBeUndefined()
+    })
+
+    test("passes limit query arg", async () => {
+      mockGet.mockResolvedValue({ pools: [] })
+
+      await tokensAPI.getTokenLiquidityPools(Chain.Mainnet, "0xabc", {
+        limit: 50,
+      })
+
+      expect(mockGet.mock.calls[0][1]).toEqual({ limit: 50 })
+    })
+  })
+
   describe("Constructor", () => {
     test("initializes with fetcher", () => {
       const { fetcher } = createMockFetcher()