Release v10.3.0

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,19 @@
 # @opensea/sdk
 
+## 10.3.0
+
+### Minor Changes
+
+- fc44d9f: feat: add cross-chain fulfillment support
+
+  Add support for the new `POST /api/v2/listings/cross_chain_fulfillment_data` endpoint across SDK, CLI, and skill packages.
+
+  **SDK**: New `getCrossChainFulfillmentData()` method on both the API client and the base SDK class. Accepts listings, fulfiller, payment token (chain + address), and optional recipient. Returns ordered transactions to sign and submit.
+
+  **CLI**: New `listings cross-chain-fulfill` subcommand with `--hashes`, `--listing-chain`, `--protocol-address`, `--fulfiller`, `--payment-chain`, `--payment-token`, and optional `--recipient` flags. Supports sweeping multiple listings via comma-separated hashes.
+
+  **Skill**: New `opensea-cross-chain-fulfill.sh` script and updated SKILL.md with cross-chain buying workflow documentation.
+
 ## 10.2.1
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "10.2.1",
+  "version": "10.3.0",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs, tokens, and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",

src/api/api.ts

@@ -35,6 +35,8 @@ import {
   type CancelOrderResponse,
   type CollectionOffer,
   CollectionOrderByOption,
+  type CrossChainFulfillmentDataRequest,
+  type CrossChainFulfillmentDataResponse,
   type DropMintRequest,
   type DropMintResponse,
   type GetAccountTokensArgs,
@@ -319,6 +321,19 @@ export class OpenSeaAPI {
     )
   }
 
+  /**
+   * Get cross-chain fulfillment data for one or more listings.
+   * Supports same-chain, cross-token, and cross-chain purchases (up to 50 listings).
+   * All listings must be EVM (Seaport orders). Payment can be from any chain (EVM or SVM).
+   * @param request The cross-chain fulfillment request containing listings, fulfiller, payment, and optional recipient
+   * @returns The {@link CrossChainFulfillmentDataResponse} with ordered transactions to sign and submit
+   */
+  public async getCrossChainFulfillmentData(
+    request: CrossChainFulfillmentDataRequest,
+  ): Promise<CrossChainFulfillmentDataResponse> {
+    return this.listingsAPI.getCrossChainFulfillmentData(request)
+  }
+
   /**
    * 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

src/api/apiPaths.ts

@@ -231,6 +231,10 @@ export const getTokenGroupPath = (slug: string) => {
   return `${API_V2_PREFIX}/token-groups/${slug}`
 }
 
+export const getCrossChainFulfillmentDataPath = () => {
+  return `${API_V2_PREFIX}/listings/cross_chain_fulfillment_data`
+}
+
 export const getInstantApiKeyPath = () => {
   return `${API_V2_PREFIX}/auth/keys`
 }

src/api/listings.ts

@@ -4,10 +4,13 @@ import {
   getAllListingsAPIPath,
   getBestListingAPIPath,
   getBestListingsAPIPath,
+  getCrossChainFulfillmentDataPath,
   getOrdersAPIPath,
 } from "./apiPaths"
 import type { Fetcher } from "./fetcher"
 import {
+  type CrossChainFulfillmentDataRequest,
+  type CrossChainFulfillmentDataResponse,
   encodeTraitsParam,
   type GetBestListingResponse,
   type GetListingsResponse,
@@ -127,4 +130,18 @@ export class ListingsAPI {
     )
     return response
   }
+
+  /**
+   * Get cross-chain fulfillment data for one or more listings.
+   * Supports same-chain, cross-token, and cross-chain purchases.
+   * @param request The cross-chain fulfillment request
+   */
+  async getCrossChainFulfillmentData(
+    request: CrossChainFulfillmentDataRequest,
+  ): Promise<CrossChainFulfillmentDataResponse> {
+    return this.fetcher.post<CrossChainFulfillmentDataResponse>(
+      getCrossChainFulfillmentDataPath(),
+      request,
+    )
+  }
 }

src/api/types.ts

@@ -1296,3 +1296,62 @@ export type ValidateMetadataResponse = {
  * @category API Response Types
  */
 export type GetNFTMetadataResponse = AssetMetadataResponse
+
+// ─── Cross-chain fulfillment types ──────────────────────────────────
+
+/**
+ * A single listing to fulfill in a cross-chain fulfillment request.
+ * @category API Models
+ */
+export type CrossChainListing = {
+  /** Order hash (66 chars, starts with 0x) */
+  hash: string
+  /** Chain slug where the listing lives (must be EVM) */
+  chain: string
+  /** Seaport contract address */
+  protocol_address: string
+}
+
+/**
+ * Request body for the cross-chain fulfillment endpoint.
+ * @category API Query Args
+ */
+export type CrossChainFulfillmentDataRequest = {
+  /** Array of listings to fulfill (up to 50) */
+  listings: CrossChainListing[]
+  /** The buyer's wallet */
+  fulfiller: { address: string }
+  /** Payment token details */
+  payment: {
+    /** Chain slug of the payment token (EVM or SVM) */
+    chain: string
+    /** Payment token contract address (0x0...0 for native, Base58 for Solana) */
+    token_address: string
+  }
+  /** Optional: different recipient address for the NFTs */
+  recipient?: string
+}
+
+/**
+ * A single transaction returned by the cross-chain fulfillment endpoint.
+ * @category API Response Types
+ */
+export type CrossChainTransaction = {
+  /** Chain slug for the transaction */
+  chain: string
+  /** Contract address to call */
+  to: string
+  /** Encoded calldata */
+  data: string
+  /** Wei amount as string */
+  value: string
+}
+
+/**
+ * Response from the cross-chain fulfillment endpoint.
+ * @category API Response Types
+ */
+export type CrossChainFulfillmentDataResponse = {
+  /** Ordered list of transactions to sign and submit */
+  transactions: CrossChainTransaction[]
+}

src/sdk/base.ts

@@ -359,6 +359,46 @@ export class BaseOpenSeaSDK {
     return this._fulfillmentManager.fulfillPrivateOrder(options)
   }
 
+  /**
+   * Get cross-chain fulfillment data for one or more listings.
+   * Supports same-chain, cross-token, and cross-chain purchases (up to 50 listings).
+   * All listings must be EVM (Seaport orders). Payment can be from any chain (EVM or SVM).
+   * Returns an ordered list of transactions to sign and submit.
+   * @param options
+   * @param options.listings Array of listings to fulfill (order hash, chain, protocol address)
+   * @param options.fulfillerAddress The buyer's wallet address
+   * @param options.paymentChain Chain slug of the payment token (EVM or SVM)
+   * @param options.paymentTokenAddress Payment token contract address (0x0...0 for native)
+   * @param options.recipientAddress Optional different recipient for the NFTs
+   */
+  public async getCrossChainFulfillmentData(options: {
+    listings: Array<{
+      hash: string
+      chain: string
+      protocolAddress: string
+    }>
+    fulfillerAddress: string
+    paymentChain: string
+    paymentTokenAddress: string
+    recipientAddress?: string
+  }) {
+    return this.api.getCrossChainFulfillmentData({
+      listings: options.listings.map(l => ({
+        hash: l.hash,
+        chain: l.chain,
+        protocol_address: l.protocolAddress,
+      })),
+      fulfiller: { address: options.fulfillerAddress },
+      payment: {
+        chain: options.paymentChain,
+        token_address: options.paymentTokenAddress,
+      },
+      ...(options.recipientAddress
+        ? { recipient: options.recipientAddress }
+        : {}),
+    })
+  }
+
   /** Returns whether an order is fulfillable. */
   public async isOrderFulfillable(options: {
     order: OrderV2

test/api/listings.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test, vi } from "vitest"
 import { ListingsAPI } from "../../src/api/listings"
 import type {
+  CrossChainFulfillmentDataResponse,
   GetBestListingResponse,
   GetListingsResponse,
   Listing,
@@ -11,11 +12,17 @@ import { createMockFetcher } from "../fixtures/fetcher"
 
 describe("API: ListingsAPI", () => {
   let mockGet: ReturnType<typeof vi.fn>
+  let mockPost: ReturnType<typeof vi.fn>
   let listingsAPI: ListingsAPI
 
   beforeEach(() => {
-    const { fetcher, mockGet: getMock } = createMockFetcher()
+    const {
+      fetcher,
+      mockGet: getMock,
+      mockPost: postMock,
+    } = createMockFetcher()
     mockGet = getMock
+    mockPost = postMock
     listingsAPI = new ListingsAPI(fetcher, Chain.Mainnet)
   })
 
@@ -720,4 +727,125 @@ describe("API: ListingsAPI", () => {
       expect(result.listings[0].remaining_quantity).toBe(3)
     })
   })
+
+  describe("getCrossChainFulfillmentData", () => {
+    test("posts to the correct endpoint with the full request body", async () => {
+      const mockResponse: CrossChainFulfillmentDataResponse = {
+        transactions: [
+          { chain: "ethereum", to: "0xabc", data: "0x123", value: "0" },
+        ],
+      }
+
+      mockPost.mockResolvedValue(mockResponse)
+
+      const result = await listingsAPI.getCrossChainFulfillmentData({
+        listings: [
+          {
+            hash: "0xorderhash",
+            chain: "ethereum",
+            protocol_address: "0xseaport",
+          },
+        ],
+        fulfiller: { address: "0xbuyer" },
+        payment: {
+          chain: "base",
+          token_address: "0x0000000000000000000000000000000000000000",
+        },
+      })
+
+      expect(mockPost).toHaveBeenCalledWith(
+        "/api/v2/listings/cross_chain_fulfillment_data",
+        {
+          listings: [
+            {
+              hash: "0xorderhash",
+              chain: "ethereum",
+              protocol_address: "0xseaport",
+            },
+          ],
+          fulfiller: { address: "0xbuyer" },
+          payment: {
+            chain: "base",
+            token_address: "0x0000000000000000000000000000000000000000",
+          },
+        },
+      )
+      expect(result.transactions).toHaveLength(1)
+      expect(result.transactions[0].chain).toBe("ethereum")
+    })
+
+    test("includes optional recipient in request", async () => {
+      mockPost.mockResolvedValue({ transactions: [] })
+
+      await listingsAPI.getCrossChainFulfillmentData({
+        listings: [
+          {
+            hash: "0xhash",
+            chain: "ethereum",
+            protocol_address: "0xseaport",
+          },
+        ],
+        fulfiller: { address: "0xbuyer" },
+        payment: {
+          chain: "base",
+          token_address: "0x0000000000000000000000000000000000000000",
+        },
+        recipient: "0xrecipient",
+      })
+
+      expect(mockPost).toHaveBeenCalledWith(
+        "/api/v2/listings/cross_chain_fulfillment_data",
+        expect.objectContaining({
+          recipient: "0xrecipient",
+        }),
+      )
+    })
+
+    test("supports multiple listings for sweep", async () => {
+      mockPost.mockResolvedValue({
+        transactions: [
+          { chain: "ethereum", to: "0xabc", data: "0x111", value: "0" },
+          { chain: "ethereum", to: "0xabc", data: "0x222", value: "0" },
+        ],
+      })
+
+      const result = await listingsAPI.getCrossChainFulfillmentData({
+        listings: [
+          {
+            hash: "0xhash1",
+            chain: "ethereum",
+            protocol_address: "0xseaport",
+          },
+          {
+            hash: "0xhash2",
+            chain: "ethereum",
+            protocol_address: "0xseaport",
+          },
+        ],
+        fulfiller: { address: "0xbuyer" },
+        payment: {
+          chain: "base",
+          token_address: "0x0000000000000000000000000000000000000000",
+        },
+      })
+
+      expect(result.transactions).toHaveLength(2)
+      expect(mockPost.mock.calls[0][1].listings).toHaveLength(2)
+    })
+
+    test("throws on API error", async () => {
+      mockPost.mockRejectedValue(new Error("Bad Request"))
+
+      await expect(
+        listingsAPI.getCrossChainFulfillmentData({
+          listings: [],
+          fulfiller: { address: "0xbuyer" },
+          payment: {
+            chain: "base",
+            token_address: "0x0000000000000000000000000000000000000000",
+          },
+        }),
+      ).rejects.toThrow("Bad Request")
+    })
+  })
 })