opensea-js

import { BuildOfferResponse, GetCollectionsResponse, ListNFTsResponse, GetNFTResponse, ListCollectionOffersResponse, GetOrdersResponse, GetBestOfferResponse, GetBestListingResponse, GetOffersResponse, GetListingsResponse, CollectionOffer, CollectionOrderByOption, CancelOrderResponse } from "./types"; import { FulfillmentDataResponse, OrderAPIOptions, OrdersQueryOptions, OrderV2, ProtocolData } from "../orders/types"; import { Chain, OpenSeaAPIConfig, OpenSeaAccount, OpenSeaCollection, OpenSeaCollectionStats, OpenSeaPaymentToken, OrderSide } 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; /** * 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 * @param options.side The side of the order (listing or offer) * @param options.protocol The protocol, typically seaport, to query orders for * @param options.orderDirection The direction to sort the orders * @param options.orderBy The field to sort the orders by * @param options.limit The number of orders to retrieve * @param options.maker Filter by the wallet address of the order maker * @param options.taker Filter by wallet address of the order taker * @param options.asset_contract_address Address of the NFT's contract * @param options.token_ids String array of token IDs to filter by. * @param options.listed_after Filter by orders listed after the Unix epoch timestamp in seconds * @param options.listed_before Filter by orders listed before the Unix epoch timestamp in seconds * @returns The first {@link OrderV2} returned by the API * * @throws An error if there are no matching orders. */ getOrder({ side, protocol, orderDirection, orderBy, ...restOptions }: Omit<OrdersQueryOptions, "limit">): Promise<OrderV2>; /** * Gets a list of orders from API based on query options. * @param options * @param options.side The side of the order (buy or sell) * @param options.protocol The protocol, typically seaport, to query orders for * @param options.orderDirection The direction to sort the orders * @param options.orderBy The field to sort the orders by * @param options.limit The number of orders to retrieve * @param options.maker Filter by the wallet address of the order maker * @param options.taker Filter by wallet address of the order taker * @param options.asset_contract_address Address of the NFT's contract * @param options.token_ids String array of token IDs to filter by. * @param options.listed_after Filter by orders listed after the Unix epoch timestamp in seconds * @param options.listed_before Filter by orders listed before the Unix epoch timestamp in seconds * @returns The {@link GetOrdersResponse} returned by the API. */ getOrders({ side, protocol, orderDirection, orderBy, ...restOptions }: 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. * @returns The {@link GetListingsResponse} returned by the API. */ getAllListings(collectionSlug: string, limit?: number, next?: string): 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. * @returns The {@link GetBestListingResponse} returned by the API. */ getBestListing(collectionSlug: string, tokenId: string | number): 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. * @returns The {@link GetListingsResponse} returned by the API. */ getBestListings(collectionSlug: string, limit?: number, next?: string): 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 * @side The side of the order (buy or sell) * @returns The {@link FulfillmentDataResponse} */ generateFulfillmentData(fulfillerAddress: string, orderHash: string, protocolAddress: string, side: OrderSide): Promise<FulfillmentDataResponse>; /** * Post an order to OpenSea. * @param order The order to post * @param apiOptions * @param apiOptions.protocol The protocol, typically seaport, to post the order to. * @param apiOptions.side The side of the order (buy or sell). * @param apiOptions.protocolAddress The address of the seaport contract. * @param options * @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. * @returns The {@link BuildOfferResponse} returned by the API. */ buildOffer(offererAddress: string, quantity: number, collectionSlug: string, offerProtectionEnabled?: boolean, traitType?: string, traitValue?: string): Promise<BuildOfferResponse>; /** * Get a list collection offers for a given slug. * @param slug The slug (identifier) of the collection to list offers for * @returns The {@link ListCollectionOffersResponse} returned by the API. */ getCollectionOffers(slug: string): Promise<ListCollectionOffersResponse | null>; /** * 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. * @returns The {@link Offer} returned to the API. */ postCollectionOffer(order: ProtocolData, slug: string, traitType?: string, traitValue?: 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 query Query to use for getting tokens. See {@link OpenSeaPaymentTokenQuery}. * @param next The cursor for the next page of results. This is returned from a previous request. * @returns The {@link OpenSeaPaymentToken} returned by the API. */ getPaymentToken(address: string, chain?: Chain): Promise<OpenSeaPaymentToken>; /** * Fetch account for an address. * @param query Query to use for getting tokens. See {@link OpenSeaPaymentTokenQuery}. * @param next The cursor for the next page of results. This is returned from a previous request. * @returns The {@link GetAccountResponse} 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>; /** * Generic fetch method for any API endpoint * @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. * @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 retry-after information for backwards compatibility. * @param response The HTTP response object from the API * @returns An enhanced Error object with retryAfter and responseBody properties */ private _createRateLimitError; }