@opensea/sdk 9.0.0

package/src/api/nfts.ts

@@ -0,0 +1,144 @@
+import type { Chain } from "../types"
+import {
+  getContractPath,
+  getListNFTsByAccountPath,
+  getListNFTsByCollectionPath,
+  getListNFTsByContractPath,
+  getNFTPath,
+  getRefreshMetadataPath,
+  getValidateMetadataPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type {
+  GetContractResponse,
+  GetNFTResponse,
+  ListNFTsResponse,
+  ValidateMetadataResponse,
+} from "./types"
+
+/**
+ * NFT-related API operations
+ */
+export class NFTsAPI {
+  constructor(
+    private fetcher: Fetcher,
+    private chain: Chain,
+  ) {}
+
+  /**
+   * Fetch multiple NFTs for a collection.
+   */
+  async getNFTsByCollection(
+    slug: string,
+    limit: number | undefined = undefined,
+    next: string | undefined = undefined,
+  ): Promise<ListNFTsResponse> {
+    const response = await this.fetcher.get<ListNFTsResponse>(
+      getListNFTsByCollectionPath(slug),
+      {
+        limit,
+        next,
+      },
+    )
+    return response
+  }
+
+  /**
+   * Fetch multiple NFTs for a contract.
+   */
+  async getNFTsByContract(
+    address: string,
+    limit: number | undefined = undefined,
+    next: string | undefined = undefined,
+    chain: Chain = this.chain,
+  ): Promise<ListNFTsResponse> {
+    const response = await this.fetcher.get<ListNFTsResponse>(
+      getListNFTsByContractPath(chain, address),
+      {
+        limit,
+        next,
+      },
+    )
+    return response
+  }
+
+  /**
+   * Fetch NFTs owned by an account.
+   */
+  async getNFTsByAccount(
+    address: string,
+    limit: number | undefined = undefined,
+    next: string | undefined = undefined,
+    chain = this.chain,
+  ): Promise<ListNFTsResponse> {
+    const response = await this.fetcher.get<ListNFTsResponse>(
+      getListNFTsByAccountPath(chain, address),
+      {
+        limit,
+        next,
+      },
+    )
+
+    return response
+  }
+
+  /**
+   * Fetch metadata, traits, ownership information, and rarity for a single NFT.
+   */
+  async getNFT(
+    address: string,
+    identifier: string,
+    chain = this.chain,
+  ): Promise<GetNFTResponse> {
+    const response = await this.fetcher.get<GetNFTResponse>(
+      getNFTPath(chain, address, identifier),
+    )
+    return response
+  }
+
+  /**
+   * Force refresh the metadata for an NFT.
+   */
+  async refreshNFTMetadata(
+    address: string,
+    identifier: string,
+    chain: Chain = this.chain,
+  ): Promise<Response> {
+    const response = await this.fetcher.post<Response>(
+      getRefreshMetadataPath(chain, address, identifier),
+      {},
+    )
+
+    return response
+  }
+
+  /**
+   * Fetch smart contract information for a given chain and address.
+   */
+  async getContract(
+    address: string,
+    chain: Chain = this.chain,
+  ): Promise<GetContractResponse> {
+    const response = await this.fetcher.get<GetContractResponse>(
+      getContractPath(chain, address),
+    )
+    return response
+  }
+
+  /**
+   * Validate NFT metadata by fetching and parsing it.
+   */
+  async validateMetadata(
+    address: string,
+    identifier: string,
+    chain: Chain = this.chain,
+    ignoreCachedItemUrls?: boolean,
+  ): Promise<ValidateMetadataResponse> {
+    let path = getValidateMetadataPath(chain, address, identifier)
+    if (ignoreCachedItemUrls !== undefined) {
+      path += `?ignoreCachedItemUrls=${ignoreCachedItemUrls}`
+    }
+    const response = await this.fetcher.post<ValidateMetadataResponse>(path)
+    return response
+  }
+}

package/src/api/offers.ts

@@ -0,0 +1,242 @@
+import type { ProtocolData } from "../orders/types"
+import {
+  getBuildCollectionOfferPayload,
+  getPostCollectionOfferPayload,
+  serializeOrdersQueryOptions,
+} from "../orders/utils"
+import { type Chain, OrderSide } from "../types"
+import {
+  getAllOffersAPIPath,
+  getBestOfferAPIPath,
+  getBuildOfferPath,
+  getCollectionOffersPath,
+  getOrdersAPIPath,
+  getPostCollectionOfferPath,
+  getTraitOffersPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type {
+  BuildOfferResponse,
+  CollectionOffer,
+  GetBestOfferResponse,
+  GetOffersResponse,
+} from "./types"
+
+/**
+ * Validates trait parameters for collection offers.
+ * Used by both buildOffer and postCollectionOffer.
+ */
+function validateTraitParams(
+  traitType?: string,
+  traitValue?: string,
+  traits?: Array<{ type: string; value: string }>,
+  numericTraits?: Array<{ type: string; min?: number; max?: number }>,
+) {
+  if (traits && traits.length > 0 && (traitType || traitValue)) {
+    throw new Error(
+      "Cannot use both 'traits' array and individual 'traitType'/'traitValue' parameters. Please use only one approach.",
+    )
+  }
+  if (traitType || traitValue) {
+    if (!traitType || !traitValue) {
+      throw new Error(
+        "Both traitType and traitValue must be defined if one is defined.",
+      )
+    }
+  }
+  if (traits && traits.length > 0) {
+    for (const trait of traits) {
+      if (!trait.type || !trait.value) {
+        throw new Error(
+          "Each trait must have both 'type' and 'value' properties.",
+        )
+      }
+    }
+  }
+  if (numericTraits && numericTraits.length > 0) {
+    for (const trait of numericTraits) {
+      if (!trait.type) {
+        throw new Error("Each numeric trait must have a 'type' property.")
+      }
+      if (trait.min === undefined && trait.max === undefined) {
+        throw new Error(
+          `Numeric trait '${trait.type}' must have at least one of 'min' or 'max'.`,
+        )
+      }
+      if (
+        trait.min !== undefined &&
+        trait.max !== undefined &&
+        trait.min > trait.max
+      ) {
+        throw new Error(
+          `Numeric trait '${trait.type}': 'min' (${trait.min}) must be <= 'max' (${trait.max}).`,
+        )
+      }
+    }
+  }
+}
+
+/**
+ * Offer-related API operations
+ */
+export class OffersAPI {
+  constructor(
+    private fetcher: Fetcher,
+    private chain: Chain,
+  ) {}
+
+  /**
+   * Gets all offers for a given collection.
+   */
+  async getAllOffers(
+    collectionSlug: string,
+    limit?: number,
+    next?: string,
+  ): Promise<GetOffersResponse> {
+    const response = await this.fetcher.get<GetOffersResponse>(
+      getAllOffersAPIPath(collectionSlug),
+      {
+        limit,
+        next,
+      },
+    )
+    return response
+  }
+
+  /**
+   * Gets trait offers for a given collection.
+   */
+  async getTraitOffers(
+    collectionSlug: string,
+    type: string,
+    value: string,
+    limit?: number,
+    next?: string,
+    floatValue?: number,
+    intValue?: number,
+  ): Promise<GetOffersResponse> {
+    const response = await this.fetcher.get<GetOffersResponse>(
+      getTraitOffersPath(collectionSlug),
+      {
+        type,
+        value,
+        limit,
+        next,
+        float_value: floatValue,
+        int_value: intValue,
+      },
+    )
+    return response
+  }
+
+  /**
+   * Gets the best offer for a given token.
+   */
+  async getBestOffer(
+    collectionSlug: string,
+    tokenId: string | number,
+  ): Promise<GetBestOfferResponse> {
+    const response = await this.fetcher.get<GetBestOfferResponse>(
+      getBestOfferAPIPath(collectionSlug, tokenId),
+    )
+    return response
+  }
+
+  /**
+   * Build a OpenSea collection offer.
+   */
+  async buildOffer(
+    offererAddress: string,
+    quantity: number,
+    collectionSlug: string,
+    offerProtectionEnabled = true,
+    traitType?: string,
+    traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
+    numericTraits?: Array<{ type: string; min?: number; max?: number }>,
+  ): Promise<BuildOfferResponse> {
+    validateTraitParams(traitType, traitValue, traits, numericTraits)
+    const payload = getBuildCollectionOfferPayload(
+      offererAddress,
+      quantity,
+      collectionSlug,
+      offerProtectionEnabled,
+      this.chain,
+      traitType,
+      traitValue,
+      traits,
+      numericTraits,
+    )
+    const response = await this.fetcher.post<BuildOfferResponse>(
+      getBuildOfferPath(),
+      payload,
+    )
+    return response
+  }
+
+  /**
+   * Get a list of collection offers for a given slug.
+   */
+  async getCollectionOffers(
+    slug: string,
+    limit?: number,
+    next?: string,
+  ): Promise<GetOffersResponse> {
+    return await this.fetcher.get<GetOffersResponse>(
+      getCollectionOffersPath(slug),
+      {
+        limit,
+        next,
+      },
+    )
+  }
+
+  /**
+   * Post a collection offer to OpenSea.
+   */
+  async postCollectionOffer(
+    order: ProtocolData,
+    slug: string,
+    traitType?: string,
+    traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
+    numericTraits?: Array<{ type: string; min?: number; max?: number }>,
+  ): Promise<CollectionOffer | null> {
+    validateTraitParams(traitType, traitValue, traits, numericTraits)
+    const payload = getPostCollectionOfferPayload(
+      slug,
+      order,
+      this.chain,
+      traitType,
+      traitValue,
+      traits,
+      numericTraits,
+    )
+    return await this.fetcher.post<CollectionOffer>(
+      getPostCollectionOfferPath(),
+      payload,
+    )
+  }
+
+  /**
+   * Gets all active offers for a specific NFT.
+   */
+  async getNFTOffers(
+    assetContractAddress: string,
+    tokenId: string,
+    limit?: number,
+    next?: string,
+    chain: Chain = this.chain,
+  ): Promise<GetOffersResponse> {
+    const response = await this.fetcher.get<GetOffersResponse>(
+      getOrdersAPIPath(chain, "seaport", OrderSide.OFFER),
+      serializeOrdersQueryOptions({
+        assetContractAddress,
+        tokenIds: [tokenId],
+        limit,
+        next,
+      }),
+    )
+    return response
+  }
+}

package/src/api/orders.ts

@@ -0,0 +1,283 @@
+import type {
+  FulfillmentDataResponse,
+  ListingPostQueryResponse,
+  OfferPostQueryResponse,
+  OrderAPIOptions,
+  OrdersPostQueryResponse,
+  OrdersQueryOptions,
+  OrdersQueryResponse,
+  OrderV2,
+  ProtocolData,
+} from "../orders/types"
+import {
+  deserializeOrder,
+  getFulfillListingPayload,
+  getFulfillmentDataPath,
+  getFulfillOfferPayload,
+  serializeOrdersQueryOptions,
+} from "../orders/utils"
+import { type Chain, OrderSide } from "../types"
+import {
+  getCancelOrderPath,
+  getOrderByHashPath,
+  getOrdersAPIPath,
+} from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type {
+  CancelOrderResponse,
+  GetOrderByHashResponse,
+  GetOrdersResponse,
+  Listing,
+  Offer,
+} from "./types"
+
+/**
+ * Order-related API operations
+ */
+export class OrdersAPI {
+  constructor(
+    private fetcher: Fetcher,
+    private chain: Chain,
+  ) {}
+
+  /**
+   * Gets an order from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
+   */
+  async getOrder({
+    side,
+    protocol = "seaport",
+    orderDirection = "desc",
+    orderBy = "created_date",
+    ...restOptions
+  }: Omit<OrdersQueryOptions, "limit">): Promise<OrderV2> {
+    // Validate eth_price orderBy requires additional parameters
+    if (orderBy === "eth_price") {
+      const hasTokenId =
+        (restOptions.tokenIds?.length ?? 0) > 0 ||
+        restOptions.tokenId !== undefined
+      if (!restOptions.assetContractAddress || !hasTokenId) {
+        throw new Error(
+          'When using orderBy: "eth_price", you must provide both assetContractAddress and tokenIds (or tokenId) parameters',
+        )
+      }
+    }
+
+    const { orders } = await this.fetcher.get<OrdersQueryResponse>(
+      getOrdersAPIPath(this.chain, protocol, side),
+      serializeOrdersQueryOptions({
+        limit: 1,
+        orderBy,
+        orderDirection,
+        ...restOptions,
+      }),
+    )
+    if (orders.length === 0) {
+      throw new Error("Not found: no matching order found")
+    }
+    return deserializeOrder(orders[0])
+  }
+
+  /**
+   * Gets a single order by its order hash.
+   * Returns the raw API response which can be either an Offer or Listing.
+   */
+  async getOrderByHash(
+    orderHash: string,
+    protocolAddress: string,
+    chain: Chain = this.chain,
+  ): Promise<GetOrderByHashResponse> {
+    const response = await this.fetcher.get<{
+      order: GetOrderByHashResponse
+    }>(getOrderByHashPath(chain, protocolAddress, orderHash))
+    return response.order
+  }
+
+  /**
+   * Gets a list of orders from API based on query options.
+   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
+   */
+  async getOrders({
+    side,
+    protocol = "seaport",
+    orderDirection = "desc",
+    orderBy = "created_date",
+    pageSize = 20,
+    ...restOptions
+  }: Omit<OrdersQueryOptions, "limit"> & {
+    pageSize?: number
+  }): Promise<GetOrdersResponse> {
+    // Validate eth_price orderBy requires additional parameters
+    if (orderBy === "eth_price") {
+      const hasTokenId =
+        (restOptions.tokenIds?.length ?? 0) > 0 ||
+        restOptions.tokenId !== undefined
+      if (!restOptions.assetContractAddress || !hasTokenId) {
+        throw new Error(
+          'When using orderBy: "eth_price", you must provide both assetContractAddress and tokenIds (or tokenId) parameters',
+        )
+      }
+    }
+
+    const response = await this.fetcher.get<OrdersQueryResponse>(
+      getOrdersAPIPath(this.chain, protocol, side),
+      serializeOrdersQueryOptions({
+        limit: pageSize,
+        orderBy,
+        orderDirection,
+        ...restOptions,
+      }),
+    )
+    return {
+      ...response,
+      orders: response.orders.map(deserializeOrder),
+    }
+  }
+
+  /**
+   * Generate the data needed to fulfill a listing or an offer onchain.
+   */
+  async generateFulfillmentData(
+    fulfillerAddress: string,
+    orderHash: string,
+    protocolAddress: string,
+    side: OrderSide,
+    assetContractAddress?: string,
+    tokenId?: string,
+    unitsToFill?: string,
+    recipientAddress?: string,
+    includeOptionalCreatorFees: boolean = false,
+  ): Promise<FulfillmentDataResponse> {
+    let payload: object | null = null
+    if (side === OrderSide.LISTING) {
+      payload = getFulfillListingPayload(
+        fulfillerAddress,
+        orderHash,
+        protocolAddress,
+        this.chain,
+        assetContractAddress,
+        tokenId,
+        unitsToFill,
+        recipientAddress,
+        includeOptionalCreatorFees,
+      )
+    } else {
+      payload = getFulfillOfferPayload(
+        fulfillerAddress,
+        orderHash,
+        protocolAddress,
+        this.chain,
+        assetContractAddress,
+        tokenId,
+        unitsToFill,
+        includeOptionalCreatorFees,
+      )
+    }
+    const response = await this.fetcher.post<FulfillmentDataResponse>(
+      getFulfillmentDataPath(side),
+      payload,
+    )
+    return response
+  }
+
+  /**
+   * Post an order to OpenSea.
+   * @deprecated Use postListing or postOffer instead.
+   */
+  async postOrder(
+    order: ProtocolData,
+    apiOptions: OrderAPIOptions,
+  ): Promise<OrderV2> {
+    const { protocol = "seaport", side, protocolAddress } = apiOptions
+
+    // Validate required fields
+    if (!side) {
+      throw new Error("apiOptions.side is required")
+    }
+    if (!protocolAddress) {
+      throw new Error("apiOptions.protocolAddress is required")
+    }
+    if (!order) {
+      throw new Error("order data is required")
+    }
+
+    // Validate protocol value
+    if (protocol !== "seaport") {
+      throw new Error("Currently only 'seaport' protocol is supported")
+    }
+
+    // Validate side value
+    if (side !== "ask" && side !== "bid") {
+      throw new Error("side must be either 'ask' or 'bid'")
+    }
+
+    // Validate protocolAddress format
+    if (!/^0x[a-fA-F0-9]{40}$/.test(protocolAddress)) {
+      throw new Error("Invalid protocol address format")
+    }
+
+    const response = await this.fetcher.post<OrdersPostQueryResponse>(
+      getOrdersAPIPath(this.chain, protocol, side),
+      { ...order, protocol_address: protocolAddress },
+    )
+    return deserializeOrder(response.order)
+  }
+
+  /**
+   * Post a listing to OpenSea. Returns the new Listing response format.
+   */
+  async postListing(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Listing> {
+    if (!order) {
+      throw new Error("order data is required")
+    }
+    if (!protocolAddress || !/^0x[a-fA-F0-9]{40}$/.test(protocolAddress)) {
+      throw new Error("Invalid protocol address format")
+    }
+
+    const response = await this.fetcher.post<ListingPostQueryResponse>(
+      getOrdersAPIPath(this.chain, "seaport", OrderSide.LISTING),
+      { ...order, protocol_address: protocolAddress },
+    )
+    return response.listing
+  }
+
+  /**
+   * Post an offer to OpenSea. Returns the new Offer response format.
+   */
+  async postOffer(
+    order: ProtocolData,
+    protocolAddress: string,
+  ): Promise<Offer> {
+    if (!order) {
+      throw new Error("order data is required")
+    }
+    if (!protocolAddress || !/^0x[a-fA-F0-9]{40}$/.test(protocolAddress)) {
+      throw new Error("Invalid protocol address format")
+    }
+
+    const response = await this.fetcher.post<OfferPostQueryResponse>(
+      getOrdersAPIPath(this.chain, "seaport", OrderSide.OFFER),
+      { ...order, protocol_address: protocolAddress },
+    )
+    return response.offer
+  }
+
+  /**
+   * Offchain cancel an order, offer or listing, by its order hash when protected by the SignedZone.
+   */
+  async offchainCancelOrder(
+    protocolAddress: string,
+    orderHash: string,
+    chain: Chain = this.chain,
+    offererSignature?: string,
+  ): Promise<CancelOrderResponse> {
+    const response = await this.fetcher.post<CancelOrderResponse>(
+      getCancelOrderPath(chain, protocolAddress, orderHash),
+      { offererSignature },
+    )
+    return response
+  }
+}

package/src/api/search.ts

@@ -0,0 +1,21 @@
+import { getSearchPath } from "./apiPaths"
+import type { Fetcher } from "./fetcher"
+import type { SearchArgs, SearchResponse } from "./types"
+
+/**
+ * Search-related API operations
+ */
+export class SearchAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Search across collections, tokens, NFTs, and accounts.
+   */
+  async search(args: SearchArgs): Promise<SearchResponse> {
+    const response = await this.fetcher.get<SearchResponse>(
+      getSearchPath(),
+      args,
+    )
+    return response
+  }
+}