Release v1.15.0

Origin-SHA: 288babb8fdf08d5296232fcdb46016533553081c

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,20 @@
 # @opensea/cli
 
+## 1.15.0
+
+### Minor Changes
+
+- bf5874d: Add `opensea tokens account-activity` to query fungible token activity (transfers, swaps, wraps, unwraps) for an account via `GET /api/v2/account/{address}/token-activity`, and `opensea tools activity` to view payment/usage activity for a registered tool via `GET /api/v2/tools/{registry_chain}/{registry_addr}/{tool_id}/activity`.
+- bf5874d: Add `opensea tools saved` subcommands for listing, saving, and removing saved tools via the wallet-authenticated `GET/POST/DELETE /api/v2/saved-tools` endpoints.
+
+### Patch Changes
+
+- 9bc9708: Require explicit scopes for private-key CLI login, and add typed SDK helpers for the wallet-authenticated social and saved-tools REST endpoints.
+- Updated dependencies [bf5874d]
+- Updated dependencies [bf5874d]
+- Updated dependencies [9bc9708]
+  - @opensea/sdk@11.5.0
+
 ## 1.14.1
 
 ### Patch Changes

README.md

@@ -54,21 +54,20 @@ Get an API key instantly via the command above, or get a full key at [opensea.io
 Wallet-authenticated endpoints also require a scoped token:
 
 ```bash
-opensea login
-opensea auth status
-opensea whoami
-opensea api request GET /api/v2/account/0xYOUR_WALLET/favorites --params '{"limit":1}'
+export OPENSEA_PRIVATE_KEY="..."
+opensea login --private-key --scopes read:favorites
+WALLET=$(opensea --format json whoami | jq -r '.address')
+opensea api request GET "/api/v2/account/$WALLET/favorites" --params '{"limit":1}'
+opensea auth revoke
 ```
 
-Use `--scopes` with `opensea login` to request a narrower scope set. For
-server-side agents, set `OPENSEA_PRIVATE_KEY` and pass `--private-key` (or pass
-`--private-key <key>`) to authenticate with SIWE instead of OAuth. Using the
-environment variable is recommended to keep the key out of shell history. The
-`api request` command supports GET, POST, PUT, PATCH, and DELETE plus JSON body
-files, so newly published scoped endpoints are available without waiting for a
-dedicated command. SIWE logins retain the session needed for session-only PAT
-revocation; `opensea auth revoke` refreshes that session before deleting the
-token.
+Private-key login uses SIWE and requires an explicit `--scopes` list. The
+private key signs locally and is not stored. The CLI
+keeps the session needed to revoke the personal access token (PAT), and
+`api request` sends the stored wallet JWT alongside `OPENSEA_API_KEY`. Use
+`opensea auth refresh` after the JWT expires. For interactive login, run
+`opensea login` without `--private-key`. See the
+[wallet-auth guide](https://docs.opensea.io/reference/auth).
 
 ## Quick Start
 
@@ -109,7 +108,7 @@ opensea --format table collections stats mfers
 | `swaps` | Get swap quotes for token trading |
 | `accounts` | Get account details |
 | `whoami` | Show the current wallet, scopes, and scope source |
-| `api request` | Call any API v2 endpoint with the active API key and scoped token |
+| `api request` | Call any API v2 endpoint with the active API key and wallet JWT |
 
 Global options: `--api-key`, `--chain` (default: ethereum), `--format` (json/table/toon), `--base-url`
 

docs/cli-reference.md

@@ -29,8 +29,8 @@ only and never authorization data.
 
 ```bash
 opensea login [--scopes <scopes>] [--client-id <id>] [--device] [--no-browser]
-opensea login --private-key [--scopes <scopes>]
-opensea login --private-key <key> [--scopes <scopes>]
+opensea login --private-key --scopes <scopes>
+opensea login --private-key <key> --scopes <scopes>
 ```
 
 `login` obtains a scoped access token and stores it in `~/.opensea/auth.json`.
@@ -39,7 +39,8 @@ By default it runs the OAuth 2.1 authorization-code flow in a browser. Use
 URL. Pass `--private-key` to authenticate with SIWE instead of OAuth, which is
 useful for server-side agents. Set `OPENSEA_PRIVATE_KEY` and use `--private-key`
 without a value to keep the key out of shell history; a raw key can be passed as
-an option value when necessary.
+an option value when necessary. Private-key login requires `--scopes` so the
+agent's capabilities are always explicit.
 
 ## Collections
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@opensea/api-types": "^0.8.2",
-    "@opensea/sdk": "^11.4.9",
+    "@opensea/sdk": "^11.5.0",
     "@opensea/wallet-adapters": "^0.3.3",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

package.json

@@ -1,5 +1,5 @@
 import { AUTH_SCOPES } from "@opensea/api-types"
-import { linkWalletWithSiwx, OPENSEA_SCOPES, OpenSeaOAuth } from "@opensea/sdk"
+import { linkWalletWithSiwx, OpenSeaOAuth } from "@opensea/sdk"
 import {
   createWalletFromEnv,
   PrivateKeyAdapter,
@@ -84,14 +84,23 @@ export function authCommand(
       "--private-key [key]",
       "Use a private key for SIWE login (set OPENSEA_PRIVATE_KEY, or pass the key as the value; using the env var is recommended)",
     )
-    .option(
-      "--scopes <scopes>",
-      "Comma-separated scopes to request",
-      OPENSEA_SCOPES.READ_ELIGIBILITY,
-    )
-    .action(async (opts: { privateKey?: string | true; scopes: string }) => {
+    .option("--scopes <scopes>", "Comma-separated scopes to request")
+    .action(async (opts: { privateKey?: string | true; scopes?: string }) => {
+      if (!opts.scopes?.trim()) {
+        throw new Error(
+          "Private-key login requires --scopes. Run `opensea auth scopes` to list available scopes.",
+        )
+      }
       const baseUrl = getBaseUrl() ?? DEFAULT_BASE_URL
-      const scopes = opts.scopes.split(",").map(s => s.trim())
+      const scopes = opts.scopes
+        .split(",")
+        .map(s => s.trim())
+        .filter(Boolean)
+      if (scopes.length === 0) {
+        throw new Error(
+          "Private-key login requires --scopes. Run `opensea auth scopes` to list available scopes.",
+        )
+      }
       const { privateKey, source } = resolvePrivateKey(opts.privateKey)
       warnIfInlinePrivateKey(source)
 

src/commands/auth.ts

@@ -28,7 +28,6 @@ const DEFAULT_BASE_URL = "https://api.opensea.io"
  * Zitadel's project roles, which can include deferred or internal roles.
  */
 const DEFAULT_SCOPES = AUTH_SCOPES.map(({ name }) => name)
-
 function scopesOutsideRequested(
   requestedScopes: string[],
   grantedScopes: string[],
@@ -84,14 +83,20 @@ export function loginCommand(
         device?: boolean
         browser: boolean
       }) => {
-        const scopes = opts.scopes
+        const requestedScopes = opts.scopes
           ? opts.scopes
               .split(",")
               .map(s => s.trim())
               .filter(Boolean)
-          : [...DEFAULT_SCOPES]
+          : undefined
 
         if (opts.privateKey !== undefined) {
+          if (!requestedScopes?.length) {
+            throw new Error(
+              "Private-key login requires --scopes. Run `opensea auth scopes` to list available scopes.",
+            )
+          }
+          const scopes = requestedScopes
           const { privateKey, source } = resolvePrivateKey(opts.privateKey)
           warnIfInlinePrivateKey(source)
 
@@ -159,6 +164,7 @@ export function loginCommand(
         const clientId = resolveOAuthClientId(opts.clientId)
         const issuer = getAuthBaseUrl?.() ?? DEFAULT_AUTH_BASE_URL
         const oauth = new OpenSeaOAuth({ clientId, issuer })
+        const scopes = requestedScopes ?? [...DEFAULT_SCOPES]
 
         const token = opts.device
           ? await runDeviceFlow(oauth, scopes)

src/commands/login.ts

@@ -198,6 +198,50 @@ export function tokensCommand(
     },
   )
 
+  addPaginationOptions(
+    cmd
+      .command("account-activity")
+      .description(
+        "Get fungible token activity for an account (transfers, swaps, wraps, unwraps)",
+      )
+      .argument("<address>", "Account address")
+      .option("--chains <chains>", "Comma-separated chains to filter by")
+      .option(
+        "--tokens <tokens>",
+        "Comma-separated token contract addresses to filter by",
+      )
+      .option(
+        "--type <types>",
+        "Comma-separated activity types (send, receive, swap, wrap, unwrap)",
+      ),
+    "Number of results per page",
+  ).action(
+    async (
+      address: string,
+      options: {
+        limit: string
+        next?: string
+        chains?: string
+        tokens?: string
+        type?: string
+      },
+    ) => {
+      const client = getClient()
+      await outputGet(
+        client,
+        getFormat(),
+        `/api/v2/account/${address}/token-activity`,
+        {
+          chains: options.chains,
+          tokens: options.tokens,
+          type: options.type,
+          limit: parseIntOption(options.limit, "--limit"),
+          next: options.next,
+        },
+      )
+    },
+  )
+
   addPaginationOptions(
     cmd
       .command("holders")