Release v1.4.0

ryanio · ryanio · commit c9eda72e7b96 · 2026-05-04T19:05:59.000Z
diff --git a/.agents/rules.md b/.agents/rules.md
@@ -57,14 +57,20 @@ CLI (src/cli.ts)              SDK (src/sdk.ts)
 
 Each domain has both a CLI command file (`src/commands/<domain>.ts`) and an SDK class (`src/sdk.ts`):
 
+- **accounts** - Account profile lookup
+- **auth** - API key request and management
+- **chains** - Chain information and supported networks
 - **collections** - Collection metadata, stats, traits
-- **nfts** - NFT lookup, listing by collection/contract/account, metadata refresh
+- **drops** - NFT drop details, listing, and minting
+- **events** - Marketplace events (sales, transfers, mints, etc.)
+- **health** - API health check
 - **listings** - Active listings (all, best, best-for-nft)
+- **nfts** - NFT lookup, listing by collection/contract/account, metadata refresh
 - **offers** - Offers (all, collection, best-for-nft, trait offers)
-- **events** - Marketplace events (sales, transfers, mints, etc.)
-- **accounts** - Account profile lookup
-- **tokens** - Fungible token trending/top/details
+- **search** - Search collections, NFTs, and accounts
 - **swaps** - Token swap quotes
+- **token-groups** - Token group details and listings
+- **tokens** - Fungible token trending/top/details
 
 ## Conventions
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # @opensea/cli
 
+## 1.4.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.
+
 ## 1.3.0
 
 ### Minor Changes
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
diff --git a/src/commands/listings.ts b/src/commands/listings.ts
@@ -3,7 +3,10 @@ import type { OpenSeaClient } from "../client.js"
 import type { OutputFormat } from "../output.js"
 import { formatOutput } from "../output.js"
 import { addTraitsOption, parseIntOption, parseTraitsOption } from "../parse.js"
-import type { Listing } from "../types/index.js"
+import type {
+  CrossChainFulfillmentDataResponse,
+  Listing,
+} from "../types/index.js"
 
 export function listingsCommand(
   getClient: () => OpenSeaClient,
@@ -69,5 +72,69 @@ export function listingsCommand(
       console.log(formatOutput(result, getFormat()))
     })
 
+  cmd
+    .command("cross-chain-fulfill")
+    .description(
+      "Get cross-chain fulfillment data for one or more listings. " +
+        "Supports same-chain, cross-token, and cross-chain purchases.",
+    )
+    .requiredOption(
+      "--hashes <hashes>",
+      "Comma-separated order hashes to fulfill",
+    )
+    .requiredOption(
+      "--listing-chain <chain>",
+      "Chain slug where the listings live (must be EVM)",
+    )
+    .requiredOption(
+      "--protocol-address <address>",
+      "Seaport contract address for the listings",
+    )
+    .requiredOption("--fulfiller <address>", "Buyer wallet address")
+    .requiredOption(
+      "--payment-chain <chain>",
+      "Chain slug of the payment token (EVM or SVM)",
+    )
+    .requiredOption(
+      "--payment-token <address>",
+      "Payment token contract address (0x0...0 for native)",
+    )
+    .option("--recipient <address>", "Different recipient address for NFTs")
+    .action(
+      async (options: {
+        hashes: string
+        listingChain: string
+        protocolAddress: string
+        fulfiller: string
+        paymentChain: string
+        paymentToken: string
+        recipient?: string
+      }) => {
+        const client = getClient()
+        const hashes = options.hashes.split(",").map(h => h.trim())
+        const listings = hashes.map(hash => ({
+          hash,
+          chain: options.listingChain,
+          protocol_address: options.protocolAddress,
+        }))
+        const body: Record<string, unknown> = {
+          listings,
+          fulfiller: { address: options.fulfiller },
+          payment: {
+            chain: options.paymentChain,
+            token_address: options.paymentToken,
+          },
+        }
+        if (options.recipient) {
+          body.recipient = options.recipient
+        }
+        const result = await client.post<CrossChainFulfillmentDataResponse>(
+          "/api/v2/listings/cross_chain_fulfillment_data",
+          body,
+        )
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
   return cmd
 }
diff --git a/src/sdk.ts b/src/sdk.ts
@@ -13,6 +13,7 @@ import type {
   CollectionPaginatedResponse,
   CollectionStats,
   Contract,
+  CrossChainFulfillmentDataResponse,
   DropDetailedResponse,
   DropMintResponse,
   DropPaginatedResponse,
@@ -345,6 +346,38 @@ class ListingsAPI {
       `/api/v2/listings/collection/${collectionSlug}/nfts/${tokenId}/best`,
     )
   }
+
+  async crossChainFulfillmentData(options: {
+    listings: Array<{
+      hash: string
+      chain: string
+      protocolAddress: string
+    }>
+    fulfillerAddress: string
+    paymentChain: string
+    paymentTokenAddress: string
+    recipient?: string
+  }): Promise<CrossChainFulfillmentDataResponse> {
+    const body: Record<string, unknown> = {
+      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,
+      },
+    }
+    if (options.recipient) {
+      body.recipient = options.recipient
+    }
+    return this.client.post(
+      "/api/v2/listings/cross_chain_fulfillment_data",
+      body,
+    )
+  }
 }
 
 class OffersAPI {
diff --git a/src/types/api.ts b/src/types/api.ts
@@ -311,6 +311,17 @@ export type TokenBalanceSortBy =
   | "ONE_DAY_PRICE_CHANGE"
   | "SEVEN_DAY_PRICE_CHANGE"
 
+export interface CrossChainFulfillmentTransaction {
+  chain: string
+  to: string
+  data: string
+  value: string
+}
+
+export interface CrossChainFulfillmentDataResponse {
+  transactions: CrossChainFulfillmentTransaction[]
+}
+
 export interface ValidateMetadataResponse {
   assetIdentifier: {
     chain: string
diff --git a/test/commands/listings.test.ts b/test/commands/listings.test.ts
@@ -20,6 +20,7 @@ describe("listingsCommand", () => {
     expect(subcommands).toContain("all")
     expect(subcommands).toContain("best")
     expect(subcommands).toContain("best-for-nft")
+    expect(subcommands).toContain("cross-chain-fulfill")
   })
 
   it("all subcommand fetches all listings", async () => {
@@ -60,4 +61,115 @@ describe("listingsCommand", () => {
       "/api/v2/listings/collection/cool-cats/nfts/123/best",
     )
   })
+
+  it("cross-chain-fulfill subcommand posts correct body", async () => {
+    ctx.mockClient.post.mockResolvedValue({ transactions: [] })
+
+    const cmd = listingsCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(
+      [
+        "cross-chain-fulfill",
+        "--hashes",
+        "0xabc",
+        "--listing-chain",
+        "ethereum",
+        "--protocol-address",
+        "0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC",
+        "--fulfiller",
+        "0x1234567890abcdef1234567890abcdef12345678",
+        "--payment-chain",
+        "base",
+        "--payment-token",
+        "0x0000000000000000000000000000000000000000",
+      ],
+      { from: "user" },
+    )
+
+    expect(ctx.mockClient.post).toHaveBeenCalledWith(
+      "/api/v2/listings/cross_chain_fulfillment_data",
+      {
+        listings: [
+          {
+            hash: "0xabc",
+            chain: "ethereum",
+            protocol_address: "0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC",
+          },
+        ],
+        fulfiller: {
+          address: "0x1234567890abcdef1234567890abcdef12345678",
+        },
+        payment: {
+          chain: "base",
+          token_address: "0x0000000000000000000000000000000000000000",
+        },
+      },
+    )
+  })
+
+  it("cross-chain-fulfill supports multiple hashes", async () => {
+    ctx.mockClient.post.mockResolvedValue({ transactions: [] })
+
+    const cmd = listingsCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(
+      [
+        "cross-chain-fulfill",
+        "--hashes",
+        "0xabc,0xdef",
+        "--listing-chain",
+        "ethereum",
+        "--protocol-address",
+        "0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC",
+        "--fulfiller",
+        "0x1234567890abcdef1234567890abcdef12345678",
+        "--payment-chain",
+        "base",
+        "--payment-token",
+        "0x0000000000000000000000000000000000000000",
+      ],
+      { from: "user" },
+    )
+
+    expect(ctx.mockClient.post).toHaveBeenCalledWith(
+      "/api/v2/listings/cross_chain_fulfillment_data",
+      expect.objectContaining({
+        listings: [
+          expect.objectContaining({ hash: "0xabc" }),
+          expect.objectContaining({ hash: "0xdef" }),
+        ],
+      }),
+    )
+  })
+
+  it("cross-chain-fulfill passes optional recipient", async () => {
+    ctx.mockClient.post.mockResolvedValue({ transactions: [] })
+
+    const cmd = listingsCommand(ctx.getClient, ctx.getFormat)
+    await cmd.parseAsync(
+      [
+        "cross-chain-fulfill",
+        "--hashes",
+        "0xabc",
+        "--listing-chain",
+        "ethereum",
+        "--protocol-address",
+        "0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC",
+        "--fulfiller",
+        "0x1234567890abcdef1234567890abcdef12345678",
+        "--payment-chain",
+        "base",
+        "--payment-token",
+        "0x0000000000000000000000000000000000000000",
+        "--recipient",
+        "0xrecipient",
+      ],
+      { from: "user" },
+    )
+
+    expect(ctx.mockClient.post).toHaveBeenCalledWith(
+      "/api/v2/listings/cross_chain_fulfillment_data",
+      expect.objectContaining({
+        recipient: "0xrecipient",
+      }),
+    )
+  })
 })
diff --git a/test/sdk.test.ts b/test/sdk.test.ts
@@ -597,4 +597,68 @@ describe("OpenSeaCLI", () => {
       expect(result.message).toContain("Network error: fetch failed")
     })
   })
+
+  describe("listings.crossChainFulfillmentData", () => {
+    it("posts to correct endpoint with snake_case body", async () => {
+      mockPost.mockResolvedValue({
+        transactions: [
+          { chain: "ethereum", to: "0xabc", data: "0x123", value: "0" },
+        ],
+      })
+      const result = await sdk.listings.crossChainFulfillmentData({
+        listings: [
+          {
+            hash: "0xorderhash",
+            chain: "ethereum",
+            protocolAddress: "0xseaport",
+          },
+        ],
+        fulfillerAddress: "0xbuyer",
+        paymentChain: "base",
+        paymentTokenAddress: "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")
+    })
+
+    it("includes recipient when provided", async () => {
+      mockPost.mockResolvedValue({ transactions: [] })
+      await sdk.listings.crossChainFulfillmentData({
+        listings: [
+          {
+            hash: "0xhash",
+            chain: "ethereum",
+            protocolAddress: "0xseaport",
+          },
+        ],
+        fulfillerAddress: "0xbuyer",
+        paymentChain: "base",
+        paymentTokenAddress: "0x0000000000000000000000000000000000000000",
+        recipient: "0xrecipient",
+      })
+      expect(mockPost).toHaveBeenCalledWith(
+        "/api/v2/listings/cross_chain_fulfillment_data",
+        expect.objectContaining({
+          recipient: "0xrecipient",
+        }),
+      )
+    })
+  })
 })

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@opensea/cli",`
`3`		`- "version": "1.3.0",`
	`3`	`+ "version": "1.4.0",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",`
`6`	`6`	`"main": "dist/index.js",`