Add multi-trait offers

.gitignore

@@ -78,3 +78,5 @@ yarn.lock
 
 # Local Claude settings
 .claude/settings.local.json
+
+examples/

src/api/api.ts

@@ -326,6 +326,7 @@ export class OpenSeaAPI {
    * @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.
    */
   public async buildOffer(
@@ -335,6 +336,7 @@ export class OpenSeaAPI {
     offerProtectionEnabled = true,
     traitType?: string,
     traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
   ): Promise<BuildOfferResponse> {
     return this.offersAPI.buildOffer(
       offererAddress,
@@ -343,6 +345,7 @@ export class OpenSeaAPI {
       offerProtectionEnabled,
       traitType,
       traitValue,
+      traits,
     );
   }
 
@@ -363,19 +366,22 @@ export class OpenSeaAPI {
    * @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.
    */
   public async postCollectionOffer(
     order: ProtocolData,
     slug: string,
     traitType?: string,
     traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
   ): Promise<CollectionOffer | null> {
     return this.offersAPI.postCollectionOffer(
       order,
       slug,
       traitType,
       traitValue,
+      traits,
     );
   }
 

src/api/offers.ts

@@ -99,21 +99,39 @@ export class OffersAPI {
     offerProtectionEnabled = true,
     traitType?: string,
     traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
   ): Promise<BuildOfferResponse> {
+    // Validate trait parameters
+    if (traits && traits.length > 0 && (traitType || traitValue)) {
+      throw new Error(
+        "Cannot use both 'traits' array and individual 'traitType'/'traitValue' parameters. Please use only one approach.",
+      );
+    }
     if (traitType || traitValue) {
       if (!traitType || !traitValue) {
         throw new Error(
           "Both traitType and traitValue must be defined if one is defined.",
         );
       }
     }
+    if (traits && traits.length > 0) {
+      // Validate each trait in the array has both type and value
+      for (const trait of traits) {
+        if (!trait.type || !trait.value) {
+          throw new Error(
+            "Each trait must have both 'type' and 'value' properties.",
+          );
+        }
+      }
+    }
     const payload = getBuildCollectionOfferPayload(
       offererAddress,
       quantity,
       collectionSlug,
       offerProtectionEnabled,
       traitType,
       traitValue,
+      traits,
     );
     const response = await this.fetcher.post<BuildOfferResponse>(
       getBuildOfferPath(),
@@ -141,12 +159,14 @@ export class OffersAPI {
     slug: string,
     traitType?: string,
     traitValue?: string,
+    traits?: Array<{ type: string; value: string }>,
   ): Promise<CollectionOffer | null> {
     const payload = getPostCollectionOfferPayload(
       slug,
       order,
       traitType,
       traitValue,
+      traits,
     );
     return await this.fetcher.post<CollectionOffer>(
       getPostCollectionOfferPath(),

src/api/types.ts

@@ -33,8 +33,10 @@ type Criteria = {
   contract: ContractCriteria;
   /** Represents a list of token ids which can be used to fulfill the criteria offer. */
   encoded_token_ids?: string;
-  /** The trait for the criteria */
+  /** The trait for the criteria (single trait) */
   trait?: TraitCriteria;
+  /** Multiple traits for the criteria (multi-trait offers) */
+  traits?: TraitCriteria[];
 };
 
 /**

src/orders/utils.ts

@@ -16,6 +16,7 @@ export const getPostCollectionOfferPayload = (
   protocol_data: ProtocolData,
   traitType?: string,
   traitValue?: string,
+  traits?: Array<{ type: string; value: string }>,
 ) => {
   const payload = {
     criteria: {
@@ -24,7 +25,13 @@ export const getPostCollectionOfferPayload = (
     protocol_data,
     protocol_address: DEFAULT_SEAPORT_CONTRACT_ADDRESS,
   };
-  if (traitType && traitValue) {
+
+  // Prioritize traits array if provided
+  if (traits && traits.length > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (payload.criteria as any).traits = traits;
+  } else if (traitType && traitValue) {
+    // Fallback to single trait for backward compatibility
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (payload.criteria as any).trait = {
       type: traitType,
@@ -41,6 +48,7 @@ export const getBuildCollectionOfferPayload = (
   offerProtectionEnabled: boolean,
   traitType?: string,
   traitValue?: string,
+  traits?: Array<{ type: string; value: string }>,
 ) => {
   const payload = {
     offerer: offererAddress,
@@ -53,7 +61,13 @@ export const getBuildCollectionOfferPayload = (
     protocol_address: DEFAULT_SEAPORT_CONTRACT_ADDRESS,
     offer_protection_enabled: offerProtectionEnabled,
   };
-  if (traitType && traitValue) {
+
+  // Prioritize traits array if provided
+  if (traits && traits.length > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (payload.criteria as any).traits = traits;
+  } else if (traitType && traitValue) {
+    // Fallback to single trait for backward compatibility
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (payload.criteria as any).trait = {
       type: traitType,

src/sdk.ts

@@ -434,6 +434,7 @@ export class OpenSeaSDK {
    * @param options.offerProtectionEnabled Build the offer on OpenSea's signed zone to provide offer protections from receiving an item which is disabled from trading.
    * @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.
    */
   public async createCollectionOffer({
@@ -448,6 +449,7 @@ export class OpenSeaSDK {
     offerProtectionEnabled = true,
     traitType,
     traitValue,
+    traits,
   }: {
     collectionSlug: string;
     accountAddress: string;
@@ -460,6 +462,7 @@ export class OpenSeaSDK {
     offerProtectionEnabled?: boolean;
     traitType?: string;
     traitValue?: string;
+    traits?: Array<{ type: string; value: string }>;
   }): Promise<CollectionOffer | null> {
     return this._ordersManager.createCollectionOffer({
       collectionSlug,
@@ -473,6 +476,7 @@ export class OpenSeaSDK {
       offerProtectionEnabled,
       traitType,
       traitValue,
+      traits,
     });
   }
 

src/sdk/orders.ts

@@ -1052,6 +1052,7 @@ export class OrdersManager {
    * @param options.offerProtectionEnabled Build the offer on OpenSea's signed zone to provide offer protections from receiving an item which is disabled from trading.
    * @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.
    */
   async createCollectionOffer({
@@ -1066,6 +1067,7 @@ export class OrdersManager {
     offerProtectionEnabled = true,
     traitType,
     traitValue,
+    traits,
   }: {
     collectionSlug: string;
     accountAddress: string;
@@ -1078,6 +1080,7 @@ export class OrdersManager {
     offerProtectionEnabled?: boolean;
     traitType?: string;
     traitValue?: string;
+    traits?: Array<{ type: string; value: string }>;
   }): Promise<CollectionOffer | null> {
     await this.context.requireAccountIsAvailable(accountAddress);
 
@@ -1089,6 +1092,7 @@ export class OrdersManager {
       offerProtectionEnabled,
       traitType,
       traitValue,
+      traits,
     );
     const item = buildOfferResult.partialParameters.consideration[0];
     const convertedConsiderationItem = {
@@ -1143,6 +1147,7 @@ export class OrdersManager {
       collectionSlug,
       traitType,
       traitValue,
+      traits,
     );
   }
 }