opensea-js/lib/sdk/orders.d.ts

TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data

import { OrderComponents } from "@opensea/seaport-js/lib/types";
import { BigNumberish } from "ethers";
import { CollectionOffer } from "../api/types";
import { SDKContext } from "./context";
import { OrderV2, ProtocolData } from "../orders/types";
import { OrderSide, AssetWithTokenId } from "../types";
/**
 * Result type for bulk operations that may partially succeed.
 * Contains successfully submitted orders and any failures with error information.
 */
export interface BulkOrderResult {
    /** Successfully submitted orders */
    successful: OrderV2[];
    /** Failed order submissions with error information */
    failed: Array<{
        /** Index of the failed order in the original input array */
        index: number;
        /** The signed order that failed to submit (undefined if order creation failed before signing) */
        order?: ProtocolData;
        /** The error that occurred during submission */
        error: Error;
    }>;
}
/**
 * Manager for order building and creation operations.
 * Handles listing creation, offer creation, and collection offers.
 */
export declare class OrdersManager {
    private context;
    private getPriceParametersCallback;
    constructor(context: SDKContext, getPriceParametersCallback: (orderSide: OrderSide, tokenAddress: string, amount: BigNumberish) => Promise<{
        basePrice: bigint;
    }>);
    private getAmountWithBasisPointsApplied;
    private isNotMarketplaceFee;
    private getNFTItems;
    private getFees;
    /**
     * Build listing order without submitting to API
     * @param options Listing parameters
     * @returns OrderWithCounter ready for API submission or onchain validation
     */
    private _buildListingOrder;
    /**
     * Build listing order components without submitting to API
     * @param options Listing parameters
     * @returns OrderComponents ready for onchain validation
     */
    buildListingOrderComponents({ asset, accountAddress, amount, quantity, domain, salt, listingTime, expirationTime, paymentTokenAddress, buyerAddress, includeOptionalCreatorFees, zone, }: {
        asset: AssetWithTokenId;
        accountAddress: string;
        amount: BigNumberish;
        quantity?: BigNumberish;
        domain?: string;
        salt?: BigNumberish;
        listingTime?: number;
        expirationTime?: number;
        paymentTokenAddress?: string;
        buyerAddress?: string;
        includeOptionalCreatorFees?: boolean;
        zone?: string;
    }): Promise<OrderComponents>;
    /**
     * Build offer order without submitting to API
     * @param options Offer parameters
     * @returns OrderWithCounter ready for API submission or onchain validation
     */
    private _buildOfferOrder;
    /**
     * Build offer order components without submitting to API
     * @param options Offer parameters
     * @returns OrderComponents ready for onchain validation
     */
    buildOfferOrderComponents({ asset, accountAddress, amount, quantity, domain, salt, expirationTime, paymentTokenAddress, zone, }: {
        asset: AssetWithTokenId;
        accountAddress: string;
        amount: BigNumberish;
        quantity?: BigNumberish;
        domain?: string;
        salt?: BigNumberish;
        expirationTime?: BigNumberish;
        paymentTokenAddress?: string;
        zone?: string;
    }): Promise<OrderComponents>;
    /**
     * Create and submit an offer on an asset.
     * @param options
     * @param options.asset The asset to trade. tokenAddress and tokenId must be defined.
     * @param options.accountAddress Address of the wallet making the offer.
     * @param options.amount Amount in decimal format (e.g., "1.5" for 1.5 ETH, not wei). Automatically converted to base units.
     * @param options.quantity Number of assets to bid for. Defaults to 1.
     * @param options.domain Optional domain for on-chain attribution. Hashed and included in salt.
     * @param options.salt Arbitrary salt. Auto-generated if not provided.
     * @param options.expirationTime Expiration time for the order, in UTC seconds
     * @param options.paymentTokenAddress ERC20 address for the payment token in the order. If unspecified, defaults to WETH
     * @param options.zone Zone for order protection. Defaults to chain's signed zone.
     *
     * @returns The {@link OrderV2} that was created.
     *
     * @throws Error if the asset does not contain a token id.
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if the amount is not greater than 0.
     * @throws Error if paymentTokenAddress is not WETH on anything other than Ethereum mainnet.
     */
    createOffer({ asset, accountAddress, amount, quantity, domain, salt, expirationTime, paymentTokenAddress, zone, }: {
        asset: AssetWithTokenId;
        accountAddress: string;
        amount: BigNumberish;
        quantity?: BigNumberish;
        domain?: string;
        salt?: BigNumberish;
        expirationTime?: BigNumberish;
        paymentTokenAddress?: string;
        zone?: string;
    }): Promise<OrderV2>;
    /**
     * Create and submit a listing for an asset.
     * @param options
     * @param options.asset The asset to trade. tokenAddress and tokenId must be defined.
     * @param options.accountAddress  Address of the wallet making the listing
     * @param options.amount Amount in decimal format (e.g., "1.5" for 1.5 ETH, not wei). Automatically converted to base units.
     * @param options.quantity Number of assets to list. Defaults to 1.
     * @param options.domain Optional domain for on-chain attribution. Hashed and included in salt. This can be used for on-chain order attribution to assist with analytics.
     * @param options.salt Arbitrary salt. Auto-generated if not provided.
     * @param options.listingTime Optional time when the order will become fulfillable, in UTC seconds. Undefined means it will start now.
     * @param options.expirationTime Expiration time for the order, in UTC seconds.
     * @param options.paymentTokenAddress ERC20 address for the payment token in the order. If unspecified, defaults to ETH
     * @param options.buyerAddress Optional address that's allowed to purchase this item. If specified, no other address will be able to take the order, unless its value is the null address.
     * @param options.includeOptionalCreatorFees If true, optional creator fees will be included in the listing. Default: false.
     * @param options.zone Zone for order protection. Defaults to no zone.
     * @returns The {@link OrderV2} that was created.
     *
     * @throws Error if the asset does not contain a token id.
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if the amount is not greater than 0.
     * @throws Error if paymentTokenAddress is not WETH on anything other than Ethereum mainnet.
     */
    createListing({ asset, accountAddress, amount, quantity, domain, salt, listingTime, expirationTime, paymentTokenAddress, buyerAddress, includeOptionalCreatorFees, zone, }: {
        asset: AssetWithTokenId;
        accountAddress: string;
        amount: BigNumberish;
        quantity?: BigNumberish;
        domain?: string;
        salt?: BigNumberish;
        listingTime?: number;
        expirationTime?: number;
        paymentTokenAddress?: string;
        buyerAddress?: string;
        includeOptionalCreatorFees?: boolean;
        zone?: string;
    }): Promise<OrderV2>;
    /**
     * Create and submit multiple listings using Seaport's bulk order creation.
     * This method uses a single signature for all listings and submits them individually to the OpenSea API with rate limit handling.
     * All listings must be from the same account address.
     *
     * Note: If only one listing is provided, this method will use a normal order signature instead of a bulk signature,
     * as bulk signatures are more expensive to decode on-chain due to the merkle proof verification.
     *
     * @param options
     * @param options.listings Array of listing parameters. Each listing requires asset, amount, and optionally other listing parameters.
     * @param options.accountAddress Address of the wallet making the listings
     * @param options.continueOnError If true, continue submitting remaining listings even if some fail. Default: false (throw on first error).
     * @param options.onProgress Optional callback for progress updates. Called after each listing is submitted (successfully or not).
     * @returns {@link BulkOrderResult} containing successful orders and any failures.
     *
     * @throws Error if listings array is empty
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if any asset does not contain a token id.
     * @throws Error if continueOnError is false and any submission fails.
     */
    createBulkListings({ listings, accountAddress, continueOnError, onProgress, }: {
        listings: Array<{
            asset: AssetWithTokenId;
            amount: BigNumberish;
            quantity?: BigNumberish;
            domain?: string;
            salt?: BigNumberish;
            listingTime?: number;
            expirationTime?: number;
            paymentTokenAddress?: string;
            buyerAddress?: string;
            includeOptionalCreatorFees?: boolean;
            zone?: string;
        }>;
        accountAddress: string;
        continueOnError?: boolean;
        onProgress?: (completed: number, total: number) => void;
    }): Promise<BulkOrderResult>;
    /**
     * Create and submit multiple offers using Seaport's bulk order creation.
     * This method uses a single signature for all offers and submits them individually to the OpenSea API with rate limit handling.
     * All offers must be from the same account address.
     *
     * Note: If only one offer is provided, this method will use a normal order signature instead of a bulk signature,
     * as bulk signatures are more expensive to decode on-chain due to the merkle proof verification.
     *
     * @param options
     * @param options.offers Array of offer parameters. Each offer requires asset, amount, and optionally other offer parameters.
     * @param options.accountAddress Address of the wallet making the offers
     * @param options.continueOnError If true, continue submitting remaining offers even if some fail. Default: false (throw on first error).
     * @param options.onProgress Optional callback for progress updates. Called after each offer is submitted (successfully or not).
     * @returns {@link BulkOrderResult} containing successful orders and any failures.
     *
     * @throws Error if offers array is empty
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if any asset does not contain a token id.
     * @throws Error if continueOnError is false and any submission fails.
     */
    createBulkOffers({ offers, accountAddress, continueOnError, onProgress, }: {
        offers: Array<{
            asset: AssetWithTokenId;
            amount: BigNumberish;
            quantity?: BigNumberish;
            domain?: string;
            salt?: BigNumberish;
            expirationTime?: BigNumberish;
            paymentTokenAddress?: string;
            zone?: string;
        }>;
        accountAddress: string;
        continueOnError?: boolean;
        onProgress?: (completed: number, total: number) => void;
    }): Promise<BulkOrderResult>;
    /**
     * Create and submit a collection offer.
     * @param options
     * @param options.collectionSlug Identifier for the collection.
     * @param options.accountAddress Address of the wallet making the offer.
     * @param options.amount Amount in decimal format (e.g., "1.5" for 1.5 ETH, not wei). Automatically converted to base units.
     * @param options.quantity Number of assets to bid for.
     * @param options.domain Optional domain for on-chain attribution. Hashed and included in salt. This can be used for on-chain order attribution to assist with analytics.
     * @param options.salt Arbitrary salt. Auto-generated if not provided.
     * @param options.expirationTime Expiration time for the order, in UTC seconds.
     * @param options.paymentTokenAddress ERC20 address for the payment token in the order. If unspecified, defaults to WETH.
     * @param options.offerProtectionEnabled Use signed zone for protection against disabled items. Default: true.
     * @param options.traitType If defined, the trait name to create the collection offer for.
     * @param options.traitValue If defined, the trait value to create the collection offer for.
     * @param options.traits If defined, an array of traits to create the multi-trait collection offer for.
     * @returns The {@link CollectionOffer} that was created.
     */
    createCollectionOffer({ collectionSlug, accountAddress, amount, quantity, domain, salt, expirationTime, paymentTokenAddress, offerProtectionEnabled, traitType, traitValue, traits, }: {
        collectionSlug: string;
        accountAddress: string;
        amount: BigNumberish;
        quantity: number;
        domain?: string;
        salt?: BigNumberish;
        expirationTime?: number | string;
        paymentTokenAddress: string;
        offerProtectionEnabled?: boolean;
        traitType?: string;
        traitValue?: string;
        traits?: Array<{
            type: string;
            value: string;
        }>;
    }): Promise<CollectionOffer | null>;
}