What's Changed

• Collection offers made with traitType and traitValue now send the trait as a one-element criteria.traits array instead of the deprecated single criteria.trait field, on both POST /api/v2/offers/build and POST /api/v2/offers. The API treats the two shapes the same, so the resulting offer does not change, and the traitType and traitValue arguments keep working.
• getTopPfpCollections documents args.chains in place of the deprecated chain param of GET /api/v2/pfp/top-collections.
• Depends on @opensea/api-types 0.17.1.

Full Changelog: v12.13.1...v12.13.2

What's Changed

• The README banner now carries the new OpenSea brand, with the new logo on the original banner art. The image is hosted on raw2.seadn.io, so img/banner.png is no longer part of the repo.

Full Changelog: v12.13.0...v12.13.1

What's Changed

The SDK now covers every operation in the OpenSea API v2 spec.

• Collections: api.collections.getCreatorFeeEnforcement, getCollectionPfpProfiles and getTopPfpCollections, plus wallet-authenticated api.walletAuth.getCollectionMetadata, createCollectionPageMediaUpload, setCollectionPricingCurrency, buildCreatorFeeEnforcementTransactions and refreshCollectionMetadata.
• Tools (beta): new api.tools namespace with listTools, searchTools, getTool, getToolActivity and reportToolUsage. getTool returns the tool's inputs and outputs JSON Schemas with their keys as sent; the rest of the response is camelCase. Saved tools stay on api.walletAuth.
• Drops: api.walletAuth.listDropItems(slug, { limit?, next? }), which needs a wallet token with write:drops from the collection owner or an editor.
• Profiles: api.walletAuth.getProfileShelves(address).
• Uploads: uploadToContext, selectUploadContext and UploadContextError finish the presigned upload flows that the five walletAuth.create*Upload helpers start. uploadToContext sends the file to the context's HTTPS storage URL with the global fetch, refuses redirects, never sends your API key or wallet token to storage, and never reads the storage response; errors carry only the HTTP status.
• Stream transport: a caller that removes its handler inside its own join callback no longer causes the next caller on the same topic to miss the join result, and a caller that subscribes from inside a join callback is told once instead of twice. OpenSeaStreamClient only logs from these callbacks, so its behavior is unchanged.
• Requires @opensea/api-types 0.17.0.

Community Contributions

• Stream join-callback fix, thanks @Osraka (opensea-sdk#2029, opensea-sdk#2030)

Full Changelog: v12.12.0...v12.13.0

What's Changed

• Add the collection group NFT search and facets endpoints, which search NFTs across every collection in a group, such as trading_cards, by normalized attributes (franchise, grader, grade, subject, year, set, language, edition, product type):
  • api.nfts.getNFTsByGroup(group, args?) (GET /api/v2/nfts/group/{group}) takes GetNFTsByGroupArgs and returns GetNFTsByGroupResponse.
  • api.nfts.getNFTGroupFacets(group, args?) (GET /api/v2/nfts/group/{group}/facets) takes GetNFTGroupFacetsArgs and returns GetNFTGroupFacetsResponse.
  • Attribute filters are string arrays sent as repeated query parameters. Values of one filter match any of them, and different filters are AND-combined.
• Depends on @opensea/api-types 0.16.1.

import type { OpenSeaSDK } from "@opensea/sdk"
declare const sdk: OpenSeaSDK

const { facets } = await sdk.api.nfts.getNFTGroupFacets("trading_cards", {
  facetTypes: ["grader"],
  franchise: ["Pokemon"],
})
const { nfts, next } = await sdk.api.nfts.getNFTsByGroup("trading_cards", {
  franchise: ["Pokemon"],
  grader: ["PSA", "CGC"],
  isListed: true,
  sortBy: "price",
  sortDirection: "asc",
})

Full Changelog: v12.11.4...v12.12.0

What's Changed

• Sign-in with Ethereum messages now accept the "Platform Terms of Service" instead of the "OpenSea Terms of Service". The linked URLs are unchanged.
• Depends on @opensea/api-types 0.16.1.

Full Changelog: v12.11.3...v12.11.4

What's Changed

• Stream: removing a listener now also drops that caller's onSubscribed and onSubscribeError callbacks once it has no handlers left on the topic. Before, a caller that unsubscribed from a topic another listener kept alive was still notified on every rejoin, and repeated add and remove cycles kept growing the topic's callback list.
• Docs: _createRateLimitError has its own JSDoc again. The Avalanche case of getListingPaymentToken labels its address WAVAX. The quick start, overview and contributing guides state Node 22 as the minimum, matching engines.node.
• Depends on @opensea/api-types 0.16.0.

Community Contributions

• Stream callback bug report and reproduction, thanks @Osraka (opensea-sdk#2027)
• _createRateLimitError JSDoc and Node 22 docs, thanks @dj-jarvis (opensea-sdk#2023, opensea-sdk#2024)
• Avalanche token label, thanks @qsysvcore (opensea-sdk#2026)

Full Changelog: v12.11.2...v12.11.3

What's Changed

• Stream: when a second subscriber joins a collection topic that is already joined and asks for event types outside the current filter, the server-side filter now widens before that subscriber is notified. Its onSubscribed fires once, after the widened join is accepted, instead of once before and once after. A throw from that callback is reported through onError instead of escaping subscribe() and skipping the widen.
• Docs: the package entry @example now passes apiKey.
• Docs: the snakeizeKeysDeep JSDoc gives the real output for URL (u_r_l, not url). The 11.0.0 changelog entry had the same wrong example and is corrected too.
• Docs: the "Buying Items" and "Accepting Offers" examples in the getting-started guide no longer import an unused OrderSide.

Community Contributions

• Stream filter widening and late onSubscribed handling, thanks @Osraka (opensea-sdk#2022)
• apiKey in the entry-point example, thanks @CryptAm (opensea-sdk#2020)
• snakeizeKeysDeep acronym example, thanks @zunixport (opensea-sdk#2019)
• Unused OrderSide imports in getting-started, thanks @CryptAm (opensea-sdk#2021)

Full Changelog: v12.11.1...v12.11.2

What's Changed

• Stream transport: a join reply that arrives after the join was replaced (filter widen, rejoin) or after the topic was unsubscribed no longer fires onSubscribed or onSubscribeError a second time.
• Snakeize<T> now matches what snakeizeKeysDeep writes at runtime: no underscore before digits (chain2Id is chain2_id) and no doubled underscore on keys that are already snake_case (order_hash stays order_hash).
• hasErrorCode returns false for null and undefined instead of throwing a TypeError.
• CI now type-checks the shipped declarations with skipLibCheck: false.

Community Contributions

• Stale stream join replies double-firing subscribe callbacks, thanks @bayrakdarerdem (opensea-sdk#2018)
• Snakeize<T> digit handling, thanks @zunixport (opensea-sdk#2015)
• Nullish-safe hasErrorCode, thanks @zunixport (opensea-sdk#2014)
• Declarations check on this repo's CI, reported by @Osraka (opensea-sdk#2016)

Full Changelog: v12.11.0...v12.11.1

What's Changed

• Add walletAuth.saveDropItemMediaBatch(slug, { uploadBatchId, filenames }), which saves a drop's items from one upload batch by filename, up to 15,000. Pass the same uploadBatchId, a UUID you generate once per set of files, to every walletAuth.createDropItemMediaUpload call for that set.
• walletAuth.saveDropItemMedia, which saves by media token, is deprecated and keeps working.
• Depends on @opensea/api-types 0.15.0.

Full Changelog: v12.10.2...v12.11.0

What's Changed

• api.tokens.getTokenHolders() now types and documents the holder distribution: totalHolders, topHoldersCount (the measured top cohort, 250 or every holder when there are fewer), topHoldersConcentration (percent of eligible supply that cohort holds, after mint, LP, CEX and burn holdings are excluded), healthScore and healthLabel. distribution is null for tokens the API has not measured. topOnePercentConcentration is deprecated in favor of topHoldersConcentration. The new fields come from @opensea/api-types 0.14.2.

import { Chain, type OpenSeaSDK } from "@opensea/sdk"

declare const sdk: OpenSeaSDK

const { distribution } = await sdk.api.tokens.getTokenHolders(
  Chain.Base,
  "0x0b3e328455c4059eeb9e3f84b5543f74e24e7e1b",
)
if (distribution) {
  console.log(distribution.topHoldersConcentration, distribution.topHoldersCount)
}

• The published declarations typecheck with skipLibCheck: false. usesNativeStablecoinOffers(chain) declared a type predicate TypeScript rejects (TS2677); it is now chain is Chain.Arc | Chain.StableChain. Runtime behavior is unchanged.

Full Changelog: v12.10.1...v12.10.2