Release v11.2.0

Origin-SHA: 12ec70653ffc71110241b58761c01985d9abd5b7

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: ryanio

AGENTS.md

@@ -23,6 +23,8 @@ pnpm run check-types   # TypeScript type checking (stricter tsconfig)
 | `src/viem.ts` | `OpenSeaViemSDK` — viem entry point |
 | `src/types.ts` | Public types: `Chain` enum, `Amount`, order/event types |
 | `src/constants.ts` | Math and Ethereum constants (basis points, addresses, etc.) |
+| `src/auth/` | `OpenSeaAuth` — SIWE-based wallet authentication (nonce, sign-in, scoped JWTs, auto-refresh) |
+| `src/scopes.ts` | `OPENSEA_SCOPES` — OAuth-style API scope string constants |
 | `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 |
@@ -41,7 +43,7 @@ pnpm run check-types   # TypeScript type checking (stricter tsconfig)
 
 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`.
+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. `getOfferPaymentToken` and `getListingPaymentToken` use exhaustive `switch` statements whose `default` branch assigns `chain` to a `never` binding, so `pnpm check-types` fails if a new `Chain` is added without a payment-token case — either map it to a real token or mark it unsupported explicitly (like `Chain.Solana` / `Chain.Hyperliquid`, which throw a clear "not supported" error). `getNativeWrapTokenAddress` delegates to `getOfferPaymentToken` except for `Chain.Polygon`, so it is covered automatically unless the wrap token differs from the offer token. `test/utils/chain.spec.ts` also iterates every `Chain` value at runtime as a second guard and runs in `pnpm test`. When adding a chain, also update `scripts/chain-data.json` at the **monorepo root** and run `pnpm sync-chains` from the monorepo root.
 
 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.
 

CHANGELOG.md

@@ -1,5 +1,35 @@
 # @opensea/sdk
 
+## 11.2.0
+
+### Minor Changes
+
+- ef89be8: Add SIWE authentication helpers: `OpenSeaAuth` class with authenticate, getValidToken, and revoke methods. Support `authToken` and `authBaseUrl` in `OpenSeaAPIConfig` for wallet-authenticated endpoints.
+- e61a57c: Add `OpenSeaOAuth` OAuth 2.1 helper (authorization-code + PKCE, device authorization grant, refresh, and revoke) for keyless login against the OpenSea authorization server. Exposes `OpenSeaOAuthConfig`, `OAuthToken`, and related types, plus a `decodeJwtPayload` utility for reading token claims.
+- ef89be8: Add `OPENSEA_SCOPES`, `OpenSeaScope`, and `ALL_SCOPES` exports — scope constants derived from the OpenAPI spec's `AuthScope` schema (via `@opensea/api-types`), with compile-time assertions that fail the build if they drift from the spec.
+- c460fc1: Add wallet trading P&L methods to `OpenSeaAPI`: `getWalletPnl`,
+  `getWalletClosedPositions`, and `getWalletTokenTransfers`, with camelized
+  `WalletPnlResponse`, `ClosedPositionsResponse`, and
+  `PositionTokenTransfersResponse` types plus `WalletClosedPositionsArgs` /
+  `WalletTokenTransfersArgs` query args.
+
+### Patch Changes
+
+- b816727: Add missing chain payment-token mappings for Soneium and AnimeChain, and make Solana/Hyperliquid fail fast with clear unsupported-chain errors for OpenSea Seaport offer/listing helpers. This fixes the chain helper drift tracked in ProjectOpenSea/opensea-js#1975.
+- c9d8cb1: Recreate the community fixes from ProjectOpenSea/opensea-js#1974 and ProjectOpenSea/opensea-js#1976: validate `amount` before `parseUnits` in `_getPriceParameters`, and reject `cancelOrders` batches that mix protocol addresses. Also add a runtime chain-helper exhaustiveness guard so new `Chain` values are consciously categorized.
+- e59df7f: Sync OpenAPI spec: add tool activity endpoint, `robinhood` chain, `source`/`collection` search filters, `calldata_suffix` on fulfillment, SIWX wallet-link endpoint (`POST /api/v2/accounts/wallets/siwx` with `LinkWalletSiwxRequest`/`WalletLinkResponse`), re-published `GET /api/v2/account/{address}/favorites`, and the new `write:wallets` auth scope (also added to the SDK's `OPENSEA_SCOPES`)
+- Updated dependencies [e59df7f]
+- Updated dependencies [c460fc1]
+- Updated dependencies [ef89be8]
+  - @opensea/api-types@0.6.0
+
+## 11.1.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @opensea/api-types@0.5.0
+
 ## 11.1.1
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "11.1.1",
+  "version": "11.2.0",
   "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.4.3",
+    "@opensea/api-types": "^0.6.0",
     "@opensea/seaport-js": "^4.1.1",
     "ethers": "^6.16.0"
   },

src/api/accounts.ts

@@ -11,14 +11,19 @@ import {
   getProfileOffersPath,
   getProfileOffersReceivedPath,
   getResolveAccountPath,
+  getWalletClosedPositionsPath,
+  getWalletPnlPath,
+  getWalletTokenTransfersPath,
 } from "./apiPaths"
 import type { Fetcher } from "./fetcher"
 import type {
+  ClosedPositionsResponse,
   GetAccountTokensArgs,
   GetAccountTokensResponse,
   PortfolioArgs,
   PortfolioHistoryResponse,
   PortfolioStatsResponse,
+  PositionTokenTransfersResponse,
   ProfileCollectionsArgs,
   ProfileCollectionsResponse,
   ProfileFavoritesArgs,
@@ -27,6 +32,9 @@ import type {
   ProfileOffersResponse,
   ProfileOrdersArgs,
   ResolveAccountResponse,
+  WalletClosedPositionsArgs,
+  WalletPnlResponse,
+  WalletTokenTransfersArgs,
 } from "./types"
 
 function joinArray(value: string[] | undefined): string | undefined {
@@ -187,6 +195,39 @@ export class AccountsAPI {
     )
   }
 
+  /**
+   * Get aggregated trading P&L (realized + unrealized) for an account.
+   */
+  async getWalletPnl(address: string): Promise<WalletPnlResponse> {
+    return this.fetcher.get<WalletPnlResponse>(getWalletPnlPath(address))
+  }
+
+  /**
+   * Get closed (realized) trading positions for an account.
+   */
+  async getWalletClosedPositions(
+    address: string,
+    args?: WalletClosedPositionsArgs,
+  ): Promise<ClosedPositionsResponse> {
+    return this.fetcher.get<ClosedPositionsResponse>(
+      getWalletClosedPositionsPath(address),
+      args,
+    )
+  }
+
+  /**
+   * Get the token transfers contributing to a wallet's position in a currency.
+   */
+  async getWalletTokenTransfers(
+    address: string,
+    args: WalletTokenTransfersArgs,
+  ): Promise<PositionTokenTransfersResponse> {
+    return this.fetcher.get<PositionTokenTransfersResponse>(
+      getWalletTokenTransfersPath(address),
+      args,
+    )
+  }
+
   /**
    * Get collections owned by an account.
    */

src/api/api.ts

@@ -38,6 +38,7 @@ import {
   type BatchTokensRequest,
   type BuildOfferResponse,
   type CancelOrderResponse,
+  type ClosedPositionsResponse,
   type CollectionBatchResponse,
   type CollectionFloorPricesArgs,
   type CollectionHoldersArgs,
@@ -98,6 +99,7 @@ import {
   type PortfolioArgs,
   type PortfolioHistoryResponse,
   type PortfolioStatsResponse,
+  type PositionTokenTransfersResponse,
   type PriceHistoryResponse,
   type ProfileCollectionsArgs,
   type ProfileCollectionsResponse,
@@ -128,6 +130,9 @@ import {
   type TransferRequest,
   type TransferResponse,
   type ValidateMetadataResponse,
+  type WalletClosedPositionsArgs,
+  type WalletPnlResponse,
+  type WalletTokenTransfersArgs,
 } from "./types"
 
 /**
@@ -149,6 +154,7 @@ export class OpenSeaAPI {
   public logger: (arg: string) => void
 
   private apiKey: string | undefined
+  private authToken: string | undefined
   private chain: Chain
 
   // Specialized API clients
@@ -173,6 +179,7 @@ export class OpenSeaAPI {
    */
   constructor(config: OpenSeaAPIConfig, logger?: (arg: string) => void) {
     this.apiKey = config.apiKey
+    this.authToken = config.authToken
     this.chain = config.chain ?? Chain.Mainnet
 
     if (config.apiBaseUrl) {
@@ -1284,6 +1291,33 @@ export class OpenSeaAPI {
     return this.accountsAPI.getProfileCollections(address, args)
   }
 
+  /**
+   * Get aggregated trading P&L (realized + unrealized) for an account.
+   */
+  public async getWalletPnl(address: string): Promise<WalletPnlResponse> {
+    return this.accountsAPI.getWalletPnl(address)
+  }
+
+  /**
+   * Get closed (realized) trading positions for an account.
+   */
+  public async getWalletClosedPositions(
+    address: string,
+    args?: WalletClosedPositionsArgs,
+  ): Promise<ClosedPositionsResponse> {
+    return this.accountsAPI.getWalletClosedPositions(address, args)
+  }
+
+  /**
+   * Get the token transfers contributing to a wallet's position in a currency.
+   */
+  public async getWalletTokenTransfers(
+    address: string,
+    args: WalletTokenTransfersArgs,
+  ): Promise<PositionTokenTransfersResponse> {
+    return this.accountsAPI.getWalletTokenTransfers(address, args)
+  }
+
   /**
    * Generic fetch method for any API endpoint with automatic rate limit retry
    * @param apiPath Path to URL endpoint under API
@@ -1382,12 +1416,14 @@ export class OpenSeaAPI {
       // Kept as "opensea-js" for server-side analytics continuity after package rename
       "x-app-id": "opensea-js",
       ...(this.apiKey ? { "X-API-KEY": this.apiKey } : {}),
+      ...(this.authToken ? { Authorization: `Bearer ${this.authToken}` } : {}),
       ...(body != null ? { "Content-Type": "application/json" } : {}),
       ...headers,
     }
 
     const sanitizedHeaders = { ...mergedHeaders }
     delete sanitizedHeaders["X-API-KEY"]
+    delete sanitizedHeaders.Authorization
     this.logger(
       `Sending request: ${url} ${JSON.stringify({
         method: body != null ? "POST" : "GET",

src/api/apiPaths.ts

@@ -373,6 +373,18 @@ export const getProfileFavoritesPath = (address: string) => {
   return `${API_V2_PREFIX}/account/${address}/favorites`
 }
 
+export const getWalletPnlPath = (address: string) => {
+  return `${API_V2_PREFIX}/account/${address}/pnl`
+}
+
+export const getWalletClosedPositionsPath = (address: string) => {
+  return `${API_V2_PREFIX}/account/${address}/pnl/closed-positions`
+}
+
+export const getWalletTokenTransfersPath = (address: string) => {
+  return `${API_V2_PREFIX}/account/${address}/pnl/token-transfers`
+}
+
 export const getProfileCollectionsPath = (address: string) => {
   return `${API_V2_PREFIX}/account/${address}/collections`
 }

src/api/types.ts

@@ -1173,6 +1173,7 @@ import type {
   BatchCollectionsRequest as ApiBatchCollectionsRequest,
   BatchNftsRequest as ApiBatchNftsRequest,
   BatchTokensRequest as ApiBatchTokensRequest,
+  ClosedPositionsResponse as ApiClosedPositionsResponse,
   CollectionBatchResponse as ApiCollectionBatchResponse,
   CollectionHoldersPaginatedResponse as ApiCollectionHoldersPaginatedResponse,
   CollectionOfferAggregatesPaginatedResponse as ApiCollectionOfferAggregatesPaginatedResponse,
@@ -1193,6 +1194,7 @@ import type {
   OwnersPaginatedResponse as ApiOwnersPaginatedResponse,
   PortfolioHistoryResponse as ApiPortfolioHistoryResponse,
   PortfolioStatsResponse as ApiPortfolioStatsResponse,
+  PositionTokenTransfersResponse as ApiPositionTokenTransfersResponse,
   PriceHistoryResponse as ApiPriceHistoryResponse,
   ProfileCollectionsResponse as ApiProfileCollectionsResponse,
   SwapTransactionResponse as ApiSwapTransactionResponse,
@@ -1202,6 +1204,7 @@ import type {
   TokenSwapActivityPaginatedResponse as ApiTokenSwapActivityPaginatedResponse,
   TransferRequest as ApiTransferRequest,
   TransferResponse as ApiTransferResponse,
+  WalletPnlResponse as ApiWalletPnlResponse,
 } from "@opensea/api-types"
 
 // Request types — camelized consumer view. The fetcher snakeizes the body on
@@ -1238,6 +1241,10 @@ export type OhlcvResponse = Camelize<ApiOhlcvResponse>
 export type OwnersPaginatedResponse = Camelize<ApiOwnersPaginatedResponse>
 export type PortfolioHistoryResponse = Camelize<ApiPortfolioHistoryResponse>
 export type PortfolioStatsResponse = Camelize<ApiPortfolioStatsResponse>
+export type WalletPnlResponse = Camelize<ApiWalletPnlResponse>
+export type ClosedPositionsResponse = Camelize<ApiClosedPositionsResponse>
+export type PositionTokenTransfersResponse =
+  Camelize<ApiPositionTokenTransfersResponse>
 export type PriceHistoryResponse = Camelize<ApiPriceHistoryResponse>
 export type ProfileCollectionsResponse = Camelize<ApiProfileCollectionsResponse>
 export type SwapTransactionResponse = Camelize<ApiSwapTransactionResponse>
@@ -1368,6 +1375,35 @@ export interface ProfileFavoritesArgs {
   chains?: string[]
 }
 
+/**
+ * Query args for the wallet closed-positions (realized P&L) endpoint.
+ * @category API Query Args
+ */
+export interface WalletClosedPositionsArgs {
+  /** Sort field for the returned positions. */
+  sortBy?: string
+  /** Max number of positions to return (default 20). */
+  limit?: number
+  /** Cursor for the next page of results. */
+  next?: string
+}
+
+/**
+ * Query args for the wallet position token-transfers endpoint. `contractAddress`
+ * and `chain` identify the currency position to inspect and are required.
+ * @category API Query Args
+ */
+export interface WalletTokenTransfersArgs {
+  /** Contract address of the currency whose position transfers to fetch. */
+  contractAddress: string
+  /** Chain the currency lives on (e.g. `ethereum`, `base`). */
+  chain: string
+  /** Max number of transfers to return (default 20). */
+  limit?: number
+  /** Cursor for the next page of results. */
+  next?: string
+}
+
 /**
  * Query args for the account profile collections endpoint.
  * @category API Query Args