feat: add includeOptionalCreatorFees to fulfillOrder

src/api/api.ts

@@ -280,6 +280,7 @@ export class OpenSeaAPI {
    * @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}
    */
   public async generateFulfillmentData(
@@ -291,6 +292,7 @@ export class OpenSeaAPI {
     tokenId?: string,
     unitsToFill?: string,
     recipientAddress?: string,
+    includeOptionalCreatorFees: boolean = false,
   ): Promise<FulfillmentDataResponse> {
     return this.ordersAPI.generateFulfillmentData(
       fulfillerAddress,
@@ -301,6 +303,7 @@ export class OpenSeaAPI {
       tokenId,
       unitsToFill,
       recipientAddress,
+      includeOptionalCreatorFees,
     );
   }
 

src/api/orders.ts

@@ -137,6 +137,7 @@ export class OrdersAPI {
     tokenId?: string,
     unitsToFill?: string,
     recipientAddress?: string,
+    includeOptionalCreatorFees: boolean = false,
   ): Promise<FulfillmentDataResponse> {
     let payload: object | null = null;
     if (side === OrderSide.LISTING) {
@@ -149,6 +150,7 @@ export class OrdersAPI {
         tokenId,
         unitsToFill,
         recipientAddress,
+        includeOptionalCreatorFees,
       );
     } else {
       payload = getFulfillOfferPayload(
@@ -159,6 +161,7 @@ export class OrdersAPI {
         assetContractAddress,
         tokenId,
         unitsToFill,
+        includeOptionalCreatorFees,
       );
     }
     const response = await this.fetcher.post<FulfillmentDataResponse>(

src/orders/utils.ts

@@ -91,6 +91,7 @@ export const getFulfillListingPayload = (
   tokenId?: string,
   unitsToFill: string = "1",
   recipientAddress?: string,
+  includeOptionalCreatorFees: boolean = false,
 ) => {
   const payload: {
     listing: {
@@ -107,6 +108,7 @@ export const getFulfillListingPayload = (
     };
     units_to_fill: string;
     recipient?: string;
+    include_optional_creator_fees: boolean;
   } = {
     listing: {
       hash: order_hash,
@@ -117,6 +119,7 @@ export const getFulfillListingPayload = (
       address: fulfillerAddress,
     },
     units_to_fill: unitsToFill,
+    include_optional_creator_fees: includeOptionalCreatorFees,
   };
 
   // Add consideration for criteria listings if needed
@@ -143,6 +146,7 @@ export const getFulfillOfferPayload = (
   assetContractAddress?: string,
   tokenId?: string,
   unitsToFill: string = "1",
+  includeOptionalCreatorFees: boolean = false,
 ) => {
   const payload: {
     offer: {
@@ -158,6 +162,7 @@ export const getFulfillOfferPayload = (
       token_id: string;
     };
     units_to_fill: string;
+    include_optional_creator_fees: boolean;
   } = {
     offer: {
       hash: order_hash,
@@ -168,6 +173,7 @@ export const getFulfillOfferPayload = (
       address: fulfillerAddress,
     },
     units_to_fill: unitsToFill,
+    include_optional_creator_fees: includeOptionalCreatorFees,
   };
 
   // Add consideration for criteria offers (e.g., collection offers)

src/sdk.ts

@@ -490,6 +490,7 @@ export class OpenSeaSDK {
    * @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.
    *
@@ -505,6 +506,7 @@ export class OpenSeaSDK {
     tokenId,
     unitsToFill,
     recipientAddress,
+    includeOptionalCreatorFees = false,
     overrides,
   }: {
     order: OrderV2 | Order | Listing | Offer;
@@ -513,6 +515,7 @@ export class OpenSeaSDK {
     tokenId?: string;
     unitsToFill?: BigNumberish;
     recipientAddress?: string;
+    includeOptionalCreatorFees?: boolean;
     overrides?: Overrides;
   }): Promise<string> {
     return this._fulfillmentManager.fulfillOrder({
@@ -522,6 +525,7 @@ export class OpenSeaSDK {
       tokenId,
       unitsToFill,
       recipientAddress,
+      includeOptionalCreatorFees,
       overrides,
     });
   }

src/sdk/fulfillment.ts

@@ -99,6 +99,7 @@ export class FulfillmentManager {
    * @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.
    *
@@ -114,6 +115,7 @@ export class FulfillmentManager {
     tokenId,
     unitsToFill,
     recipientAddress,
+    includeOptionalCreatorFees = false,
     overrides,
   }: {
     order: OrderV2 | Order | Listing | Offer;
@@ -122,6 +124,7 @@ export class FulfillmentManager {
     tokenId?: string;
     unitsToFill?: BigNumberish;
     recipientAddress?: string;
+    includeOptionalCreatorFees?: boolean;
     overrides?: Overrides;
   }): Promise<string> {
     await this.context.requireAccountIsAvailable(accountAddress);
@@ -167,6 +170,7 @@ export class FulfillmentManager {
       tokenId,
       unitsToFillStr,
       recipientAddress,
+      includeOptionalCreatorFees,
     );
 
     // Use the transaction data returned by the API

test/orders/utils.spec.ts

@@ -352,10 +352,27 @@ suite("Orders: utils", () => {
           address: "0xFulfiller",
         },
         units_to_fill: "1",
+        include_optional_creator_fees: false,
       });
       expect(result.consideration).to.be.undefined;
     });
 
+    test("should include includeOptionalCreatorFees when set to true", () => {
+      const result = getFulfillListingPayload(
+        "0xFulfiller",
+        "0xOrderHash",
+        "0xProtocol",
+        Chain.Mainnet,
+        undefined,
+        undefined,
+        "1",
+        undefined,
+        true,
+      );
+
+      expect(result.include_optional_creator_fees).to.be.true;
+    });
+
     test("should add consideration for criteria listings", () => {
       const result = getFulfillListingPayload(
         "0xFulfiller",
@@ -417,6 +434,7 @@ suite("Orders: utils", () => {
           address: "0xFulfiller",
         },
         units_to_fill: "1",
+        include_optional_creator_fees: false,
       });
       expect(result.consideration).to.be.undefined;
     });
@@ -436,6 +454,21 @@ suite("Orders: utils", () => {
         token_id: "456",
       });
     });
+
+    test("should include includeOptionalCreatorFees when set to true", () => {
+      const result = getFulfillOfferPayload(
+        "0xFulfiller",
+        "0xOrderHash",
+        "0xProtocol",
+        Chain.Polygon,
+        undefined,
+        undefined,
+        "1",
+        true,
+      );
+
+      expect(result.include_optional_creator_fees).to.be.true;
+    });
   });
 
   suite("deserializeOrder", () => {