@opensea/sdk 9.0.0

package/src/api/apiPaths.ts

@@ -0,0 +1,208 @@
+import type { OrderProtocol } from "../orders/types"
+import { type Chain, OrderSide } from "../types"
+
+/** Base path prefix for all OpenSea API v2 endpoints. */
+export const API_V2_PREFIX = "/api/v2"
+
+export const getOrdersAPIPath = (
+  chain: Chain,
+  protocol: OrderProtocol,
+  side: OrderSide,
+) => {
+  const sidePath = side === OrderSide.LISTING ? "listings" : "offers"
+  return `${API_V2_PREFIX}/orders/${chain}/${protocol}/${sidePath}`
+}
+
+export const getAllOffersAPIPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/all`
+}
+
+export const getAllListingsAPIPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/all`
+}
+
+export const getBestOfferAPIPath = (
+  collectionSlug: string,
+  tokenId: string | number,
+) => {
+  return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/nfts/${tokenId}/best`
+}
+
+export const getBestListingAPIPath = (
+  collectionSlug: string,
+  tokenId: string | number,
+) => {
+  return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/nfts/${tokenId}/best`
+}
+
+export const getBestListingsAPIPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/listings/collection/${collectionSlug}/best`
+}
+
+export const getCollectionPath = (slug: string) => {
+  return `${API_V2_PREFIX}/collections/${slug}`
+}
+
+export const getCollectionsPath = () => {
+  return `${API_V2_PREFIX}/collections`
+}
+
+export const getCollectionStatsPath = (slug: string) => {
+  return `${API_V2_PREFIX}/collections/${slug}/stats`
+}
+
+export const getPaymentTokenPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/payment_token/${address}`
+}
+
+export const getAccountPath = (address: string) => {
+  return `${API_V2_PREFIX}/accounts/${address}`
+}
+
+export const getBuildOfferPath = () => {
+  return `${API_V2_PREFIX}/offers/build`
+}
+
+export const getPostCollectionOfferPath = () => {
+  return `${API_V2_PREFIX}/offers`
+}
+
+export const getCollectionOffersPath = (slug: string) => {
+  return `${API_V2_PREFIX}/offers/collection/${slug}`
+}
+
+export const getListNFTsByCollectionPath = (slug: string) => {
+  return `${API_V2_PREFIX}/collection/${slug}/nfts`
+}
+
+export const getListNFTsByContractPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts`
+}
+
+export const getListNFTsByAccountPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/account/${address}/nfts`
+}
+
+export const getNFTPath = (
+  chain: Chain,
+  address: string,
+  identifier: string,
+) => {
+  return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}`
+}
+
+export const getRefreshMetadataPath = (
+  chain: Chain,
+  address: string,
+  identifier: string,
+) => {
+  return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/refresh`
+}
+
+export const getOrderByHashPath = (
+  chain: Chain,
+  protocolAddress: string,
+  orderHash: string,
+) => {
+  return `${API_V2_PREFIX}/orders/chain/${chain}/protocol/${protocolAddress}/${orderHash}`
+}
+
+export const getCancelOrderPath = (
+  chain: Chain,
+  protocolAddress: string,
+  orderHash: string,
+) => {
+  return `${API_V2_PREFIX}/orders/chain/${chain}/protocol/${protocolAddress}/${orderHash}/cancel`
+}
+
+export const getTraitOffersPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/traits`
+}
+
+export const getEventsAPIPath = () => {
+  return `${API_V2_PREFIX}/events`
+}
+
+export const getEventsByAccountAPIPath = (address: string) => {
+  return `${API_V2_PREFIX}/events/accounts/${address}`
+}
+
+export const getEventsByCollectionAPIPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/events/collection/${collectionSlug}`
+}
+
+export const getEventsByNFTAPIPath = (
+  chain: Chain,
+  address: string,
+  identifier: string,
+) => {
+  return `${API_V2_PREFIX}/events/chain/${chain}/contract/${address}/nfts/${identifier}`
+}
+
+export const getContractPath = (chain: Chain, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/contract/${address}`
+}
+
+export const getTraitsPath = (collectionSlug: string) => {
+  return `${API_V2_PREFIX}/traits/${collectionSlug}`
+}
+
+export const getTrendingTokensPath = () => {
+  return `${API_V2_PREFIX}/tokens/trending`
+}
+
+export const getTopTokensPath = () => {
+  return `${API_V2_PREFIX}/tokens/top`
+}
+
+export const getSwapQuotePath = () => {
+  return `${API_V2_PREFIX}/swap/quote`
+}
+
+export const getTokenPath = (chain: string, address: string) => {
+  return `${API_V2_PREFIX}/chain/${chain}/token/${address}`
+}
+
+export const getSearchPath = () => {
+  return `${API_V2_PREFIX}/search`
+}
+
+export const getChainsPath = () => {
+  return `${API_V2_PREFIX}/chains`
+}
+
+export const getAccountTokensPath = (address: string) => {
+  return `${API_V2_PREFIX}/account/${address}/tokens`
+}
+
+export const getValidateMetadataPath = (
+  chain: Chain,
+  address: string,
+  identifier: string,
+) => {
+  return `${API_V2_PREFIX}/chain/${chain}/contract/${address}/nfts/${identifier}/validate-metadata`
+}
+
+export const getDropsPath = () => {
+  return `${API_V2_PREFIX}/drops`
+}
+
+export const getDropPath = (slug: string) => {
+  return `${API_V2_PREFIX}/drops/${slug}`
+}
+
+export const getDropMintPath = (slug: string) => {
+  return `${API_V2_PREFIX}/drops/${slug}/mint`
+}
+
+export const getTrendingCollectionsPath = () => {
+  return `${API_V2_PREFIX}/collections/trending`
+}
+
+export const getTopCollectionsPath = () => {
+  return `${API_V2_PREFIX}/collections/top`
+}
+
+export const getResolveAccountPath = (identifier: string) => {
+  return `${API_V2_PREFIX}/accounts/resolve/${identifier}`
+}

package/src/api/chains.ts

@@ -0,0 +1,18 @@
+import { getChainsPath } from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type { GetChainsResponse } from "./types"
+
+/**
+ * Chain-related API operations
+ */
+export class ChainsAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Gets the list of supported chains.
+   */
+  async getChains(): Promise<GetChainsResponse> {
+    const response = await this.fetcher.get<GetChainsResponse>(getChainsPath())
+    return response
+  }
+}

package/src/api/collections.ts

@@ -0,0 +1,120 @@
+import type { Chain, OpenSeaCollection, OpenSeaCollectionStats } from "../types"
+import { collectionFromJSON } from "../utils/converters"
+import {
+  getCollectionPath,
+  getCollectionStatsPath,
+  getCollectionsPath,
+  getTopCollectionsPath,
+  getTraitsPath,
+  getTrendingCollectionsPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import {
+  CollectionOrderByOption,
+  type GetCollectionResponse,
+  type GetCollectionsArgs,
+  type GetCollectionsPaginatedResponse,
+  type GetCollectionsResponse,
+  type GetTopCollectionsArgs,
+  type GetTraitsResponse,
+  type GetTrendingCollectionsArgs,
+} from "./types"
+
+/**
+ * Collection-related API operations
+ */
+export class CollectionsAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Fetch an OpenSea collection.
+   */
+  async getCollection(slug: string): Promise<OpenSeaCollection> {
+    const path = getCollectionPath(slug)
+    const response = await this.fetcher.get<GetCollectionResponse>(path)
+    return collectionFromJSON(response)
+  }
+
+  /**
+   * Fetch a list of OpenSea collections.
+   */
+  async getCollections(
+    orderBy: CollectionOrderByOption = CollectionOrderByOption.CREATED_DATE,
+    chain?: Chain,
+    creatorUsername?: string,
+    includeHidden: boolean = false,
+    limit?: number,
+    next?: string,
+  ): Promise<GetCollectionsResponse> {
+    const path = getCollectionsPath()
+    const args: GetCollectionsArgs = {
+      order_by: orderBy,
+      chain,
+      creator_username: creatorUsername,
+      include_hidden: includeHidden,
+      limit,
+      next,
+    }
+    const response = await this.fetcher.get<GetCollectionsResponse>(path, args)
+    response.collections = response.collections.map(collection =>
+      collectionFromJSON(collection),
+    )
+    return response
+  }
+
+  /**
+   * Fetch stats for an OpenSea collection.
+   */
+  async getCollectionStats(slug: string): Promise<OpenSeaCollectionStats> {
+    const path = getCollectionStatsPath(slug)
+    const response = await this.fetcher.get<OpenSeaCollectionStats>(path)
+    return response as OpenSeaCollectionStats
+  }
+
+  /**
+   * Fetch all traits for a collection with their possible values and counts.
+   */
+  async getTraits(collectionSlug: string): Promise<GetTraitsResponse> {
+    const path = getTraitsPath(collectionSlug)
+    const response = await this.fetcher.get<GetTraitsResponse>(path)
+    return response
+  }
+
+  /**
+   * Fetch trending collections sorted by sales activity.
+   */
+  async getTrendingCollections(
+    args?: GetTrendingCollectionsArgs,
+  ): Promise<GetCollectionsPaginatedResponse> {
+    const response = await this.fetcher.get<GetCollectionsPaginatedResponse>(
+      getTrendingCollectionsPath(),
+      {
+        ...args,
+        chains: args?.chains?.join(","),
+      },
+    )
+    response.collections = response.collections.map(collection =>
+      collectionFromJSON(collection),
+    )
+    return response
+  }
+
+  /**
+   * Fetch top collections ranked by various stats.
+   */
+  async getTopCollections(
+    args?: GetTopCollectionsArgs,
+  ): Promise<GetCollectionsPaginatedResponse> {
+    const response = await this.fetcher.get<GetCollectionsPaginatedResponse>(
+      getTopCollectionsPath(),
+      {
+        ...args,
+        chains: args?.chains?.join(","),
+      },
+    )
+    response.collections = response.collections.map(collection =>
+      collectionFromJSON(collection),
+    )
+    return response
+  }
+}

package/src/api/drops.ts

@@ -0,0 +1,49 @@
+import { getDropMintPath, getDropPath, getDropsPath } from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type {
+  DropMintRequest,
+  DropMintResponse,
+  GetDropResponse,
+  GetDropsArgs,
+  GetDropsResponse,
+} from "./types"
+
+/**
+ * Drop-related API operations
+ */
+export class DropsAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Gets a list of drops (mints).
+   */
+  async getDrops(args?: GetDropsArgs): Promise<GetDropsResponse> {
+    const response = await this.fetcher.get<GetDropsResponse>(getDropsPath(), {
+      ...args,
+      chains: args?.chains?.join(","),
+    })
+    return response
+  }
+
+  /**
+   * Gets detailed drop information for a collection.
+   */
+  async getDrop(slug: string): Promise<GetDropResponse> {
+    const response = await this.fetcher.get<GetDropResponse>(getDropPath(slug))
+    return response
+  }
+
+  /**
+   * Builds a mint transaction for a drop.
+   */
+  async buildMintTransaction(
+    slug: string,
+    request: DropMintRequest,
+  ): Promise<DropMintResponse> {
+    const response = await this.fetcher.post<DropMintResponse>(
+      getDropMintPath(slug),
+      request,
+    )
+    return response
+  }
+}

package/src/api/events.ts

@@ -0,0 +1,71 @@
+import type { Chain } from "../types"
+import {
+  getEventsAPIPath,
+  getEventsByAccountAPIPath,
+  getEventsByCollectionAPIPath,
+  getEventsByNFTAPIPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type { GetEventsArgs, GetEventsResponse } from "./types"
+
+/**
+ * Events-related API operations
+ */
+export class EventsAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Gets a list of events based on query parameters.
+   */
+  async getEvents(args?: GetEventsArgs): Promise<GetEventsResponse> {
+    const response = await this.fetcher.get<GetEventsResponse>(
+      getEventsAPIPath(),
+      args,
+    )
+    return response
+  }
+
+  /**
+   * Gets a list of events for a specific account.
+   */
+  async getEventsByAccount(
+    address: string,
+    args?: GetEventsArgs,
+  ): Promise<GetEventsResponse> {
+    const response = await this.fetcher.get<GetEventsResponse>(
+      getEventsByAccountAPIPath(address),
+      args,
+    )
+    return response
+  }
+
+  /**
+   * Gets a list of events for a specific collection.
+   */
+  async getEventsByCollection(
+    collectionSlug: string,
+    args?: GetEventsArgs,
+  ): Promise<GetEventsResponse> {
+    const response = await this.fetcher.get<GetEventsResponse>(
+      getEventsByCollectionAPIPath(collectionSlug),
+      args,
+    )
+    return response
+  }
+
+  /**
+   * Gets a list of events for a specific NFT.
+   */
+  async getEventsByNFT(
+    chain: Chain,
+    address: string,
+    identifier: string,
+    args?: GetEventsArgs,
+  ): Promise<GetEventsResponse> {
+    const response = await this.fetcher.get<GetEventsResponse>(
+      getEventsByNFTAPIPath(chain, address, identifier),
+      args,
+    )
+    return response
+  }
+}

package/src/api/fetcher.ts

@@ -0,0 +1,31 @@
+import type { RequestOptions } from "../types"
+
+/**
+ * Fetcher context interface for making HTTP requests to the OpenSea API.
+ * This interface abstracts the HTTP methods used by specialized API clients.
+ */
+export interface Fetcher {
+  /**
+   * Generic fetch method for GET requests with automatic rate limit retry
+   * @param apiPath Path to URL endpoint under API
+   * @param query URL query params. Will be used to create a URLSearchParams object.
+   * @param options Request options like timeout and abort signal.
+   * @returns The response from the API.
+   */
+  get<T>(apiPath: string, query?: object, options?: RequestOptions): Promise<T>
+
+  /**
+   * Generic post method for POST requests with automatic rate limit retry
+   * @param apiPath Path to URL endpoint under API
+   * @param body Data to send.
+   * @param headers Additional headers to send with the request.
+   * @param options Request options like timeout and abort signal.
+   * @returns The response from the API.
+   */
+  post<T>(
+    apiPath: string,
+    body?: object,
+    headers?: object,
+    options?: RequestOptions,
+  ): Promise<T>
+}

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export * from "./api"
+export * from "./fetcher"

package/src/api/listings.ts

@@ -0,0 +1,126 @@
+import { serializeOrdersQueryOptions } from "../orders/utils"
+import { type Chain, OrderSide } from "../types"
+import {
+  getAllListingsAPIPath,
+  getBestListingAPIPath,
+  getBestListingsAPIPath,
+  getOrdersAPIPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type { GetBestListingResponse, GetListingsResponse } from "./types"
+
+/**
+ * Listing-related API operations
+ */
+export class ListingsAPI {
+  constructor(
+    private fetcher: Fetcher,
+    private chain: Chain,
+  ) {}
+
+  /**
+   * Gets all 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)
+   */
+  async getAllListings(
+    collectionSlug: string,
+    limit?: number,
+    next?: string,
+    includePrivateListings?: boolean,
+  ): Promise<GetListingsResponse> {
+    const response = await this.fetcher.get<GetListingsResponse>(
+      getAllListingsAPIPath(collectionSlug),
+      {
+        limit,
+        next,
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
+      },
+    )
+    return response
+  }
+
+  /**
+   * Gets the best listing for a given token.
+   * @param collectionSlug The collection slug
+   * @param tokenId The token ID
+   * @param includePrivateListings Whether to include private listings (default: false)
+   */
+  async getBestListing(
+    collectionSlug: string,
+    tokenId: string | number,
+    includePrivateListings?: boolean,
+  ): Promise<GetBestListingResponse> {
+    const response = await this.fetcher.get<GetBestListingResponse>(
+      getBestListingAPIPath(collectionSlug, tokenId),
+      includePrivateListings !== undefined
+        ? { include_private_listings: includePrivateListings }
+        : undefined,
+    )
+    return response
+  }
+
+  /**
+   * 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)
+   */
+  async getBestListings(
+    collectionSlug: string,
+    limit?: number,
+    next?: string,
+    includePrivateListings?: boolean,
+  ): Promise<GetListingsResponse> {
+    const response = await this.fetcher.get<GetListingsResponse>(
+      getBestListingsAPIPath(collectionSlug),
+      {
+        limit,
+        next,
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
+      },
+    )
+    return response
+  }
+
+  /**
+   * Gets all active listings for a specific NFT.
+   * @param assetContractAddress The NFT contract address
+   * @param tokenId The token ID
+   * @param limit The number of listings to return
+   * @param next The cursor for pagination
+   * @param chain The blockchain chain
+   * @param includePrivateListings Whether to include private listings (default: false)
+   */
+  async getNFTListings(
+    assetContractAddress: string,
+    tokenId: string,
+    limit?: number,
+    next?: string,
+    chain: Chain = this.chain,
+    includePrivateListings?: boolean,
+  ): Promise<GetListingsResponse> {
+    const response = await this.fetcher.get<GetListingsResponse>(
+      getOrdersAPIPath(chain, "seaport", OrderSide.LISTING),
+      {
+        ...serializeOrdersQueryOptions({
+          assetContractAddress,
+          tokenIds: [tokenId],
+          limit,
+          next,
+        }),
+        ...(includePrivateListings !== undefined && {
+          include_private_listings: includePrivateListings,
+        }),
+      },
+    )
+    return response
+  }
+}