opensea-js/lib/sdk/fulfillment.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, Overrides } from "ethers";
import { SDKContext } from "./context";
import { OrdersManager } from "./orders";
import { Listing, Offer, Order } from "../api/types";
import { OrderV2 } from "../orders/types";
import { AssetWithTokenId } from "../types";
/**
 * Manager for order fulfillment and validation operations.
 * Handles fulfilling orders, validating orders onchain, and approving orders.
 */
export declare class FulfillmentManager {
    private context;
    private ordersManager;
    constructor(context: SDKContext, ordersManager: OrdersManager);
    /**
     * Fulfill a private order for a designated address.
     * @param options
     * @param options.order The order to fulfill
     * @param options.accountAddress Address of the wallet taking the order.
     * @param options.domain An optional domain to be hashed and included at the end of fulfillment calldata.
     *                       This can be used for on-chain order attribution to assist with analytics.
     * @param options.overrides Transaction overrides, ignored if not set.
     * @returns Transaction hash of the order.
     */
    private fulfillPrivateOrder;
    /**
     * Fulfill an order for an asset. The order can be either a listing or an offer.
     * Uses the OpenSea API to generate fulfillment transaction data and executes it directly.
     * @param options
     * @param options.order The order to fulfill, a.k.a. "take"
     * @param options.accountAddress Address of the wallet taking the offer.
     * @param options.assetContractAddress Optional address of the NFT contract for criteria offers (e.g., collection offers). Required when fulfilling collection offers.
     * @param options.tokenId Optional token ID for criteria offers (e.g., collection offers). Required when fulfilling collection offers.
     * @param options.unitsToFill Optional number of units to fill. Defaults to 1 for both listings and offers.
     * @param options.recipientAddress Optional recipient address for the NFT when fulfilling a listing. Not applicable for offers.
     * @param options.includeOptionalCreatorFees Whether to include optional creator fees in the fulfillment. If creator fees are already required, this is a no-op. Defaults to false.
     * @param options.overrides Transaction overrides, ignored if not set.
     * @returns Transaction hash of the order.
     *
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if the order's protocol address is not supported by OpenSea. See {@link isValidProtocol}.
     * @throws Error if a signer is not provided (read-only providers cannot fulfill orders).
     * @throws Error if the order hash is not available.
     */
    fulfillOrder({ order, accountAddress, assetContractAddress, tokenId, unitsToFill, recipientAddress, includeOptionalCreatorFees, overrides, }: {
        order: OrderV2 | Order | Listing | Offer;
        accountAddress: string;
        assetContractAddress?: string;
        tokenId?: string;
        unitsToFill?: BigNumberish;
        recipientAddress?: string;
        includeOptionalCreatorFees?: boolean;
        overrides?: Overrides;
    }): Promise<string>;
    /**
     * Returns whether an order is fulfillable.
     * An order may not be fulfillable if a target item's transfer function
     * is locked for some reason, e.g. an item is being rented within a game
     * or trading has been locked for an item type.
     * @param options
     * @param options.order Order to check
     * @param options.accountAddress The account address that will be fulfilling the order
     * @returns True if the order is fulfillable, else False.
     *
     * @throws Error if the order's protocol address is not supported by OpenSea. See {@link isValidProtocol}.
     */
    isOrderFulfillable({ order, accountAddress, }: {
        order: OrderV2;
        accountAddress: string;
    }): Promise<boolean>;
    /**
     * Instead of signing an off-chain order, this methods allows you to approve an order
     * with an on-chain transaction.
     * @param order Order to approve
     * @param domain An optional domain to be hashed and included at the end of fulfillment calldata.  This can be used for on-chain order attribution to assist with analytics.
     * @returns Transaction hash of the approval transaction
     *
     * @throws Error if the accountAddress is not available through wallet or provider.
     * @throws Error if the order's protocol address is not supported by OpenSea. See {@link isValidProtocol}.
     */
    approveOrder(order: OrderV2, domain?: string): Promise<string>;
    /**
     * Validates an order onchain using Seaport's validate() method. This submits the order onchain
     * and pre-validates the order using Seaport, which makes it cheaper to fulfill since a signature
     * is not needed to be verified during fulfillment for the order, but is not strictly required
     * and the alternative is orders can be submitted to the API for free instead of sent onchain.
     * @param orderComponents Order components to validate onchain
     * @param accountAddress Address of the wallet that will pay the gas to validate the order
     * @returns Transaction hash of the validation transaction
     *
     * @throws Error if the accountAddress is not available through wallet or provider.
     */
    validateOrderOnchain(orderComponents: OrderComponents, accountAddress: string): Promise<string>;
    /**
     * Create and validate a listing onchain. Combines order building with onchain validation.
     * Validation costs gas upfront but makes fulfillment cheaper (no signature verification needed).
     * @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.
     * @param options.salt Arbitrary salt. Auto-generated if not provided.
     * @param options.listingTime When order becomes fulfillable (UTC seconds). Defaults to now.
     * @param options.expirationTime Expiration time (UTC seconds).
     * @param options.paymentTokenAddress Payment token address. Defaults to ETH.
     * @param options.buyerAddress Optional buyer restriction. Only this address can purchase.
     * @param options.includeOptionalCreatorFees Include optional creator fees. Default: false.
     * @param options.zone Zone for order protection. Defaults to no zone.
     * @returns Transaction hash
     *
     * @throws Error if asset missing token id or accountAddress unavailable.
     */
    createListingAndValidateOnchain({ 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<string>;
    /**
     * Create and validate an offer onchain. Combines order building with onchain validation.
     * Validation costs gas upfront but makes fulfillment cheaper (no signature verification needed).
     * @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 (UTC seconds).
     * @param options.paymentTokenAddress Payment token address. Defaults to WETH.
     * @param options.zone Zone for order protection. Defaults to chain's signed zone.
     * @returns Transaction hash
     *
     * @throws Error if asset missing token id or accountAddress unavailable.
     */
    createOfferAndValidateOnchain({ 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<string>;
}