Release v1.17.0

Origin-SHA: 49f6b1ccdea412dd451b3ecdb71446338fc13e0e

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,20 @@
 # @opensea/cli
 
+## 1.17.0
+
+### Minor Changes
+
+- a093a89: Add first-class SDK and CLI access to materialized token activity stats, with typed window selection and response models.
+
+### Patch Changes
+
+- 954d547: Add typed account agent status fields and helpers to mark or clear registered
+  agent wallets from the SDK and CLI.
+- Updated dependencies [954d547]
+- Updated dependencies [a093a89]
+  - @opensea/api-types@0.8.6
+  - @opensea/sdk@11.7.0
+
 ## 1.16.0
 
 ### Minor Changes

README.md

@@ -55,9 +55,11 @@ Wallet-authenticated endpoints also require a scoped token:
 
 ```bash
 export OPENSEA_PRIVATE_KEY="..."
-opensea login --private-key --scopes read:favorites
+opensea login --private-key --scopes read:favorites,write:wallets
 WALLET=$(opensea --format json whoami | jq -r '.address')
 opensea api request GET "/api/v2/account/$WALLET/favorites" --params '{"limit":1}'
+opensea accounts mark-agent "$WALLET"
+opensea accounts remove-agent "$WALLET"
 opensea auth revoke
 ```
 
@@ -90,6 +92,9 @@ opensea search collections "cool cats"
 # Get trending tokens
 opensea tokens trending --limit 5
 
+# Get materialized token activity for selected windows
+opensea tokens activity-stats base 0x4200000000000000000000000000000000000006 --windows 1h,24h
+
 # Human-readable table output
 opensea --format table collections stats mfers
 ```
@@ -106,9 +111,9 @@ opensea --format table collections stats mfers
 | `transactions` | Poll transaction and cross-chain receipt status |
 | `events` | List marketplace events (sales, transfers, mints, etc.) |
 | `search` | Search collections, NFTs, tokens, and accounts |
-| `tokens` | Get trending tokens, top tokens, and token details |
+| `tokens` | Get trending tokens, top tokens, token details, and activity stats |
 | `swaps` | Get swap quotes for token trading |
-| `accounts` | Get account details |
+| `accounts` | Get account details and manage agent wallet designations |
 | `whoami` | Show the current wallet, scopes, and scope source |
 | `api request` | Call any API v2 endpoint with the active API key and wallet JWT |
 
@@ -130,7 +135,14 @@ const { asset_events } = await client.events.byCollection("mfers", {
   eventType: "sale",
 })
 const { tokens } = await client.tokens.trending({ chains: ["base"], limit: 5 })
+const activity = await client.tokens.activityStats(
+  "base",
+  "0x4200000000000000000000000000000000000006",
+  { windows: ["1h", "24h"] },
+)
 const results = await client.search.collections("mfers", { limit: 5 })
+const markedAgent = await client.accounts.markAgent("0x123...")
+const clearedAgent = await client.accounts.removeAgent("0x123...")
 
 // Error handling
 try {

docs/cli-reference.md

@@ -125,8 +125,12 @@ opensea search <query> [--types <types>] [--chains <chains>] [--limit <n>]
 opensea tokens trending [--chains <chains>] [--limit <n>] [--next <cursor>]
 opensea tokens top [--chains <chains>] [--limit <n>] [--next <cursor>]
 opensea tokens get <chain> <address>
+opensea tokens activity-stats <chain> <address> [--windows <windows>]
 ```
 
+`--windows` accepts a comma-separated list containing `5m`, `1h`, `4h`, and
+`24h`. If omitted, the API returns every available materialized window.
+
 ## Swaps
 
 ```bash
@@ -137,6 +141,11 @@ opensea swaps quote --from-chain <chain> --from-address <address> --to-chain <ch
 
 ```bash
 opensea accounts get <address>
+opensea accounts mark-agent <wallet>
+opensea accounts remove-agent <wallet>
 ```
 
+Agent designation commands require a wallet-authenticated token with the
+`write:wallets` scope.
+
 > REST list commands support cursor-based pagination. The search command returns a flat list with no cursor. See [pagination.md](pagination.md) for details.

docs/sdk.md

@@ -137,6 +137,8 @@ const { asset_events, next } = await client.events.byNFT(
 
 ```typescript
 const account = await client.accounts.get("0x123...")
+const markedAgent = await client.accounts.markAgent("0x123...")
+const clearedAgent = await client.accounts.removeAgent("0x123...")
 ```
 
 ## Tokens
@@ -154,8 +156,18 @@ const { tokens, next } = await client.tokens.top({
 })
 
 const tokenDetails = await client.tokens.get("base", "0x123...")
+
+const activity = await client.tokens.activityStats(
+  "base",
+  "0x4200000000000000000000000000000000000006",
+  { windows: ["1h", "24h"] },
+)
 ```
 
+Token activity stats use the public REST response shape, including
+`computed_at`, `volume_usd`, and `average_trade_usd`. A requested window is
+omitted from `windows` when it has no swaps.
+
 ## Search
 
 Search uses the unified `/api/v2/search` REST endpoint. Results are ranked by relevance and each result has a `type` discriminator (`collection`, `nft`, `token`, or `account`) with the corresponding typed object. The search endpoint does not support cursor-based pagination; use `limit` to control result count (max 50).

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "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.8.4",
-    "@opensea/sdk": "^11.6.0",
+    "@opensea/api-types": "^0.8.6",
+    "@opensea/sdk": "^11.7.0",
     "@opensea/wallet-adapters": "^0.3.3",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

package.json

@@ -10,6 +10,7 @@ import {
 import type {
   FavoriteResponse,
   TokenBalanceSortBy,
+  WalletAgentStatusResponse,
   WatchlistRequest,
 } from "../types/index.js"
 
@@ -28,6 +29,34 @@ export function accountsCommand(
       await outputGet(client, getFormat(), `/api/v2/accounts/${address}`)
     })
 
+  cmd
+    .command("mark-agent")
+    .description(
+      "Mark a registered wallet as an agent (requires write:wallets)",
+    )
+    .argument("<wallet>", "Registered wallet address")
+    .action(async (wallet: string) => {
+      const client = getClient()
+      const result = await client.put<WalletAgentStatusResponse>(
+        `/api/v2/accounts/wallets/${encodeURIComponent(wallet)}/agent`,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  cmd
+    .command("remove-agent")
+    .description(
+      "Remove a registered wallet's agent designation (requires write:wallets)",
+    )
+    .argument("<wallet>", "Registered wallet address")
+    .action(async (wallet: string) => {
+      const client = getClient()
+      const result = await client.delete<WalletAgentStatusResponse>(
+        `/api/v2/accounts/wallets/${encodeURIComponent(wallet)}/agent`,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
   cmd
     .command("tokens")
     .description("Get token balances for an account")

src/commands/accounts.ts

@@ -198,6 +198,26 @@ export function tokensCommand(
     },
   )
 
+  cmd
+    .command("activity-stats")
+    .description(
+      "Get materialized trade count, USD volume, and average trade size for a token",
+    )
+    .argument("<chain>", "Chain")
+    .argument("<address>", "Token contract address")
+    .option("--windows <windows>", "Comma-separated windows (5m, 1h, 4h, 24h)")
+    .action(
+      async (chain: string, address: string, options: { windows?: string }) => {
+        const client = getClient()
+        await outputGet(
+          client,
+          getFormat(),
+          `/api/v2/chain/${chain as Chain}/token/${address}/activity/stats`,
+          { windows: options.windows },
+        )
+      },
+    )
+
   addPaginationOptions(
     cmd
       .command("account-activity")

src/commands/tokens.ts

@@ -58,6 +58,8 @@ import type {
   SweepCollectionResponse,
   Token,
   TokenAccountActivityPaginatedResponse,
+  TokenActivityStatsResponse,
+  TokenActivityStatsWindow,
   TokenBalancePaginatedResponse,
   TokenBalanceSortBy,
   TokenBatchResponse,
@@ -74,6 +76,7 @@ import type {
   TransferRequest,
   TransferResponse,
   ValidateMetadataResponse,
+  WalletAgentStatusResponse,
   WalletPnlResponse,
 } from "./types/index.js"
 import type { TransactionResult, WalletAdapter } from "./wallet/index.js"
@@ -682,6 +685,18 @@ class AccountsAPI {
     return this.client.get(`/api/v2/accounts/${address}`)
   }
 
+  async markAgent(wallet: string): Promise<WalletAgentStatusResponse> {
+    return this.client.put(
+      `/api/v2/accounts/wallets/${encodeURIComponent(wallet)}/agent`,
+    )
+  }
+
+  async removeAgent(wallet: string): Promise<WalletAgentStatusResponse> {
+    return this.client.delete(
+      `/api/v2/accounts/wallets/${encodeURIComponent(wallet)}/agent`,
+    )
+  }
+
   async tokens(
     address: string,
     options?: {
@@ -942,6 +957,17 @@ class TokensAPI {
     })
   }
 
+  async activityStats(
+    chain: Chain,
+    address: string,
+    options?: { windows?: TokenActivityStatsWindow[] },
+  ): Promise<TokenActivityStatsResponse> {
+    return this.client.get(
+      `/api/v2/chain/${chain}/token/${address}/activity/stats`,
+      { windows: options?.windows?.join(",") },
+    )
+  }
+
   async accountActivity(
     address: string,
     options?: {

src/sdk.ts

@@ -95,6 +95,9 @@ export type PriceHistoryResponse = Schemas["PriceHistoryResponse"]
 export type OhlcvResponse = Schemas["OhlcvResponse"]
 export type TokenSwapActivityPaginatedResponse =
   Schemas["TokenSwapActivityPaginatedResponse"]
+export type TokenActivityStatsResponse = Schemas["TokenActivityStatsResponse"]
+export type TokenActivityWindowStatsResponse =
+  Schemas["TokenActivityWindowStatsResponse"]
 export type TokenAccountActivityPaginatedResponse =
   Schemas["TokenAccountActivityPaginatedResponse"]
 export type TokenHoldersResponse = Schemas["TokenHoldersResponse"]
@@ -124,6 +127,8 @@ export interface TraitFilter {
   value: string
 }
 
+export type TokenActivityStatsWindow = "5m" | "1h" | "4h" | "24h"
+
 // ── CLI-specific types (not from API spec) ──────────────────────────
 
 export type SafelistStatus =
@@ -278,6 +283,7 @@ export type WatchlistRequest = Schemas["WatchlistRequest"]
 export type FavoriteResponse = Schemas["FavoriteResponse"]
 export type CancelRequest = Schemas["CancelRequest"]
 export type WalletUnlinkResponse = Schemas["WalletUnlinkResponse"]
+export type WalletAgentStatusResponse = Schemas["WalletAgentStatusResponse"]
 
 export type UpdateProfileSettingsRequest =
   Schemas["UpdateProfileSettingsRequest"]