opensea-js

import { FulfillmentDataResponse, OrderAPIOptions, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types"; import { Chain, OpenSeaAPIConfig, OpenSeaAccount, OpenSeaCollection, OpenSeaCollectionStats, OpenSeaPaymentToken, OrderSide } from "../types"; import { BuildOfferResponse, GetCollectionsResponse, ListNFTsResponse, GetNFTResponse, GetOrdersResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, GetOrderByHashResponse, CollectionOffer, CollectionOrderByOption, CancelOrderResponse, GetEventsArgs, GetEventsResponse, GetContractResponse, GetTraitsResponse } from "./types"; /** * The API class for the OpenSea SDK. * @category Main Classes */ export declare class OpenSeaAPI { /** * Base url for the API */ readonly apiBaseUrl: string; /** * Default size to use for fetching orders */ pageSize: number; /** * Logger function to use when debugging */ logger: (arg: string) => void; private apiKey; private chain; private ordersAPI; private offersAPI; private listingsAPI; private collectionsAPI; private nftsAPI; private accountsAPI; private eventsAPI; /** * Create an instance of the OpenSeaAPI * @param config OpenSeaAPIConfig for setting up the API, including an optional API key, Chain name, and base URL * @param logger Optional function for logging debug strings before and after requests are made. Defaults to no logging */ constructor(config: OpenSeaAPIConfig, logger?: (arg: string) => void); /** * Gets an order from API based on query options. * @param options Query options for fetching an order * @returns The first {@link OrderV2} returned by the API * * @throws An error if there are no matching orders. */ getOrder(options: Omit<OrdersQueryOptions, "limit">): Promise<OrderV2>; /** * Gets a single order by its order hash. * @param orderHash The hash of the order to fetch * @param protocolAddress The address of the seaport contract * @param chain The chain where the order is located. Defaults to the chain set in the constructor. * @returns The {@link GetOrderByHashResponse} returned by the API (can be Offer or Listing) * @throws An error if the order is not found */ getOrderByHash(orderHash: string, protocolAddress: string, chain?: Chain): Promise<GetOrderByHashResponse>; /** * Gets a list of orders from API based on query options. * @param options Query options for fetching orders * @returns The {@link GetOrdersResponse} returned by the API. */ getOrders(options: Omit<OrdersQueryOptions, "limit">): Promise<GetOrdersResponse>; /** * Gets all offers for a given collection. * @param collectionSlug The slug of the collection. * @param limit The number of offers to return. Must be between 1 and 100. Default: 100 * @param next The cursor for the next page of results. This is returned from a previous request. * @returns The {@link GetOffersResponse} returned by the API. */ getAllOffers(collectionSlug: string, limit?: number, next?: string): Promise<GetOffersResponse>; /** * Gets all listings for a given collection. * @param collectionSlug The slug of the collection. * @param limit The number of listings to return. Must be between 1 and 100. Default: 100 * @param next The cursor for the next page of results. This is returned from a previous request. * @param includePrivateListings Whether to include private listings (default: false) * @returns The {@link GetListingsResponse} returned by the API. */ getAllListings(collectionSlug: string, limit?: number, next?: string, includePrivateListings?: boolean): Promise<GetListingsResponse>; /** * Gets trait offers for a given collection. * @param collectionSlug The slug of the collection. * @param type The name of the trait (e.g. 'Background'). * @param value The value of the trait (e.g. 'Red'). * @param limit The number of offers to return. Must be between 1 and 100. Default: 100 * @param next The cursor for the next page of results. This is returned from a previous request. * @param floatValue The value of the trait for decimal-based numeric traits. * @param intValue The value of the trait for integer-based numeric traits. * @returns The {@link GetOffersResponse} returned by the API. */ getTraitOffers(collectionSlug: string, type: string, value: string, limit?: number, next?: string, floatValue?: number, intValue?: number): Promise<GetOffersResponse>; /** * Gets the best offer for a given token. * @param collectionSlug The slug of the collection. * @param tokenId The token identifier. * @returns The {@link GetBestOfferResponse} returned by the API. */ getBestOffer(collectionSlug: string, tokenId: string | number): Promise<GetBestOfferResponse>; /** * Gets the best listing for a given token. * @param collectionSlug The slug of the collection. * @param tokenId The token identifier. * @param includePrivateListings Whether to include private listings (default: false) * @returns The {@link GetBestListingResponse} returned by the API. */ getBestListing(collectionSlug: string, tokenId: string | number, includePrivateListings?: boolean): Promise<GetBestListingResponse>; /** * Gets the best listings for a given collection. * @param collectionSlug The slug of the collection. * @param limit The number of listings to return. Must be between 1 and 100. Default: 100 * @param next The cursor for the next page of results. This is returned from a previous request. * @param includePrivateListings Whether to include private listings (default: false) * @returns The {@link GetListingsResponse} returned by the API. */ getBestListings(collectionSlug: string, limit?: number, next?: string, includePrivateListings?: boolean): Promise<GetListingsResponse>; /** * Generate the data needed to fulfill a listing or an offer onchain. * @param fulfillerAddress The wallet address which will be used to fulfill the order * @param orderHash The hash of the order to fulfill * @param protocolAddress The address of the seaport contract * @param side The side of the order (buy or sell) * @param assetContractAddress Optional address of the NFT contract for criteria offers (e.g., collection offers) * @param tokenId Optional token ID for criteria offers (e.g., collection offers) * @param unitsToFill Optional number of units to fill. Defaults to 1 for both listings and offers. * @param recipientAddress Optional recipient address for the NFT when fulfilling a listing. Not applicable for offers. * @param includeOptionalCreatorFees Whether to include optional creator fees in the fulfillment. If creator fees are already required, this is a no-op. Defaults to false. * @returns The {@link FulfillmentDataResponse} */ generateFulfillmentData(fulfillerAddress: string, orderHash: string, protocolAddress: string, side: OrderSide, assetContractAddress?: string, tokenId?: string, unitsToFill?: string, recipientAddress?: string, includeOptionalCreatorFees?: boolean): Promise<FulfillmentDataResponse>; /** * Post an order to OpenSea. * @param order The order to post * @param apiOptions API options for the order * @returns The {@link OrderV2} posted to the API. */ postOrder(order: ProtocolData, apiOptions: OrderAPIOptions): Promise<OrderV2>; /** * Build a OpenSea collection offer. * @param offererAddress The wallet address which is creating the offer. * @param quantity The number of NFTs requested in the offer. * @param collectionSlug The slug (identifier) of the collection to build the offer for. * @param offerProtectionEnabled Build the offer on OpenSea's signed zone to provide offer protections from receiving an item which is disabled from trading. * @param traitType If defined, the trait name to create the collection offer for. * @param traitValue If defined, the trait value to create the collection offer for. * @param traits If defined, an array of traits to create the multi-trait collection offer for. * @returns The {@link BuildOfferResponse} returned by the API. */ buildOffer(offererAddress: string, quantity: number, collectionSlug: string, offerProtectionEnabled?: boolean, traitType?: string, traitValue?: string, traits?: Array<{ type: string; value: string; }>): Promise<BuildOfferResponse>; /** * Get a list collection offers for a given slug. * @param slug The slug (identifier) of the collection to list offers for * @param limit Optional limit for number of results. * @param next Optional cursor for pagination. * @returns The {@link GetOffersResponse} returned by the API. */ getCollectionOffers(slug: string, limit?: number, next?: string): Promise<GetOffersResponse>; /** * Post a collection offer to OpenSea. * @param order The collection offer to post. * @param slug The slug (identifier) of the collection to post the offer for. * @param traitType If defined, the trait name to create the collection offer for. * @param traitValue If defined, the trait value to create the collection offer for. * @param traits If defined, an array of traits to create the multi-trait collection offer for. * @returns The {@link Offer} returned to the API. */ postCollectionOffer(order: ProtocolData, slug: string, traitType?: string, traitValue?: string, traits?: Array<{ type: string; value: string; }>): Promise<CollectionOffer | null>; /** * Fetch multiple NFTs for a collection. * @param slug The slug (identifier) of the collection * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51. * @param next Cursor to retrieve the next page of NFTs * @returns The {@link ListNFTsResponse} returned by the API. */ getNFTsByCollection(slug: string, limit?: number | undefined, next?: string | undefined): Promise<ListNFTsResponse>; /** * Fetch multiple NFTs for a contract. * @param address The NFT's contract address. * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51. * @param next Cursor to retrieve the next page of NFTs. * @param chain The NFT's chain. * @returns The {@link ListNFTsResponse} returned by the API. */ getNFTsByContract(address: string, limit?: number | undefined, next?: string | undefined, chain?: Chain): Promise<ListNFTsResponse>; /** * Fetch NFTs owned by an account. * @param address The address of the account * @param limit The number of NFTs to retrieve. Must be greater than 0 and less than 51. * @param next Cursor to retrieve the next page of NFTs * @param chain The chain to query. Defaults to the chain set in the constructor. * @returns The {@link ListNFTsResponse} returned by the API. */ getNFTsByAccount(address: string, limit?: number | undefined, next?: string | undefined, chain?: Chain): Promise<ListNFTsResponse>; /** * Fetch metadata, traits, ownership information, and rarity for a single NFT. * @param address The NFT's contract address. * @param identifier the identifier of the NFT (i.e. Token ID) * @param chain The NFT's chain. * @returns The {@link GetNFTResponse} returned by the API. */ getNFT(address: string, identifier: string, chain?: Chain): Promise<GetNFTResponse>; /** * Fetch an OpenSea collection. * @param slug The slug (identifier) of the collection. * @returns The {@link OpenSeaCollection} returned by the API. */ getCollection(slug: string): Promise<OpenSeaCollection>; /** * Fetch a list of OpenSea collections. * @param orderBy The order to return the collections in. Default: CREATED_DATE * @param chain The chain to filter the collections on. Default: all chains * @param creatorUsername The creator's OpenSea username to filter the collections on. * @param includeHidden If hidden collections should be returned. Default: false * @param limit The limit of collections to return. * @param next The cursor for the next page of results. This is returned from a previous request. * @returns List of {@link OpenSeaCollection} returned by the API. */ getCollections(orderBy?: CollectionOrderByOption, chain?: Chain, creatorUsername?: string, includeHidden?: boolean, limit?: number, next?: string): Promise<GetCollectionsResponse>; /** * Fetch stats for an OpenSea collection. * @param slug The slug (identifier) of the collection. * @returns The {@link OpenSeaCollection} returned by the API. */ getCollectionStats(slug: string): Promise<OpenSeaCollectionStats>; /** * Fetch a payment token. * @param address The address of the payment token * @param chain The chain of the payment token * @returns The {@link OpenSeaPaymentToken} returned by the API. */ getPaymentToken(address: string, chain?: Chain): Promise<OpenSeaPaymentToken>; /** * Fetch account for an address. * @param address The address to fetch the account for * @returns The {@link OpenSeaAccount} returned by the API. */ getAccount(address: string): Promise<OpenSeaAccount>; /** * Force refresh the metadata for an NFT. * @param address The address of the NFT's contract. * @param identifier The identifier of the NFT. * @param chain The chain where the NFT is located. * @returns The response from the API. */ refreshNFTMetadata(address: string, identifier: string, chain?: Chain): Promise<Response>; /** * Offchain cancel an order, offer or listing, by its order hash when protected by the SignedZone. * Protocol and Chain are required to prevent hash collisions. * Please note cancellation is only assured if a fulfillment signature was not vended prior to cancellation. * @param protocolAddress The Seaport address for the order. * @param orderHash The order hash, or external identifier, of the order. * @param chain The chain where the order is located. * @param offererSignature An EIP-712 signature from the offerer of the order. * If this is not provided, the user associated with the API Key will be checked instead. * The signature must be a EIP-712 signature consisting of the order's Seaport contract's * name, version, address, and chain. The struct to sign is `OrderHash` containing a * single bytes32 field. * @returns The response from the API. */ offchainCancelOrder(protocolAddress: string, orderHash: string, chain?: Chain, offererSignature?: string): Promise<CancelOrderResponse>; /** * Gets a list of events based on query parameters. * @param args Query parameters for filtering events. * @returns The {@link GetEventsResponse} returned by the API. */ getEvents(args?: GetEventsArgs): Promise<GetEventsResponse>; /** * Gets a list of events for a specific account. * @param address The account address. * @param args Query parameters for filtering events. * @returns The {@link GetEventsResponse} returned by the API. */ getEventsByAccount(address: string, args?: GetEventsArgs): Promise<GetEventsResponse>; /** * Gets a list of events for a specific collection. * @param collectionSlug The slug (identifier) of the collection. * @param args Query parameters for filtering events. * @returns The {@link GetEventsResponse} returned by the API. */ getEventsByCollection(collectionSlug: string, args?: GetEventsArgs): Promise<GetEventsResponse>; /** * Gets a list of events for a specific NFT. * @param chain The chain where the NFT is located. * @param address The contract address of the NFT. * @param identifier The token identifier. * @param args Query parameters for filtering events. * @returns The {@link GetEventsResponse} returned by the API. */ getEventsByNFT(chain: Chain, address: string, identifier: string, args?: GetEventsArgs): Promise<GetEventsResponse>; /** * Fetch smart contract information for a given chain and address. * @param address The contract address. * @param chain The chain where the contract is deployed. Defaults to the chain set in the constructor. * @returns The {@link GetContractResponse} returned by the API. */ getContract(address: string, chain?: Chain): Promise<GetContractResponse>; /** * Fetch all traits for a collection with their possible values and counts. * @param collectionSlug The slug (identifier) of the collection. * @returns The {@link GetTraitsResponse} returned by the API. */ getTraits(collectionSlug: string): Promise<GetTraitsResponse>; /** * Gets all active offers for a specific NFT (not just the best offer). * @param assetContractAddress The NFT contract address. * @param tokenId The token identifier. * @param limit The number of offers to return. Must be between 1 and 100. * @param next The cursor for the next page of results. This is returned from a previous request. * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor. * @returns The {@link GetOffersResponse} returned by the API. */ getNFTOffers(assetContractAddress: string, tokenId: string, limit?: number, next?: string, chain?: Chain): Promise<GetOffersResponse>; /** * Gets all active listings for a specific NFT (not just the best listing). * @param assetContractAddress The NFT contract address. * @param tokenId The token identifier. * @param limit The number of listings to return. Must be between 1 and 100. * @param next The cursor for the next page of results. This is returned from a previous request. * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor. * @param includePrivateListings Whether to include private listings (default: false) * @returns The {@link GetListingsResponse} returned by the API. */ getNFTListings(assetContractAddress: string, tokenId: string, limit?: number, next?: string, chain?: Chain, includePrivateListings?: boolean): Promise<GetListingsResponse>; /** * Generic fetch method for any API endpoint 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. * @returns @typeParam T The response from the API. */ get<T>(apiPath: string, query?: object): Promise<T>; /** * Generic post method for any API endpoint with automatic rate limit retry * @param apiPath Path to URL endpoint under API * @param body Data to send. * @param opts ethers ConnectionInfo, similar to Fetch API. * @returns @typeParam T The response from the API. */ post<T>(apiPath: string, body?: object, opts?: object): Promise<T>; private objectToSearchParams; /** * Get from an API Endpoint, sending auth token in headers * @param opts ethers ConnectionInfo, similar to Fetch API * @param body Optional body to send. If set, will POST, otherwise GET */ private _fetch; /** * Parses the retry-after header from the response with robust error handling. * @param response The HTTP response object from the API * @returns The retry-after value in seconds, or undefined if not present or invalid */ private _parseRetryAfter; /** * Creates a rate limit error with status code and retry-after information. * @param response The HTTP response object from the API * @returns An enhanced Error object with statusCode, retryAfter and responseBody properties */ private _createRateLimitError; }