Release v10.3.1

Author: ryanio

AGENTS.md

@@ -43,7 +43,7 @@ When reviewing changes to this package, verify:
 
 2. **Dual provider support**: Both `OpenSeaSDK` (ethers) and `OpenSeaViemSDK` (viem) must work. Changes to `BaseOpenSeaSDK` affect both. If adding provider-specific logic, ensure both adapters in `src/provider/` are updated.
 
-3. **`@opensea/api-types` dependency**: The SDK imports types from the workspace `@opensea/api-types` package. If the OpenAPI spec changes, rebuild api-types first (`pnpm --filter @opensea/api-types run build`) before testing the SDK.
+3. **`@opensea/api-types` dependency**: The SDK imports types from the workspace `@opensea/api-types` package. If the OpenAPI spec changes, rebuild api-types first (`pnpm --filter @opensea/api-types run build`) before testing the SDK. **Never hand-roll API request/response types in `src/api/types.ts`** — always import from `@opensea/api-types` (or re-export through `src/api/types.ts`) using the canonical OpenAPI schema names. The `pnpm check-api-paths` CI guardrail will fail the build if `src/api/apiPaths.ts` references a URL that isn't in `packages/api-types/opensea-api.json`. See the top-level [AGENTS.md → "Adding a new OpenSea API endpoint"](../../AGENTS.md#adding-a-new-opensea-api-endpoint-to-the-sdk-or-cli) for the full flow.
 
 4. **Seaport integration**: Order creation and fulfillment flows use `@opensea/seaport-js`. Changes to order parameters, consideration items, or fulfillment logic must be tested against the Seaport contract behavior.
 

CHANGELOG.md

@@ -1,5 +1,34 @@
 # @opensea/sdk
 
+## 10.3.1
+
+### Patch Changes
+
+- 961f2c5: fix(api): consume cross-chain fulfillment types from `@opensea/api-types`
+
+  The cross-chain fulfillment types added in the previous release were hand-rolled in `packages/sdk/src/api/types.ts` and `packages/cli/src/types/api.ts` rather than generated from the OpenAPI spec. This release pulls them from `@opensea/api-types` (the source of truth) so future spec changes flow through automatically.
+
+  **`@opensea/api-types`**: Adds named exports for `CrossChainFulfillmentRequest`, `CrossChainFulfillmentResponse`, `CrossChainPaymentToken`, `FulfillerObject`, and `ListingObject` schemas (regenerated from the production OpenAPI spec).
+
+  **`@opensea/sdk`** _(type rename — minimal-impact since the prior release shipped <1 day ago)_:
+
+  - `CrossChainListing` → `ListingObject`
+  - `CrossChainFulfillmentDataRequest` → `CrossChainFulfillmentRequest`
+  - `CrossChainFulfillmentDataResponse` → `CrossChainFulfillmentResponse`
+  - `CrossChainTransaction` → `SwapTransactionResponse`
+
+  The runtime call signature on `BaseOpenSeaSDK.getCrossChainFulfillmentData()` is unchanged.
+
+  **`@opensea/cli`** _(type rename — same minimal impact)_:
+
+  - `CrossChainFulfillmentTransaction` → `SwapTransactionResponse`
+  - `CrossChainFulfillmentDataResponse` → `CrossChainFulfillmentResponse`
+
+  Adds a new blocking CI check (`pnpm check-api-paths`) that fails when an `/api/v2/...` URL referenced in SDK or CLI source is not present in `packages/api-types/opensea-api.json`. AGENTS docs updated to make the api-types-first flow explicit for new endpoints.
+
+- Updated dependencies [961f2c5]
+  - @opensea/api-types@0.2.3
+
 ## 10.3.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "10.3.0",
+  "version": "10.3.1",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs, tokens, and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",
@@ -45,7 +45,7 @@
   "types": "lib/index.d.ts",
   "dependencies": {
     "@noble/hashes": "^2.0.1",
-    "@opensea/api-types": "^0.2.2",
+    "@opensea/api-types": "^0.2.3",
     "@opensea/seaport-js": "^4.1.1",
     "ethers": "^6.16.0"
   },

src/api/api.ts

@@ -35,8 +35,8 @@ import {
   type CancelOrderResponse,
   type CollectionOffer,
   CollectionOrderByOption,
-  type CrossChainFulfillmentDataRequest,
-  type CrossChainFulfillmentDataResponse,
+  type CrossChainFulfillmentRequest,
+  type CrossChainFulfillmentResponse,
   type DropMintRequest,
   type DropMintResponse,
   type GetAccountTokensArgs,
@@ -326,11 +326,11 @@ export class OpenSeaAPI {
    * 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
+   * @returns The {@link CrossChainFulfillmentResponse} with ordered transactions to sign and submit
    */
   public async getCrossChainFulfillmentData(
-    request: CrossChainFulfillmentDataRequest,
-  ): Promise<CrossChainFulfillmentDataResponse> {
+    request: CrossChainFulfillmentRequest,
+  ): Promise<CrossChainFulfillmentResponse> {
     return this.listingsAPI.getCrossChainFulfillmentData(request)
   }
 

src/api/listings.ts

@@ -9,8 +9,8 @@ import {
 } from "./apiPaths"
 import type { Fetcher } from "./fetcher"
 import {
-  type CrossChainFulfillmentDataRequest,
-  type CrossChainFulfillmentDataResponse,
+  type CrossChainFulfillmentRequest,
+  type CrossChainFulfillmentResponse,
   encodeTraitsParam,
   type GetBestListingResponse,
   type GetListingsResponse,
@@ -137,9 +137,9 @@ export class ListingsAPI {
    * @param request The cross-chain fulfillment request
    */
   async getCrossChainFulfillmentData(
-    request: CrossChainFulfillmentDataRequest,
-  ): Promise<CrossChainFulfillmentDataResponse> {
-    return this.fetcher.post<CrossChainFulfillmentDataResponse>(
+    request: CrossChainFulfillmentRequest,
+  ): Promise<CrossChainFulfillmentResponse> {
+    return this.fetcher.post<CrossChainFulfillmentResponse>(
       getCrossChainFulfillmentDataPath(),
       request,
     )

src/api/types.ts

@@ -1298,60 +1298,15 @@ export type ValidateMetadataResponse = {
 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[]
-}
+// Re-exported from @opensea/api-types so consumers can keep importing them
+// from @opensea/sdk. See packages/api-types — these are generated from the
+// OpenSea v2 OpenAPI spec.
+
+export type {
+  CrossChainFulfillmentRequest,
+  CrossChainFulfillmentResponse,
+  CrossChainPaymentToken,
+  FulfillerObject,
+  ListingObject,
+  SwapTransactionResponse,
+} from "@opensea/api-types"

test/api/listings.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test, vi } from "vitest"
 import { ListingsAPI } from "../../src/api/listings"
 import type {
-  CrossChainFulfillmentDataResponse,
+  CrossChainFulfillmentResponse,
   GetBestListingResponse,
   GetListingsResponse,
   Listing,
@@ -730,7 +730,7 @@ describe("API: ListingsAPI", () => {
 
   describe("getCrossChainFulfillmentData", () => {
     test("posts to the correct endpoint with the full request body", async () => {
-      const mockResponse: CrossChainFulfillmentDataResponse = {
+      const mockResponse: CrossChainFulfillmentResponse = {
         transactions: [
           { chain: "ethereum", to: "0xabc", data: "0x123", value: "0" },
         ],