Release v1.2.0

ryanio · ryanio · commit e2af5bff8d1a · 2026-04-21T01:02:34.000Z
diff --git a/.github/workflows/npm-publish-reusable.yml b/.github/workflows/npm-publish-reusable.yml
@@ -37,7 +37,11 @@ jobs:
       # Use npm install (not npm ci) because the package-lock.json may be
       # out of sync after the sync-package workflow resolves workspace: protocols
       # and updates dependencies. npm ci requires exact lockfile match.
-      - run: npm install
+      #
+      # --legacy-peer-deps mirrors pnpm's permissive peer-dep behavior used in the
+      # monorepo. Without it, packages like api-types fail on openapi-typescript@^7
+      # which declares a strict `typescript@^5.x` peer while we ship typescript@^6.
+      - run: npm install --legacy-peer-deps
 
       - if: ${{ inputs.build-before-publish }}
         run: npm run build
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,27 @@
 # @opensea/cli
 
+## 1.2.0
+
+### Minor Changes
+
+- bc9c6ce: Add token-groups and instant API key endpoints.
+
+  **SDK**:
+
+  - `sdk.api.getTokenGroups({ limit?, cursor? })` and `sdk.api.getTokenGroup(slug)` for the new `/api/v2/token-groups` endpoints.
+  - `OpenSeaSDK.requestInstantApiKey()` and `OpenSeaAPI.requestInstantApiKey()` — static methods that call `POST /api/v2/auth/keys` without authentication and return a free-tier key you can pass into the SDK constructor. Rate limited to 3 keys/hour per IP; keys expire after 30 days.
+  - `OpenSeaAPI` class is now exported from the package root (`@opensea/sdk` and `@opensea/sdk/viem`).
+
+  **CLI**:
+
+  - New `opensea token-groups list` and `opensea token-groups get <slug>` commands.
+  - New `opensea auth request-key` command — works without `--api-key` / `OPENSEA_API_KEY` since the endpoint is unauthenticated.
+
+### Patch Changes
+
+- Updated dependencies [5b6ba13]
+  - @opensea/api-types@0.2.1
+
 ## 1.1.0
 
 ### Minor Changes
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.1.0",
+  "version": "1.2.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.2.0",
+    "@opensea/api-types": "^0.2.1",
     "commander": "^14.0.3",
     "zod": "^4.3.6"
   },
diff --git a/src/cli.ts b/src/cli.ts
@@ -2,6 +2,7 @@ import { Command } from "commander"
 import { OpenSeaAPIError, OpenSeaClient } from "./client.js"
 import {
   accountsCommand,
+  authCommand,
   chainsCommand,
   collectionsCommand,
   dropsCommand,
@@ -12,6 +13,7 @@ import {
   offersCommand,
   searchCommand,
   swapsCommand,
+  tokenGroupsCommand,
   tokensCommand,
 } from "./commands/index.js"
 import { type OutputFormat, setOutputOptions } from "./output.js"
@@ -123,6 +125,10 @@ program.addCommand(offersCommand(getClient, getFormat))
 program.addCommand(eventsCommand(getClient, getFormat))
 program.addCommand(accountsCommand(getClient, getFormat))
 program.addCommand(tokensCommand(getClient, getFormat))
+program.addCommand(tokenGroupsCommand(getClient, getFormat))
+program.addCommand(
+  authCommand(() => program.opts<{ baseUrl?: string }>().baseUrl, getFormat),
+)
 program.addCommand(searchCommand(getClient, getFormat))
 program.addCommand(swapsCommand(getClient, getFormat))
 program.addCommand(healthCommand(getClient, getFormat))
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
@@ -0,0 +1,43 @@
+import { Command } from "commander"
+import type { OutputFormat } from "../output.js"
+import { formatOutput } from "../output.js"
+
+const DEFAULT_BASE_URL = "https://api.opensea.io"
+
+export function authCommand(
+  getBaseUrl: () => string | undefined,
+  getFormat: () => OutputFormat,
+): Command {
+  const cmd = new Command("auth").description(
+    "Authentication helpers — bootstrap an API key without existing credentials",
+  )
+
+  cmd
+    .command("request-key")
+    .description(
+      "Request a free-tier API key (rate limited to 3/hour per IP, keys expire after 30 days)",
+    )
+    .action(async () => {
+      const baseUrl = getBaseUrl() ?? DEFAULT_BASE_URL
+      const response = await fetch(`${baseUrl}/api/v2/auth/keys`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      })
+      if (!response.ok) {
+        const body = await response.text().catch(() => "")
+        console.error(
+          JSON.stringify(
+            { error: "API Error", status: response.status, body },
+            null,
+            2,
+          ),
+        )
+        process.exit(1)
+      }
+      const result = (await response.json()) as Record<string, unknown>
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  return cmd
+}
diff --git a/src/commands/index.ts b/src/commands/index.ts
@@ -1,4 +1,5 @@
 export { accountsCommand } from "./accounts.js"
+export { authCommand } from "./auth.js"
 export { chainsCommand } from "./chains.js"
 export { collectionsCommand } from "./collections.js"
 export { dropsCommand } from "./drops.js"
@@ -9,4 +10,5 @@ export { nftsCommand } from "./nfts.js"
 export { offersCommand } from "./offers.js"
 export { searchCommand } from "./search.js"
 export { swapsCommand } from "./swaps.js"
+export { tokenGroupsCommand } from "./token-groups.js"
 export { tokensCommand } from "./tokens.js"
diff --git a/src/commands/token-groups.ts b/src/commands/token-groups.ts
@@ -0,0 +1,48 @@
+import { Command } from "commander"
+import type { OpenSeaClient } from "../client.js"
+import type { OutputFormat } from "../output.js"
+import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
+
+type TokenGroup = Record<string, unknown>
+
+export function tokenGroupsCommand(
+  getClient: () => OpenSeaClient,
+  getFormat: () => OutputFormat,
+): Command {
+  const cmd = new Command("token-groups").description(
+    "Query token groups (equivalent currencies across chains, e.g. 'eth')",
+  )
+
+  cmd
+    .command("list")
+    .description("List token groups sorted by market cap descending")
+    .option("--limit <limit>", "Number of results (max 100, default 50)", "50")
+    .option("--next <cursor>", "Pagination cursor")
+    .action(async (options: { limit: string; next?: string }) => {
+      const client = getClient()
+      const result = await client.get<{
+        token_groups: TokenGroup[]
+        next?: string
+      }>("/api/v2/token-groups", {
+        limit: parseIntOption(options.limit, "--limit"),
+        // Token Groups API uses "cursor" instead of "next" as the query param
+        cursor: options.next,
+      })
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  cmd
+    .command("get")
+    .description("Get a single token group by slug")
+    .argument("<slug>", "Token group slug (e.g. 'eth')")
+    .action(async (slug: string) => {
+      const client = getClient()
+      const result = await client.get<TokenGroup>(
+        `/api/v2/token-groups/${slug}`,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  return cmd
+}
diff --git a/test/cli-api-error.test.ts b/test/cli-api-error.test.ts
@@ -4,6 +4,7 @@ import { OpenSeaAPIError } from "../src/client.js"
 
 vi.mock("../src/commands/index.js", () => ({
   accountsCommand: () => new Command("accounts"),
+  authCommand: () => new Command("auth"),
   chainsCommand: () => new Command("chains"),
   collectionsCommand: () => new Command("collections"),
   dropsCommand: () => new Command("drops"),
@@ -13,6 +14,7 @@ vi.mock("../src/commands/index.js", () => ({
   offersCommand: () => new Command("offers"),
   searchCommand: () => new Command("search"),
   swapsCommand: () => new Command("swaps"),
+  tokenGroupsCommand: () => new Command("token-groups"),
   tokensCommand: () => new Command("tokens"),
   healthCommand: () => new Command("health"),
 }))
diff --git a/test/cli-network-error.test.ts b/test/cli-network-error.test.ts
@@ -3,6 +3,7 @@ import { afterAll, expect, it, vi } from "vitest"
 
 vi.mock("../src/commands/index.js", () => ({
   accountsCommand: () => new Command("accounts"),
+  authCommand: () => new Command("auth"),
   chainsCommand: () => new Command("chains"),
   collectionsCommand: () => new Command("collections"),
   dropsCommand: () => new Command("drops"),
@@ -12,6 +13,7 @@ vi.mock("../src/commands/index.js", () => ({
   offersCommand: () => new Command("offers"),
   searchCommand: () => new Command("search"),
   swapsCommand: () => new Command("swaps"),
+  tokenGroupsCommand: () => new Command("token-groups"),
   tokensCommand: () => new Command("tokens"),
   healthCommand: () => new Command("health"),
 }))
diff --git a/test/cli-rate-limit.test.ts b/test/cli-rate-limit.test.ts
@@ -4,6 +4,7 @@ import { OpenSeaAPIError } from "../src/client.js"
 
 vi.mock("../src/commands/index.js", () => ({
   accountsCommand: () => new Command("accounts"),
+  authCommand: () => new Command("auth"),
   chainsCommand: () => new Command("chains"),
   collectionsCommand: () => new Command("collections"),
   dropsCommand: () => new Command("drops"),
@@ -13,6 +14,7 @@ vi.mock("../src/commands/index.js", () => ({
   offersCommand: () => new Command("offers"),
   searchCommand: () => new Command("search"),
   swapsCommand: () => new Command("swaps"),
+  tokenGroupsCommand: () => new Command("token-groups"),
   tokensCommand: () => new Command("tokens"),
   healthCommand: () => new Command("health"),
 }))
diff --git a/test/commands/auth.test.ts b/test/commands/auth.test.ts
@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { authCommand } from "../../src/commands/auth.js"
+import { createCommandTestContext } from "../mocks.js"
+
+describe("authCommand", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch")
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("creates command with request-key subcommand", () => {
+    const ctx = createCommandTestContext()
+    const cmd = authCommand(() => undefined, ctx.getFormat)
+    expect(cmd.name()).toBe("auth")
+    expect(cmd.commands.map(c => c.name())).toContain("request-key")
+  })
+
+  it("request-key POSTs to /api/v2/auth/keys without auth header", async () => {
+    const ctx = createCommandTestContext()
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ api_key: "k-123" }), { status: 201 }),
+    )
+
+    const cmd = authCommand(() => undefined, ctx.getFormat)
+    await cmd.parseAsync(["request-key"], { from: "user" })
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchSpy.mock.calls[0] as [
+      string,
+      RequestInit & { headers: Record<string, string> },
+    ]
+    expect(url).toBe("https://api.opensea.io/api/v2/auth/keys")
+    expect(init.method).toBe("POST")
+    // No api-key header in any casing — endpoint is unauthenticated.
+    const headerKeys = Object.keys(init.headers).map(k => k.toLowerCase())
+    expect(headerKeys).not.toContain("x-api-key")
+
+    logSpy.mockRestore()
+  })
+
+  it("request-key uses --base-url override", async () => {
+    const ctx = createCommandTestContext()
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {})
+    fetchSpy.mockResolvedValue(new Response("{}", { status: 201 }))
+
+    const cmd = authCommand(
+      () => "https://testnets-api.opensea.io",
+      ctx.getFormat,
+    )
+    await cmd.parseAsync(["request-key"], { from: "user" })
+
+    const url = fetchSpy.mock.calls[0][0] as string
+    expect(url).toBe("https://testnets-api.opensea.io/api/v2/auth/keys")
+
+    logSpy.mockRestore()
+  })
+})
diff --git a/test/commands/token-groups.test.ts b/test/commands/token-groups.test.ts
@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { tokenGroupsCommand } from "../../src/commands/token-groups.js"
+import { type CommandTestContext, createCommandTestContext } from "../mocks.js"
+
+describe("tokenGroupsCommand", () => {
+  let ctx: CommandTestContext
+
+  beforeEach(() => {
+    ctx = createCommandTestContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("creates command with correct subcommands", () => {
+    const cmd = tokenGroupsCommand(ctx.getClient, ctx.getFormat)
+    expect(cmd.name()).toBe("token-groups")
+    const subcommands = cmd.commands.map(c => c.name())
+    expect(subcommands).toContain("list")
+    expect(subcommands).toContain("get")
+  })
+
+  it("list subcommand passes options and maps --next to cursor", async () => {
+    ctx.mockClient.get.mockResolvedValue({ token_groups: [] })
+
+    const cmd = tokenGroupsCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(["list", "--limit", "25", "--next", "abc123"], {
+      from: "user",
+    })
+
+    expect(ctx.mockClient.get).toHaveBeenCalledWith(
+      "/api/v2/token-groups",
+      expect.objectContaining({ limit: 25, cursor: "abc123" }),
+    )
+  })
+
+  it("get subcommand fetches token group by slug", async () => {
+    ctx.mockClient.get.mockResolvedValue({ slug: "eth" })
+
+    const cmd = tokenGroupsCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(["get", "eth"], { from: "user" })
+
+    expect(ctx.mockClient.get).toHaveBeenCalledWith("/api/v2/token-groups/eth")
+  })
+})
