@opensea/sdk 9.0.0

package/src/types.ts

@@ -0,0 +1,413 @@
+import type { ChainIdentifier } from "@opensea/api-types"
+import type { BigNumberish } from "ethers"
+import type { Listing, Offer } from "./api/types"
+import type { OrderV2 } from "./orders/types"
+
+/**
+ * Events emitted by the SDK which can be used by frontend applications
+ * to update state or show useful messages to users.
+ * @category Events
+ */
+export enum EventType {
+  /**
+   * Emitted when the transaction is sent to the network and the application
+   * is waiting for the transaction to be mined.
+   */
+  TransactionCreated = "TransactionCreated",
+  /**
+   * Emitted when the transaction is mined and confirmed.
+   */
+  TransactionConfirmed = "TransactionConfirmed",
+  /**
+   * Emitted when the transaction has failed to be submitted.
+   */
+  TransactionDenied = "TransactionDenied",
+  /**
+   * Emitted when the transaction has failed to be mined.
+   */
+  TransactionFailed = "TransactionFailed",
+  /**
+   * Emitted when the {@link OpenSeaSDK.wrapEth} method is called.
+   */
+  WrapEth = "WrapEth",
+  /**
+   * Emitted when the {@link OpenSeaSDK.unwrapWeth} method is called.
+   */
+  UnwrapWeth = "UnwrapWeth",
+  /**
+   * Emitted when fulfilling a public or private order.
+   */
+  MatchOrders = "MatchOrders",
+  /**
+   * Emitted when the {@link OpenSeaSDK.cancelOrder} method is called.
+   */
+  CancelOrder = "CancelOrder",
+  /**
+   * Emitted when the {@link OpenSeaSDK.approveOrder} method is called.
+   */
+  ApproveOrder = "ApproveOrder",
+  /**
+   * Emitted when the {@link OpenSeaSDK.transfer} method is called.
+   */
+  Transfer = "Transfer",
+  /**
+   * Emitted when the {@link OpenSeaSDK.batchApproveAssets} method is called.
+   */
+  ApproveAllAssets = "ApproveAllAssets",
+}
+
+/**
+ * Data that gets sent with each {@link EventType}
+ * @category Events
+ */
+export interface EventData {
+  /**
+   * Wallet address of the user who initiated the event.
+   */
+  accountAddress?: string
+  /**
+   * Amount of ETH sent when wrapping or unwrapping.
+   */
+  amount?: BigNumberish
+  /**
+   * The transaction hash of the event.
+   */
+  transactionHash?: string
+  /**
+   * The {@link EventType} of the event.
+   */
+  event?: EventType
+  /**
+   * Error which occurred when transaction was denied or failed.
+   */
+  error?: unknown
+  /**
+   * The {@link OrderV2} object.
+   */
+  orderV2?: OrderV2
+  /**
+   * The order as returned by the API ({@link Offer} or {@link Listing}).
+   */
+  order?: Offer | Listing
+  /**
+   * Array of assets for bulk transfer and batch approval operations.
+   */
+  assets?: Array<{
+    asset: AssetWithTokenStandard
+    toAddress?: string
+    amount?: BigNumberish
+  }>
+}
+
+/**
+ * OpenSea API configuration object
+ * @param chain `Chain` to use. Defaults to Ethereum Mainnet (`Chain.Mainnet`)
+ * @param apiKey API key to use
+ * @param apiBaseUrl Optional base URL to use for the API
+ */
+export interface OpenSeaAPIConfig {
+  chain?: Chain
+  apiKey?: string
+  apiBaseUrl?: string
+}
+
+/**
+ * Each of the possible chains that OpenSea supports.
+ * ⚠️NOTE: When adding to this list, also update:
+ * - `scripts/chain-data.json` + run `pnpm sync-chains` (generates `getChainId` mapping)
+ * - `getListingPaymentToken`
+ * - `getOfferPaymentToken`
+ * - `getNativeWrapTokenAddress` (if getOfferPaymentToken isn't the wrapped native asset)
+ */
+export enum Chain {
+  Mainnet = "ethereum",
+  Polygon = "polygon",
+  Base = "base",
+  Blast = "blast",
+  Arbitrum = "arbitrum",
+  Avalanche = "avalanche",
+  Optimism = "optimism",
+  Solana = "solana",
+  Zora = "zora",
+  Sei = "sei",
+  B3 = "b3",
+  BeraChain = "bera_chain",
+  ApeChain = "ape_chain",
+  Flow = "flow",
+  Ronin = "ronin",
+  Abstract = "abstract",
+  Shape = "shape",
+  Unichain = "unichain",
+  Gunzilla = "gunzilla",
+  HyperEVM = "hyperevm",
+  Somnia = "somnia",
+  Monad = "monad",
+  MegaETH = "megaeth",
+  Soneium = "soneium",
+  Hyperliquid = "hyperliquid",
+  AnimeChain = "animechain",
+  Ink = "ink",
+}
+
+// Compile-time check: every ChainIdentifier from the API spec must be assignable to Chain.
+// If the API adds a new chain, this will error — add it to the Chain enum above.
+// The SDK may have chains not yet in the API spec (e.g. testnets, upcoming chains).
+type _AssertAPIChainsCovered = ChainIdentifier extends `${Chain}` ? true : never
+
+const _assertAPIChainsCovered: _AssertAPIChainsCovered = true
+
+/**
+ * Order side: listing (ask) or offer (bid)
+ */
+export enum OrderSide {
+  LISTING = "ask",
+  OFFER = "bid",
+}
+
+/**
+ * Token standards
+ */
+export enum TokenStandard {
+  ERC20 = "ERC20",
+  ERC721 = "ERC721",
+  ERC1155 = "ERC1155",
+}
+
+/**
+ * The collection's approval status within OpenSea.
+ * Can be one of:
+ * - not_requested: brand new collections
+ * - requested: collections that requested safelisting on our site
+ * - approved: collections that are approved on our site and can be found in search results
+ * - verified: verified collections
+ */
+export enum SafelistStatus {
+  NOT_REQUESTED = "not_requested",
+  REQUESTED = "requested",
+  APPROVED = "approved",
+  VERIFIED = "verified",
+  DISABLED_TOP_TRENDING = "disabled_top_trending",
+}
+
+/**
+ * Collection fees
+ * @category API Models
+ */
+export interface Fee {
+  fee: number
+  recipient: string
+  required: boolean
+}
+
+/**
+ * Generic Blockchain Asset.
+ * @category API Models
+ */
+export interface Asset {
+  /** The asset's token ID, or null if ERC-20 */
+  tokenId: string | null
+  /** The asset's contract address */
+  tokenAddress: string
+  /** The token standard (e.g. "ERC721") for this asset */
+  tokenStandard?: TokenStandard
+  /** Optional for ENS names */
+  name?: string
+  /** Optional for fungible items */
+  decimals?: number
+}
+
+/**
+ * Generic Blockchain Asset, with tokenId required.
+ * @category API Models
+ */
+export interface AssetWithTokenId extends Asset {
+  /** The asset's token ID */
+  tokenId: string
+}
+
+/**
+ * Generic Blockchain Asset, with tokenStandard required.
+ * @category API Models
+ */
+export interface AssetWithTokenStandard extends Asset {
+  /** The token standard (e.g. "ERC721") for this asset */
+  tokenStandard: TokenStandard
+}
+
+interface OpenSeaCollectionStatsIntervalData {
+  interval: "one_day" | "seven_day" | "thirty_day"
+  volume: number
+  volume_diff: number
+  volume_change: number
+  sales: number
+  sales_diff: number
+  average_price: number
+}
+
+/**
+ * OpenSea Collection Stats
+ * @category API Models
+ */
+export interface OpenSeaCollectionStats {
+  total: {
+    volume: number
+    sales: number
+    average_price: number
+    num_owners: number
+    market_cap: number
+    floor_price: number
+    floor_price_symbol: string
+  }
+  intervals: OpenSeaCollectionStatsIntervalData[]
+}
+
+export interface RarityStrategy {
+  strategyId: string
+  strategyVersion: string
+  calculatedAt: string
+  maxRank: number
+  tokensScored: number
+}
+
+/**
+ * OpenSea collection metadata.
+ * @category API Models
+ */
+export interface OpenSeaCollection {
+  /** Name of the collection */
+  name: string
+  /** The identifier (slug) of the collection */
+  collection: string
+  /** Description of the collection */
+  description: string
+  /** Image for the collection */
+  imageUrl: string
+  /** Banner image for the collection */
+  bannerImageUrl: string
+  /** Owner address of the collection */
+  owner: string
+  /** The collection's safelist status */
+  safelistStatus: SafelistStatus
+  /** The category of the collection */
+  category: string
+  /** If the collection is disabled */
+  isDisabled: boolean
+  /** If the collection is NSFW (not safe for work) */
+  isNSFW: boolean
+  /** If trait offers are enabled */
+  traitOffersEnabled: boolean
+  /** If collection offers are enabled */
+  collectionOffersEnabled: boolean
+  /** The OpenSea url for the collection */
+  openseaUrl: string
+  /** The project url for the collection */
+  projectUrl: string
+  /** The wiki url for the collection */
+  wikiUrl: string
+  /** The discord url for the collection */
+  discordUrl: string
+  /** The telegram url for the collection */
+  telegramUrl: string
+  /** The twitter username for the collection */
+  twitterUsername: string
+  /** The instagram username for the collection */
+  instagramUsername: string
+  /** The contracts for the collection */
+  contracts: { address: string; chain: Chain }[]
+  /** Accounts allowed to edit this collection */
+  editors: string[]
+  /** The fees for the collection */
+  fees: Fee[]
+  /** The rarity strategy for the collection */
+  rarity: RarityStrategy | null
+  /** Pricing currencies for listings and offers in this collection */
+  pricingCurrencies?: PricingCurrencies
+  /** The total supply of the collection (minted minus burned) */
+  totalSupply: number
+  /** The number of unique items in the collection */
+  uniqueItemCount: number
+  /** The created date of the collection */
+  createdDate: string
+  /** When defined, the zone required for orders for the collection */
+  requiredZone?: string
+}
+
+/**
+ * Full annotated Fungible Token spec with OpenSea metadata
+ */
+export interface OpenSeaPaymentToken {
+  name: string
+  symbol: string
+  decimals: number
+  address: string
+  chain: Chain
+  imageUrl?: string
+  ethPrice?: string
+  usdPrice?: string
+}
+
+/**
+ * Pricing currencies for a collection, defining default currencies for listings and offers.
+ * @category API Models
+ */
+export interface PricingCurrencies {
+  listingCurrency?: OpenSeaPaymentToken
+  offerCurrency?: OpenSeaPaymentToken
+}
+
+/**
+ * OpenSea Account
+ * @category API Models
+ */
+export interface OpenSeaAccount {
+  address: string
+  username: string
+  profileImageUrl: string
+  bannerImageUrl: string
+  website: string
+  socialMediaAccounts: SocialMediaAccount[]
+  bio: string
+  joinedDate: string
+}
+/**
+ * Social media account
+ * @category API Models
+ */
+export interface SocialMediaAccount {
+  platform: string
+  username: string
+}
+
+/**
+ * Enhanced Error type for rate limit errors that includes retry-after information
+ * @category API Models
+ */
+export interface OpenSeaRateLimitError extends Error {
+  /** The HTTP status code of the error response */
+  statusCode?: number
+  /** The number of seconds to wait before retrying the request */
+  retryAfter?: number
+  /** The response body from the API */
+  responseBody?: unknown
+}
+
+/**
+ * Options for controlling HTTP request behavior.
+ * @category API Models
+ */
+export interface RequestOptions {
+  /**
+   * Request timeout in milliseconds.
+   * If the request takes longer than this, it will be aborted.
+   */
+  timeout?: number
+  /**
+   * An AbortSignal to cancel the request.
+   * Useful for implementing custom cancellation logic or timeouts.
+   * @example
+   * const controller = new AbortController();
+   * setTimeout(() => controller.abort(), 5000);
+   * await api.post('/path', body, headers, { signal: controller.signal });
+   */
+  signal?: AbortSignal
+}

package/src/utils/chain.ts

@@ -0,0 +1,224 @@
+import { CROSS_CHAIN_SEAPORT_V1_6_ADDRESS } from "@opensea/seaport-js/lib/constants"
+import {
+  ALTERNATE_CONDUIT_ADDRESS,
+  ALTERNATE_CONDUIT_KEY,
+  ALTERNATE_FEE_RECIPIENT,
+  ALTERNATE_SEAPORT_V1_6_ADDRESS,
+  ALTERNATE_SIGNED_ZONE_V2_ADDRESS,
+  GUNZILLA_FEE_RECIPIENT,
+  OPENSEA_CONDUIT_ADDRESS,
+  OPENSEA_CONDUIT_ADDRESS_2,
+  OPENSEA_CONDUIT_KEY,
+  OPENSEA_CONDUIT_KEY_2,
+  OPENSEA_FEE_RECIPIENT,
+  OPENSEA_SIGNED_ZONE_V2,
+  SOMNIA_FEE_RECIPIENT,
+  WPOL_ADDRESS,
+} from "../constants"
+import { Chain } from "../types"
+import { CHAIN_ID_MAP } from "./chainIds.generated"
+
+/**
+ * Checks if a chain uses the alternate protocol addresses.
+ * These chains use non-standard Seaport, conduit, and signed zone deployments.
+ * @param chain The chain to check
+ * @returns True if the chain uses alternate protocol addresses
+ */
+export const usesAlternateProtocol = (chain: Chain): boolean =>
+  chain === Chain.Gunzilla || chain === Chain.Somnia || chain === Chain.MegaETH
+
+/**
+ * Gets the chain ID for a given chain.
+ *
+ * Uses the generated CHAIN_ID_MAP from scripts/chain-data.json.
+ * To add a new chain, update chain-data.json and run `pnpm sync-chains`.
+ *
+ * @param chain The chain to get the ID for
+ * @returns The chain ID as a string
+ */
+export const getChainId = (chain: Chain): string => {
+  const id = CHAIN_ID_MAP[chain]
+  if (id === undefined) throw new Error(`Unknown chainId for ${chain}`)
+  return id
+}
+
+/**
+ * Returns the default currency for offers on the given chain.
+ * @param chain The chain to get the offer payment token for
+ * @returns The token address for offers
+ */
+export const getOfferPaymentToken = (chain: Chain) => {
+  switch (chain) {
+    case Chain.Mainnet:
+      return "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" // WETH
+    case Chain.Polygon:
+      return "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619" // WETH
+    case Chain.Avalanche:
+      return "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7" // WAVAX
+    case Chain.Arbitrum:
+      return "0x82af49447d8a07e3bd95bd0d56f35241523fbab1" // WETH
+    case Chain.Blast:
+      return "0x4300000000000000000000000000000000000004" // WETH
+    // MegaETH and OP Chains have WETH at the same address
+    case Chain.MegaETH:
+    case Chain.Base:
+    case Chain.Optimism:
+    case Chain.Zora:
+    case Chain.B3:
+    case Chain.Shape:
+    case Chain.Unichain:
+    case Chain.Ink:
+      return "0x4200000000000000000000000000000000000006" // WETH
+    case Chain.BeraChain:
+      return "0x6969696969696969696969696969696969696969" // WBERA
+    case Chain.Sei:
+      return "0xe30fedd158a2e3b13e9badaeabafc5516e95e8c7" // WSEI
+    case Chain.Flow:
+      return "0xd3bf53dac106a0290b0483ecbc89d40fcc961f3e" // WFLOW
+    case Chain.ApeChain:
+      return "0x48b62137edfa95a428d35c09e44256a739f6b557" // WAPE
+    case Chain.Ronin:
+      return "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4" // WRON
+    case Chain.Abstract:
+      return "0x3439153eb7af838ad19d56e1571fbd09333c2809" // WETH
+    case Chain.Gunzilla:
+      return "0x5aad7bba61d95c2c4e525a35f4062040264611f1" // WGUN
+    case Chain.HyperEVM:
+      return "0x5555555555555555555555555555555555555555" // WHYPE
+    case Chain.Somnia:
+      return "0x046ede9564a72571df6f5e44d0405360c0f4dcab" // WSOMI
+    case Chain.Monad:
+      return "0x3bd359c1119da7da1d913d1c4d2b7c461115433a" // WMON
+    default:
+      throw new Error(`Unknown offer currency for ${chain}`)
+  }
+}
+
+/**
+ * Returns the default currency for listings on the given chain.
+ * @param chain The chain to get the listing payment token for
+ * @returns The token address for listings
+ */
+export const getListingPaymentToken = (chain: Chain) => {
+  switch (chain) {
+    case Chain.Mainnet:
+    case Chain.Somnia:
+    case Chain.HyperEVM:
+    case Chain.Arbitrum:
+    case Chain.Blast:
+    case Chain.Base:
+    case Chain.Optimism:
+    case Chain.Zora:
+    case Chain.B3:
+    case Chain.Abstract:
+    case Chain.Shape:
+    case Chain.Unichain:
+    case Chain.Monad:
+    case Chain.MegaETH:
+    case Chain.Ink:
+      return "0x0000000000000000000000000000000000000000" // ETH
+    case Chain.Polygon:
+      return "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619" // WETH
+    case Chain.Avalanche:
+      return "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7" // WETH
+    case Chain.BeraChain:
+      return "0x0000000000000000000000000000000000000000" // BERA
+    case Chain.Sei:
+      return "0x0000000000000000000000000000000000000000" // SEI
+    case Chain.Flow:
+      return "0xd3bf53dac106a0290b0483ecbc89d40fcc961f3e" // WETH
+    case Chain.ApeChain:
+      return "0x0000000000000000000000000000000000000000" // APE
+    case Chain.Ronin:
+      return "0xe514d9deb7966c8be0ca922de8a064264ea6bcd4" // WETH
+    case Chain.Gunzilla:
+      return "0x0000000000000000000000000000000000000000" // GUN
+    default:
+      throw new Error(`Unknown listing currency for ${chain}`)
+  }
+}
+
+/**
+ * Get the default conduit key and address for a given chain.
+ * @param chain The chain to get the conduit for
+ * @returns The conduit key and address for the chain
+ */
+export const getDefaultConduit = (
+  chain: Chain,
+): { key: string; address: string } => {
+  switch (chain) {
+    case Chain.Abstract:
+    case Chain.HyperEVM:
+    case Chain.Monad:
+      return {
+        key: OPENSEA_CONDUIT_KEY_2,
+        address: OPENSEA_CONDUIT_ADDRESS_2,
+      }
+    default:
+      if (usesAlternateProtocol(chain)) {
+        return {
+          key: ALTERNATE_CONDUIT_KEY,
+          address: ALTERNATE_CONDUIT_ADDRESS,
+        }
+      }
+      return {
+        key: OPENSEA_CONDUIT_KEY,
+        address: OPENSEA_CONDUIT_ADDRESS,
+      }
+  }
+}
+
+/**
+ * Get the Seaport 1.6 contract address for a given chain.
+ * @param chain The chain to get the Seaport address for
+ * @returns The Seaport 1.6 address for the chain
+ */
+export const getSeaportAddress = (chain: Chain): string => {
+  return usesAlternateProtocol(chain)
+    ? ALTERNATE_SEAPORT_V1_6_ADDRESS
+    : CROSS_CHAIN_SEAPORT_V1_6_ADDRESS
+}
+
+/**
+ * Get the signed zone address for a given chain.
+ * @param chain The chain to get the signed zone address for
+ * @returns The signed zone address for the chain
+ */
+export const getSignedZone = (chain: Chain): string => {
+  return usesAlternateProtocol(chain)
+    ? ALTERNATE_SIGNED_ZONE_V2_ADDRESS
+    : OPENSEA_SIGNED_ZONE_V2
+}
+
+/**
+ * Get the fee recipient address for a given chain
+ * @param chain The blockchain chain
+ * @returns The fee recipient address for the chain
+ */
+export const getFeeRecipient = (chain: Chain): string => {
+  switch (chain) {
+    case Chain.Gunzilla:
+      return GUNZILLA_FEE_RECIPIENT
+    case Chain.Somnia:
+      return SOMNIA_FEE_RECIPIENT
+    case Chain.MegaETH:
+      return ALTERNATE_FEE_RECIPIENT
+    default:
+      return OPENSEA_FEE_RECIPIENT
+  }
+}
+
+/**
+ * Get the appropriate token address for wrap/unwrap operations.
+ * For Polygon, use WPOL. For other chains, use the wrapped native asset.
+ * @param chain The chain to get the token address for
+ * @returns The token address for wrap/unwrap operations
+ */
+export const getNativeWrapTokenAddress = (chain: Chain): string => {
+  switch (chain) {
+    case Chain.Polygon:
+      return WPOL_ADDRESS
+    default:
+      return getOfferPaymentToken(chain)
+  }
+}

package/src/utils/chainIds.generated.ts

@@ -0,0 +1,34 @@
+/**
+ * AUTO-GENERATED by scripts/sync-chains.ts — DO NOT EDIT.
+ * Source of truth: OpenSea REST API + scripts/chain-data.json
+ * Run `pnpm sync-chains` to regenerate.
+ */
+
+/** Map chain slug (Chain enum value) to numeric chain ID. */
+export const CHAIN_ID_MAP: Record<string, string> = {
+  ethereum: "1",
+  optimism: "10",
+  unichain: "130",
+  polygon: "137",
+  monad: "143",
+  shape: "360",
+  flow: "747",
+  hyperevm: "999",
+  sei: "1329",
+  soneium: "1868",
+  ronin: "2020",
+  abstract: "2741",
+  megaeth: "4326",
+  somnia: "5031",
+  b3: "8333",
+  base: "8453",
+  ape_chain: "33139",
+  arbitrum: "42161",
+  avalanche: "43114",
+  gunzilla: "43419",
+  ink: "57073",
+  animechain: "69000",
+  bera_chain: "80094",
+  blast: "81457",
+  zora: "7777777",
+}