Release v10.2.1

Author: ryanio

AGENTS.md

@@ -0,0 +1,64 @@
+# sdk — Agent Conventions
+
+TypeScript SDK for buying, selling, and managing NFTs and tokens on OpenSea. Supports ethers and viem providers.
+
+## Quick Reference
+
+```bash
+cd packages/sdk
+pnpm install
+pnpm run build         # Build with tsc
+pnpm run test          # Run unit tests with Vitest
+pnpm run test:integration  # Run integration tests (requires API key)
+pnpm run lint          # Lint with Biome
+pnpm run format        # Format with Biome
+pnpm run check-types   # TypeScript type checking (stricter tsconfig)
+```
+
+## Architecture
+
+| Directory | Role |
+|-----------|------|
+| `src/sdk.ts` | `OpenSeaSDK` — main ethers entry point |
+| `src/viem.ts` | `OpenSeaViemSDK` — viem entry point |
+| `src/sdk/base.ts` | `BaseOpenSeaSDK` — shared logic for both providers |
+| `src/sdk/fulfillment.ts` | Order fulfillment (buy, sell, match) via Seaport |
+| `src/sdk/orders.ts` | Create and manage listings and offers |
+| `src/sdk/cancellation.ts` | Order cancellation logic |
+| `src/sdk/assets.ts` | Asset transfers and approvals |
+| `src/sdk/tokens.ts` | ERC20 wrap/unwrap (WETH) |
+| `src/sdk/context.ts` | Shared per-call context (provider, chain, API client) threaded through the SDK |
+| `src/api/` | `OpenSeaAPI` client — all REST API calls |
+| `src/provider/` | Provider abstraction: ethers adapter, viem adapter, Seaport bridge |
+| `src/abi/` | Contract ABIs (ERC20, ERC721, ERC1155, Multicall3, TransferHelper) |
+| `src/utils/` | Chain helpers, fee calculations, rate limiting, address utilities |
+| `src/orders/` | Order types and Seaport parameter construction |
+| `test/` | Unit and integration tests |
+
+## Review Checklist
+
+When reviewing changes to this package, verify:
+
+1. **Chain enum sync**: The `Chain` enum in `src/types.ts` has a compile-time check (`_AssertAPIChainsCovered`) ensuring every `ChainIdentifier` from `@opensea/api-types` maps to a `Chain` value. When adding a chain, also update `scripts/chain-data.json` at the **monorepo root**, run `pnpm sync-chains` from the monorepo root, and update `getListingPaymentToken` / `getOfferPaymentToken` / `getNativeWrapTokenAddress`.
+
+2. **Dual provider support**: Both `OpenSeaSDK` (ethers) and `OpenSeaViemSDK` (viem) must work. Changes to `BaseOpenSeaSDK` affect both. If adding provider-specific logic, ensure both adapters in `src/provider/` are updated.
+
+3. **`@opensea/api-types` dependency**: The SDK imports types from the workspace `@opensea/api-types` package. If the OpenAPI spec changes, rebuild api-types first (`pnpm --filter @opensea/api-types run build`) before testing the SDK.
+
+4. **Seaport integration**: Order creation and fulfillment flows use `@opensea/seaport-js`. Changes to order parameters, consideration items, or fulfillment logic must be tested against the Seaport contract behavior.
+
+5. **No secret leakage**: API keys are passed via `OpenSeaAPIConfig.apiKey`. Never log or expose them. Integration tests read keys from environment variables.
+
+## Conventions
+
+- CommonJS (`"type": "commonjs"`). The SDK is consumed by both CJS and ESM projects.
+- Biome for linting and formatting (config at monorepo root).
+- `viem` is an optional peer dependency — the main entry point uses ethers; `@opensea/sdk/viem` is the viem entry point.
+- Amounts use the `Amount` type (`string | number | bigint`). Prefer `string` for decimal values to avoid floating-point precision issues.
+- The `Chain` enum uses API slug strings (e.g. `"ethereum"`, `"base"`), not numeric chain IDs.
+
+## Testing
+
+- **Unit tests** (`test/`): Mock API responses, test order construction and parameter validation.
+- **Integration tests** (`test/integration/`): Hit the real API. Require `OPENSEA_API_KEY` env var. Run separately with `pnpm run test:integration`.
+- Always run `pnpm run check-types` — it uses a stricter tsconfig than the build.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @opensea/sdk
 
+## 10.2.1
+
+### Patch Changes
+
+- 4a76bc1: Add server-side trait filtering on three collection-scoped read methods. `getNFTsByCollection`, `getBestListings`, and `getEventsByCollection` now accept an optional `traits` argument (a `TraitFilter[]`); multiple entries are AND-combined server-side. The SDK JSON-encodes the array for the request — callers pass a structured `[{ traitType, value }]`. New exports: `TraitFilter`, `GetEventsByCollectionArgs`, `encodeTraitsParam`. Requires `@opensea/api-types@^0.2.2`.
+
 ## 10.2.0
 
 ### Minor Changes

biome.json

@@ -5,13 +5,13 @@
       "**/*.ts",
       "**/*.js",
       "**/*.json",
-      "!**/node_modules/**",
-      "!**/dist/**",
-      "!**/lib/**",
-      "!**/coverage/**",
-      "!**/.nyc_output/**",
-      "!packages/sdk/src/typechain/**",
-      "!**/typechain/**",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/lib",
+      "!**/coverage",
+      "!**/.nyc_output",
+      "!packages/sdk/src/typechain",
+      "!**/typechain",
       "!packages/api-types/src/generated.ts",
       "!**/pnpm-lock.yaml",
       "!**/package-lock.json"
@@ -41,9 +41,10 @@
         "noExplicitAny": "off"
       },
       "correctness": {
-        "noUnusedImports": "warn"
+        "noUnusedImports": "error"
       },
       "style": {
+        "noNonNullAssertion": "error",
         "noUnusedTemplateLiteral": "off"
       }
     }
@@ -53,8 +54,8 @@
       "includes": ["**/*.test.ts", "**/*.spec.ts", "**/test/**"],
       "linter": {
         "rules": {
-          "correctness": {
-            "noUnusedImports": "off"
+          "style": {
+            "noNonNullAssertion": "off"
           }
         }
       }

developerDocs/api-reference.md

@@ -73,11 +73,12 @@ console.log(`Fetched ${nfts.length} NFTs`);
 
 **Parameters:**
 
-| Parameter | Type   | Required | Description                             |
-| --------- | ------ | -------- | --------------------------------------- |
-| `slug`    | string | Yes      | Collection slug (identifier)            |
-| `limit`   | number | No       | Number of NFTs to retrieve (1-50)       |
-| `next`    | string | No       | Pagination cursor from previous request |
+| Parameter | Type   | Required | Description                                                                                                                                    |
+| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `slug`    | string | Yes      | Collection slug (identifier)                                                                                                                   |
+| `limit`   | number | No       | Number of NFTs to retrieve (1-50)                                                                                                              |
+| `next`    | string | No       | Pagination cursor from previous request                                                                                                        |
+| `traits`  | TraitFilter[] | No | Trait filters, e.g. `[{ traitType: "Background", value: "Red" }]`. Multiple entries are AND-combined. The SDK JSON-encodes the array for the request. |
 
 **Returns:** `ListNFTsResponse` containing:
 
@@ -405,12 +406,13 @@ const { listings, next } = await openseaSDK.api.getBestListings(
 
 **Parameters:**
 
-| Parameter                | Type    | Required | Description                               |
-| ------------------------ | ------- | -------- | ----------------------------------------- |
-| `collectionSlug`         | string  | Yes      | Collection slug                           |
-| `limit`                  | number  | No       | Number of listings (1-100)                |
-| `next`                   | string  | No       | Pagination cursor                         |
-| `includePrivateListings` | boolean | No       | Include private listings (default: false) |
+| Parameter                | Type    | Required | Description                                                                                                                                 |
+| ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collectionSlug`         | string  | Yes      | Collection slug                                                                                                                             |
+| `limit`                  | number  | No       | Number of listings (1-100)                                                                                                                  |
+| `next`                   | string  | No       | Pagination cursor                                                                                                                           |
+| `includePrivateListings` | boolean | No       | Include private listings (default: false)                                                                                                   |
+| `traits`                 | TraitFilter[] | No | Trait filters, e.g. `[{ traitType: "Background", value: "Red" }]`. Multiple entries are AND-combined. The SDK JSON-encodes the array for the request. |
 
 **Returns:** `GetListingsResponse` with best listings.
 
@@ -1020,10 +1022,10 @@ asset_events.forEach((event) => {
 
 **Parameters:**
 
-| Parameter        | Type          | Required | Description             |
-| ---------------- | ------------- | -------- | ----------------------- |
-| `collectionSlug` | string        | Yes      | Collection slug         |
-| `args`           | GetEventsArgs | No       | Event filtering options |
+| Parameter        | Type          | Required | Description                                                                                                                                                       |
+| ---------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collectionSlug` | string        | Yes      | Collection slug                                                                                                                                                   |
+| `args`           | GetEventsArgs | No       | Event filtering options. `args.traits` is a `TraitFilter[]` (e.g. `[{ traitType: "Background", value: "Red" }]`) to scope events to NFTs matching every trait — the SDK JSON-encodes it for the request. |
 
 **Returns:** `GetEventsResponse` with collection events.
 

developerDocs/getting-started.md

@@ -37,7 +37,7 @@ const { nft } = await openseaSDK.api.getNFT(tokenAddress, tokenId);
 
 **Additional NFT Methods:**
 
-- `getNFTsByCollection(collectionSlug, limit?, next?)` - Get all NFTs in a collection
+- `getNFTsByCollection(collectionSlug, limit?, next?, traits?)` - Get all NFTs in a collection (`traits` is an array of `{ traitType, value }` for server-side filtering — multiple entries are AND-combined)
 - `getNFTsByContract(contractAddress, limit?, next?, chain?)` - Get all NFTs for a contract
 - `getNFTsByAccount(accountAddress, limit?, next?, chain?)` - Get all NFTs owned by an account
 - `getContract(contractAddress, chain?)` - Get contract information

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "10.2.0",
+  "version": "10.2.1",
   "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.2.1",
+    "@opensea/api-types": "^0.2.2",
     "@opensea/seaport-js": "^4.1.1",
     "ethers": "^6.16.0"
   },

src/api/api.ts

@@ -49,6 +49,7 @@ import {
   type GetDropsArgs,
   type GetDropsResponse,
   type GetEventsArgs,
+  type GetEventsByCollectionArgs,
   type GetEventsResponse,
   type GetListingsResponse,
   type GetNFTMetadataResponse,
@@ -75,6 +76,7 @@ import {
   type ResolveAccountResponse,
   type SearchArgs,
   type SearchResponse,
+  type TraitFilter,
   type ValidateMetadataResponse,
 } from "./types"
 
@@ -298,19 +300,22 @@ export class OpenSeaAPI {
    * @param limit The number of listings to return. Must be between 1 and 100. Default: 100
    * @param next The cursor for the next page of results. This is returned from a previous request.
    * @param includePrivateListings Whether to include private listings (default: false)
+   * @param traits Optional {@link TraitFilter} array. Returns 400 if a single trait matches more than 1000 items.
    * @returns The {@link GetListingsResponse} returned by the API.
    */
   public async getBestListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
     includePrivateListings?: boolean,
+    traits?: TraitFilter[],
   ): Promise<GetListingsResponse> {
     return this.listingsAPI.getBestListings(
       collectionSlug,
       limit,
       next,
       includePrivateListings,
+      traits,
     )
   }
 
@@ -473,14 +478,16 @@ export class OpenSeaAPI {
    * @param slug The slug (identifier) of the collection
    * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51.
    * @param next Cursor to retrieve the next page of NFTs
+   * @param traits Optional {@link TraitFilter} array. Returns 400 if a single trait matches more than 1000 items.
    * @returns The {@link ListNFTsResponse} returned by the API.
    */
   public async getNFTsByCollection(
     slug: string,
     limit: number | undefined = undefined,
     next: string | undefined = undefined,
+    traits: TraitFilter[] | undefined = undefined,
   ): Promise<ListNFTsResponse> {
-    return this.nftsAPI.getNFTsByCollection(slug, limit, next)
+    return this.nftsAPI.getNFTsByCollection(slug, limit, next, traits)
   }
 
   /**
@@ -668,14 +675,15 @@ export class OpenSeaAPI {
   }
 
   /**
-   * Gets a list of events for a specific collection.
+   * Gets a list of events for a specific collection. Pass `args.traits` to
+   * filter server-side by item traits (multiple entries are AND-combined).
    * @param collectionSlug The slug (identifier) of the collection.
-   * @param args Query parameters for filtering events.
+   * @param args Query parameters; see {@link GetEventsByCollectionArgs}.
    * @returns The {@link GetEventsResponse} returned by the API.
    */
   public async getEventsByCollection(
     collectionSlug: string,
-    args?: GetEventsArgs,
+    args?: GetEventsByCollectionArgs,
   ): Promise<GetEventsResponse> {
     return this.eventsAPI.getEventsByCollection(collectionSlug, args)
   }
@@ -1093,16 +1101,17 @@ export class OpenSeaAPI {
     let userAbortHandler: (() => void) | undefined
     let signal = options?.signal
     if (options?.timeout !== undefined) {
-      controller = new AbortController()
-      timeoutId = setTimeout(() => controller!.abort(), options.timeout)
+      const ctrl = new AbortController()
+      controller = ctrl
+      timeoutId = setTimeout(() => ctrl.abort(), options.timeout)
       // If user provided their own signal, abort ours if theirs fires
       if (options.signal) {
         if (options.signal.aborted) {
           clearTimeout(timeoutId)
           throw new Error("Request aborted")
         }
         userAbortHandler = () => {
-          controller!.abort()
+          ctrl.abort()
           clearTimeout(timeoutId)
         }
         options.signal.addEventListener("abort", userAbortHandler)

src/api/events.ts

@@ -6,7 +6,12 @@ import {
   getEventsByNFTAPIPath,
 } from "./apiPaths"
 import type { Fetcher } from "./fetcher"
-import type { GetEventsArgs, GetEventsResponse } from "./types"
+import {
+  encodeTraitsParam,
+  type GetEventsArgs,
+  type GetEventsByCollectionArgs,
+  type GetEventsResponse,
+} from "./types"
 
 /**
  * Events-related API operations
@@ -40,15 +45,16 @@ export class EventsAPI {
   }
 
   /**
-   * Gets a list of events for a specific collection.
+   * Gets a list of events for a specific collection. Pass `args.traits` to
+   * filter server-side; the SDK JSON-encodes the trait array for the request.
    */
   async getEventsByCollection(
     collectionSlug: string,
-    args?: GetEventsArgs,
+    args?: GetEventsByCollectionArgs,
   ): Promise<GetEventsResponse> {
     const response = await this.fetcher.get<GetEventsResponse>(
       getEventsByCollectionAPIPath(collectionSlug),
-      args,
+      encodeArgs(args),
     )
     return response
   }
@@ -69,3 +75,13 @@ export class EventsAPI {
     return response
   }
 }
+
+// Returns `undefined` (not `{}`) when no args were passed so the fetcher
+// receives the same shape as before `traits` existed — preserves the
+// pre-feature query string for callers that don't set any args.
+function encodeArgs(args?: GetEventsByCollectionArgs) {
+  if (!args) return args
+  const { traits, ...rest } = args
+  const encoded = encodeTraitsParam(traits)
+  return encoded === undefined ? rest : { ...rest, traits: encoded }
+}

src/api/listings.ts

@@ -7,7 +7,12 @@ import {
   getOrdersAPIPath,
 } from "./apiPaths"
 import type { Fetcher } from "./fetcher"
-import type { GetBestListingResponse, GetListingsResponse } from "./types"
+import {
+  encodeTraitsParam,
+  type GetBestListingResponse,
+  type GetListingsResponse,
+  type TraitFilter,
+} from "./types"
 
 /**
  * Listing-related API operations
@@ -65,17 +70,15 @@ export class ListingsAPI {
   }
 
   /**
-   * Gets the best listings for a given collection.
-   * @param collectionSlug The collection slug
-   * @param limit The number of listings to return
-   * @param next The cursor for pagination
-   * @param includePrivateListings Whether to include private listings (default: false)
+   * Gets the best listings for a given collection. Pass `traits` to filter
+   * server-side by item traits (multiple entries are AND-combined).
    */
   async getBestListings(
     collectionSlug: string,
     limit?: number,
     next?: string,
     includePrivateListings?: boolean,
+    traits?: TraitFilter[],
   ): Promise<GetListingsResponse> {
     const response = await this.fetcher.get<GetListingsResponse>(
       getBestListingsAPIPath(collectionSlug),
@@ -85,6 +88,7 @@ export class ListingsAPI {
         ...(includePrivateListings !== undefined && {
           include_private_listings: includePrivateListings,
         }),
+        traits: encodeTraitsParam(traits),
       },
     )
     return response