Release v2.9.1

Origin-SHA: 5f657f94ac77da0ecbcc5efdf264d0ba3cca707d

### Patch Changes

- c5aada3: `events list` no longer accepts a chain filter. `GET /api/v2/events` has no `chain` parameter and returns events from every chain whatever is sent, so the flag never filtered anything. `opensea events list --chain <chain>` and `opensea --chain <chain> events list` now exit with an error that points to `events by-account <address> --chain <chain>` and `events by-nft <chain> <contract> <token-id>`, which do filter by chain. The programmatic `EventsAPI.list` stops sending `chain`, and its `chain` option is deprecated.

  Correction to 2.9.0: its notes list `events list` among the commands whose `--chain` filter was restored. That filter never applied on this endpoint; only `collections list` and `events by-account` filter by chain.

- f5676f0: `opensea tokens holders` now describes the distribution it returns: total holders, the share of eligible supply held by the top 250, and a health score and label.
- Updated dependencies [6ffe0c9]
- Updated dependencies [e7882a8]
- Updated dependencies [a1e4356]
- Updated dependencies [f5676f0]
  - @opensea/api-types@0.14.2
  - @opensea/sdk@12.10.2

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

Author: 3 people

AGENTS.md

@@ -24,7 +24,7 @@ pnpm run format
 1. **Never hand-roll API request/response types**. Import from `@opensea/api-types` via `src/types/api.ts`. Run `pnpm --filter @opensea/api-types run update-spec && pnpm --filter @opensea/api-types run build` before adding endpoints.
 2. **API path check**. `pnpm check-api-paths` (from the repo root) fails if source code references an `/api/v2/...` URL not in `packages/api-types/opensea-api.json`.
 3. **CLI commands are thin**. Parse args, call `OpenSeaClient`, format output with `formatOutput()` (or `outputGet()` from `src/output.ts` for plain GET commands, which also handles TOON). Keep business logic in the client.
-4. **One file per domain in `src/commands/`**. Register new commands in `src/commands/index.ts` and wire in `src/cli.ts`.
+4. **One file per domain in `src/commands/`**. Export new commands from `src/commands/index.ts` and register them with `program.addCommand()` in `src/program.ts` (`createProgram()`).
 5. **SDK classes in `src/sdk.ts`**. Add domain classes as `readonly` properties on `OpenSeaCLI` for programmatic consumers.
 6. **Auth session invariants**. Persisted tokens require access token, refresh token, wallet address, ISO expiration, scopes, and `oauth`/`siwe` method. Normalize only `0x`-prefixed EVM addresses to lowercase; preserve Solana base58 case.
 7. **Exit codes**. `0` success, `1` API error, `2` auth error, `3` rate limited.

CHANGELOG.md

@@ -1,5 +1,21 @@
 # @opensea/cli
 
+## 2.9.1
+
+### Patch Changes
+
+- c5aada3: `events list` no longer accepts a chain filter. `GET /api/v2/events` has no `chain` parameter and returns events from every chain whatever is sent, so the flag never filtered anything. `opensea events list --chain <chain>` and `opensea --chain <chain> events list` now exit with an error that points to `events by-account <address> --chain <chain>` and `events by-nft <chain> <contract> <token-id>`, which do filter by chain. The programmatic `EventsAPI.list` stops sending `chain`, and its `chain` option is deprecated.
+
+  Correction to 2.9.0: its notes list `events list` among the commands whose `--chain` filter was restored. That filter never applied on this endpoint; only `collections list` and `events by-account` filter by chain.
+
+- f5676f0: `opensea tokens holders` now describes the distribution it returns: total holders, the share of eligible supply held by the top 250, and a health score and label.
+- Updated dependencies [6ffe0c9]
+- Updated dependencies [e7882a8]
+- Updated dependencies [a1e4356]
+- Updated dependencies [f5676f0]
+  - @opensea/api-types@0.14.2
+  - @opensea/sdk@12.10.2
+
 ## 2.9.0
 
 ### Minor Changes

docs/cli-reference.md

@@ -15,9 +15,11 @@ Full command reference for all `opensea` CLI commands.
 ```
 
 A `--chain` you pass reaches every subcommand that takes `--chain` (such as
-`collections list`, `events list` or `drops deploy`), whether you put it before
-or after the subcommand. The `ethereum` default never does: a chain filter you
-leave out filters nothing, and a command that needs a chain fails without one.
+`collections list`, `events by-account` or `drops deploy`), whether you put it
+before or after the subcommand. The `ethereum` default never does: a chain
+filter you leave out filters nothing, and a command that needs a chain fails
+without one. `events list` has no chain filter and refuses a `--chain` you
+pass; use `events by-account --chain` or `events by-nft <chain>` instead.
 
 ## Authentication
 
@@ -243,7 +245,7 @@ opensea transactions receipt --request <receipt-request.json>
 ## Events
 
 ```bash
-opensea events list [--event-type <type>] [--after <timestamp>] [--before <timestamp>] [--chain <chain>] [--limit <n>] [--next <cursor>]
+opensea events list [--event-type <type>] [--after <timestamp>] [--before <timestamp>] [--limit <n>] [--next <cursor>]
 opensea events by-account <address> [--event-type <type>] [--chain <chain>] [--limit <n>] [--next <cursor>]
 opensea events by-collection <slug> [--event-type <type>] [--limit <n>] [--next <cursor>]
 opensea events by-nft <chain> <contract> <token-id> [--event-type <type>] [--limit <n>] [--next <cursor>]

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -23,8 +23,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@opensea/api-types": "^0.14.0",
-    "@opensea/sdk": "^12.10.1",
+    "@opensea/api-types": "^0.14.2",
+    "@opensea/sdk": "^12.10.2",
     "@opensea/wallet-adapters": "^1.2.1",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

package.json

@@ -1,4 +1,4 @@
-import { Command } from "commander"
+import { Command, Option } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import type { OutputFormat } from "../output.js"
 import { outputGet } from "../output.js"
@@ -17,32 +17,40 @@ export function eventsCommand(
   const cmd = new Command("events").description("Query marketplace events")
 
   addPaginationOptions(
-    addChainOption(
-      cmd
-        .command("list")
-        .description("List events")
-        .option(
-          "--event-type <type>",
-          "Event type (sale, transfer, mint, listing, offer, trait_offer, collection_offer)",
-        )
-        .option(
-          "--after <timestamp>",
-          "Filter events after this Unix timestamp",
-        )
-        .option(
-          "--before <timestamp>",
-          "Filter events before this Unix timestamp",
-        ),
-    ),
+    cmd
+      .command("list")
+      .description("List events")
+      .option(
+        "--event-type <type>",
+        "Event type (sale, transfer, mint, listing, offer, trait_offer, collection_offer)",
+      )
+      .option("--after <timestamp>", "Filter events after this Unix timestamp")
+      .option(
+        "--before <timestamp>",
+        "Filter events before this Unix timestamp",
+      )
+      // GET /api/v2/events has no chain filter. The option stays declared,
+      // hidden, so a --chain in either position reaches this action and is
+      // refused rather than silently returning events from every chain.
+      .addOption(new Option("--chain <chain>").hideHelp()),
   ).action(
-    async (options: {
-      eventType?: string
-      after?: string
-      before?: string
-      chain?: string
-      limit: string
-      next?: string
-    }) => {
+    async (
+      options: {
+        eventType?: string
+        after?: string
+        before?: string
+        chain?: string
+        limit: string
+        next?: string
+      },
+      command: Command,
+    ) => {
+      if (options.chain !== undefined) {
+        command.error(
+          "error: events list cannot filter by chain, because the events endpoint has no chain filter. Use 'opensea events by-account <address> --chain <chain>' or 'opensea events by-nft <chain> <contract> <token-id>' instead.",
+          { code: "opensea.unsupportedChainFilter" },
+        )
+      }
       const client = getClient()
       await outputGet(client, getFormat(), "/api/v2/events", {
         event_type: options.eventType,
@@ -52,7 +60,6 @@ export function eventsCommand(
         before: options.before
           ? parseIntOption(options.before, "--before")
           : undefined,
-        chain: options.chain,
         limit: parseIntOption(options.limit, "--limit"),
         next: options.next,
       })

src/commands/events.ts

@@ -266,7 +266,7 @@ export function tokensCommand(
     cmd
       .command("holders")
       .description(
-        "Get paginated holders for a token (with aggregate distribution health)",
+        "Get paginated holders for a token, with its distribution: total holders, the share of eligible supply held by the top 250, and a health score and label",
       )
       .argument("<chain>", "Chain")
       .argument("<address>", "Token contract address"),

src/commands/tokens.ts

@@ -904,6 +904,11 @@ class EventsAPI {
     before?: number
     limit?: number
     next?: string
+    /**
+     * @deprecated Ignored and not sent. `GET /api/v2/events` has no `chain`
+     * parameter, so it never filtered. Use `byAccount` with `chain`, or
+     * `byNFT`, for chain-scoped events.
+     */
     chain?: Chain
   }): Promise<{ asset_events: AssetEvent[]; next?: string }> {
     return this.client.get("/api/v2/events", {
@@ -912,7 +917,6 @@ class EventsAPI {
       before: options?.before,
       limit: options?.limit,
       next: options?.next,
-      chain: options?.chain,
     })
   }
 

src/sdk.ts

@@ -155,7 +155,6 @@ describe("subcommand --chain through the full program", () => {
   describe("--chain filters", () => {
     it.each([
       [["collections", "list"], "/api/v2/collections"],
-      [["events", "list"], "/api/v2/events"],
       [
         ["events", "by-account", "0x1111111111111111111111111111111111111111"],
         "/api/v2/events/accounts/0x1111111111111111111111111111111111111111",
@@ -178,6 +177,38 @@ describe("subcommand --chain through the full program", () => {
     })
   })
 
+  // GET /api/v2/events has no chain parameter and returns every chain's
+  // events whatever is sent, so a chain the user asks for is refused.
+  describe("events list", () => {
+    it.each([
+      ["after the subcommand", ["events", "list", "--chain", "base"]],
+      ["before the subcommand", ["--chain", "base", "events", "list"]],
+    ])("refuses --chain placed %s", async (_, argv) => {
+      const stderr = vi
+        .spyOn(process.stderr, "write")
+        .mockImplementation(() => true)
+      vi.spyOn(process, "exit").mockImplementation(() => {
+        throw new Error("process.exit")
+      })
+
+      await expect(run(...argv)).rejects.toThrow("process.exit")
+
+      expect(fetchSpy).not.toHaveBeenCalled()
+      expect(stderr.mock.calls.flat().join("")).toContain(
+        "events list cannot filter by chain",
+      )
+    })
+
+    it("runs without --chain and sends no chain", async () => {
+      respondWith({ asset_events: [] })
+
+      await run("events", "list")
+
+      expect(requestedUrl().pathname).toBe("/api/v2/events")
+      expect(requestedUrl().searchParams.has("chain")).toBe(false)
+    })
+  })
+
   // Commander checks a mandatory option before any hook runs, so a
   // `requiredOption("--chain ...")` on a subcommand can never be satisfied:
   // the program has already taken the value. Required chains are checked in

test/cli-chain-option.test.ts

@@ -27,19 +27,43 @@ describe("eventsCommand", () => {
     ctx.mockClient.get.mockResolvedValue({ asset_events: [] })
 
     const cmd = eventsCommand(ctx.getClient, ctx.getFormat)
-    await cmd.parseAsync(
-      ["list", "--event-type", "sale", "--limit", "5", "--chain", "ethereum"],
-      { from: "user" },
-    )
+    await cmd.parseAsync(["list", "--event-type", "sale", "--limit", "5"], {
+      from: "user",
+    })
 
     expect(ctx.mockClient.get).toHaveBeenCalledWith(
       "/api/v2/events",
       expect.objectContaining({
         event_type: "sale",
         limit: 5,
-        chain: "ethereum",
       }),
     )
+    expect(ctx.mockClient.get.mock.calls[0][1]).not.toHaveProperty("chain")
+  })
+
+  it("list subcommand refuses --chain instead of sending an ignored filter", async () => {
+    const cmd = eventsCommand(ctx.getClient, ctx.getFormat)
+    cmd.exitOverride()
+    cmd.commands.find(c => c.name() === "list")?.exitOverride()
+    const stderr = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true)
+
+    await expect(
+      cmd.parseAsync(["list", "--chain", "base"], { from: "user" }),
+    ).rejects.toMatchObject({ code: "opensea.unsupportedChainFilter" })
+
+    expect(ctx.mockClient.get).not.toHaveBeenCalled()
+    const message = stderr.mock.calls.flat().join("")
+    expect(message).toContain("events list cannot filter by chain")
+    expect(message).toContain("events by-account <address> --chain <chain>")
+    expect(message).toContain("events by-nft <chain>")
+  })
+
+  it("list help does not advertise --chain", () => {
+    const cmd = eventsCommand(ctx.getClient, ctx.getFormat)
+    const list = cmd.commands.find(c => c.name() === "list")
+    expect(list?.helpInformation()).not.toContain("--chain")
   })
 
   it("list subcommand parses after/before timestamps", async () => {