Release v1.6.0

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,59 @@
 # @opensea/cli
 
+## 1.6.0
+
+### Minor Changes
+
+- 94dbf08: Sync downstream packages to the API surface introduced in `@opensea/api-types` 0.3.0 (os2-core#40171 + #40190): drop methods backed by removed endpoints, fix POST shapes, and surface the four new endpoints (`/listings/sweep`, `/offers/collection/{slug}/nfts/{identifier}`, `/swap/execute`, `/transactions/receipt`).
+
+  ### `@opensea/sdk` — breaking
+
+  **Removed methods** (the underlying GET endpoints were deleted; they would return 404 against the new API):
+
+  - `OpenSeaAPI.getOrder` / `OrdersAPI.getOrder` — was already `@deprecated`. Use `getBestOffer` / `getBestListing` for "best" or `getAllOffers` / `getAllListings` for collection-wide results.
+  - `OpenSeaAPI.getOrders` / `OrdersAPI.getOrders` — was already `@deprecated`. Use `getAllOffers` / `getAllListings`.
+  - `OpenSeaAPI.postOrder` / `OrdersAPI.postOrder` — was already `@deprecated`. Use `postListing` / `postOffer`.
+  - `OpenSeaAPI.getNFTOffers` / `OffersAPI.getNFTOffers` — replaced by `getOffersByNFT(slug, tokenId)` (new endpoint takes a collection slug, not contract address).
+  - `OpenSeaAPI.getNFTListings` / `ListingsAPI.getNFTListings` — no per-NFT all-listings endpoint exists. Use `getBestListing(slug, tokenId)` for the best, or `getAllListings(slug)` and filter client-side.
+  - Helpers `getOrdersAPIPath`, `serializeOrdersQueryOptions`, `deserializeOrder` — orphaned with the methods above.
+  - Types `OrderAPIOptions`, `OrdersQueryOptions`, `OrdersQueryResponse`, `OrdersPostQueryResponse`, `ListingPostQueryResponse`, `OfferPostQueryResponse`, `SerializedOrderV2`, `GetOrdersResponse` — unused after the deletions.
+  - Stats fields `IntervalStat.{volume_diff, volume_change, sales_diff, average_price}` and `Stats.{market_cap, average_price}` — server stopped returning them (always `0` previously).
+
+  **Behavior changes:**
+
+  - `OrdersAPI.postListing` and `OrdersAPI.postOffer` now read the bare `Listing` / `Offer` response (the upstream API dropped the legacy `order` wrapper field).
+  - `OpenSeaSDK.createOffer` returns `Promise<Offer>` (was `Promise<OrderV2>`).
+  - `OpenSeaSDK.createListing` returns `Promise<Listing>` (was `Promise<OrderV2>`).
+  - `OpenSeaSDK.createBulkListings` returns `Promise<BulkOrderResult<Listing>>`; `createBulkOffers` returns `Promise<BulkOrderResult<Offer>>`. `BulkOrderResult` is now generic in the success type.
+
+  **New methods:**
+
+  - `OpenSeaAPI.getOffersByNFT(slug, identifier, limit?, next?)` — all offers for one NFT.
+  - `OpenSeaAPI.sweepCollection(request)` — bulk-buy items from a collection, any payment token (incl. cross-chain).
+  - `OpenSeaAPI.executeSwap(request)` — multi-asset swap; companion to `getSwapQuote`.
+  - `OpenSeaAPI.getTransactionReceipt(request)` — fetch transaction status (sweep, swap, fulfillment).
+  - New `TransactionsAPI` sub-client.
+
+  ### `@opensea/cli` — additive (with one type re-export removed)
+
+  - `OrdersResponse`, `SimpleAccount` re-exports removed from `src/types/api.ts` (schemas no longer exist).
+  - `offers all` and `listings all` now accept `--maker <address>` to filter by order maker.
+  - New commands:
+    - `listings sweep` — bulk-buy items from a collection with any payment token.
+    - `offers by-nft <collection> <token-id>` — all offers for a specific NFT.
+    - `transactions receipt --request <file>` — fetch transaction receipt/status (request body via JSON file).
+  - New SDK helpers: `OpenSeaCLI.transactions.receipt`, `SwapsAPI.executeMulti` (POST `/swap/execute`).
+
+  ### `@opensea/skill` — docs refresh
+
+  - `opensea-api/references/rest-api.md` — endpoint tables refreshed: removed deleted GET rows, added `?maker=` annotations, added `listings/sweep`, per-NFT offers, `swap/execute`, and `transactions/receipt` rows.
+  - `opensea-marketplace/references/marketplace-api.md` — replaced "Get listings/offers for specific NFT" sections (which curled the removed endpoints) with the slug-based replacements.
+
+### Patch Changes
+
+- Updated dependencies [7a51fd0]
+  - @opensea/api-types@0.3.0
+
 ## 1.5.0
 
 ### Minor Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "OpenSea CLI - Query the OpenSea API from the command line or programmatically",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@opensea/api-types": "^0.2.3",
+    "@opensea/api-types": "^0.3.0",
     "@opensea/wallet-adapters": "^0.3.0",
     "commander": "^14.0.3",
     "zod": "^4.3.6"

src/cli.ts

@@ -15,6 +15,7 @@ import {
   swapsCommand,
   tokenGroupsCommand,
   tokensCommand,
+  transactionsCommand,
   walletCommand,
 } from "./commands/index.js"
 import { type OutputFormat, setOutputOptions } from "./output.js"
@@ -132,6 +133,7 @@ program.addCommand(
 )
 program.addCommand(searchCommand(getClient, getFormat))
 program.addCommand(swapsCommand(getClient, getFormat))
+program.addCommand(transactionsCommand(getClient, getFormat))
 program.addCommand(healthCommand(getClient, getFormat))
 program.addCommand(walletCommand(getFormat))
 

src/commands/index.ts

@@ -12,4 +12,5 @@ export { searchCommand } from "./search.js"
 export { swapsCommand } from "./swaps.js"
 export { tokenGroupsCommand } from "./token-groups.js"
 export { tokensCommand } from "./tokens.js"
+export { transactionsCommand } from "./transactions.js"
 export { walletCommand } from "./wallet.js"

src/commands/listings.ts

@@ -17,20 +17,75 @@ export function listingsCommand(
     .argument("<collection>", "Collection slug")
     .option("--limit <limit>", "Number of results", "20")
     .option("--next <cursor>", "Pagination cursor")
+    .option("--maker <address>", "Filter by order maker address")
     .action(
-      async (collection: string, options: { limit: string; next?: string }) => {
+      async (
+        collection: string,
+        options: { limit: string; next?: string; maker?: string },
+      ) => {
         const client = getClient()
         const result = await client.get<{
           listings: Listing[]
           next?: string
         }>(`/api/v2/listings/collection/${collection}/all`, {
           limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
+          maker: options.maker,
         })
         console.log(formatOutput(result, getFormat()))
       },
     )
 
+  cmd
+    .command("sweep")
+    .description("Bulk-buy items from a collection (any payment token)")
+    .requiredOption("--collection <slug>", "Collection slug to sweep")
+    .requiredOption("--max-items <n>", "Maximum number of items to buy", v =>
+      parseIntOption(v, "--max-items"),
+    )
+    .requiredOption(
+      "--max-price-per-item <wei>",
+      "Maximum price per item in wei of the payment token",
+    )
+    .requiredOption("--buyer <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: {
+        collection: string
+        maxItems: number
+        maxPricePerItem: string
+        buyer: string
+        paymentChain: string
+        paymentToken: string
+        recipient?: string
+      }) => {
+        const client = getClient()
+        const body: Record<string, unknown> = {
+          collection_slug: options.collection,
+          max_items: options.maxItems,
+          max_price_per_item: options.maxPricePerItem,
+          buyer: options.buyer,
+          payment: {
+            chain: options.paymentChain,
+            token_address: options.paymentToken,
+          },
+        }
+        if (options.recipient) {
+          body.recipient = options.recipient
+        }
+        const result = await client.post("/api/v2/listings/sweep", body)
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
   addTraitsOption(
     cmd
       .command("best")

src/commands/offers.ts

@@ -17,15 +17,45 @@ export function offersCommand(
     .argument("<collection>", "Collection slug")
     .option("--limit <limit>", "Number of results", "20")
     .option("--next <cursor>", "Pagination cursor")
+    .option("--maker <address>", "Filter by order maker address")
     .action(
-      async (collection: string, options: { limit: string; next?: string }) => {
+      async (
+        collection: string,
+        options: { limit: string; next?: string; maker?: string },
+      ) => {
         const client = getClient()
         const result = await client.get<{
           offers: Offer[]
           next?: string
         }>(`/api/v2/offers/collection/${collection}/all`, {
           limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
+          maker: options.maker,
+        })
+        console.log(formatOutput(result, getFormat()))
+      },
+    )
+
+  cmd
+    .command("by-nft")
+    .description("Get all offers for a specific NFT")
+    .argument("<collection>", "Collection slug")
+    .argument("<token-id>", "Token ID")
+    .option("--limit <limit>", "Number of results", "20")
+    .option("--next <cursor>", "Pagination cursor")
+    .action(
+      async (
+        collection: string,
+        tokenId: string,
+        options: { limit: string; next?: string },
+      ) => {
+        const client = getClient()
+        const result = await client.get<{
+          offers: Offer[]
+          next?: string
+        }>(`/api/v2/offers/collection/${collection}/nfts/${tokenId}`, {
+          limit: parseIntOption(options.limit, "--limit"),
+          next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
       },

src/commands/transactions.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs"
+import { Command } from "commander"
+import type { OpenSeaClient } from "../client.js"
+import type { OutputFormat } from "../output.js"
+import { formatOutput } from "../output.js"
+import type {
+  TransactionReceiptRequest,
+  TransactionReceiptResponse,
+} from "../types/index.js"
+
+export function transactionsCommand(
+  getClient: () => OpenSeaClient,
+  getFormat: () => OutputFormat,
+): Command {
+  const cmd = new Command("transactions").description(
+    "Query transaction status and receipts",
+  )
+
+  cmd
+    .command("receipt")
+    .description(
+      "Fetch transaction status. Works for listing fulfillments, " +
+        "cross-chain buys, sweeps, offer fulfillments, and token swaps.",
+    )
+    .requiredOption(
+      "--request <file>",
+      "Path to a JSON file containing the request body " +
+        "(at minimum a `swap_quote` object). " +
+        "Optional fields: `transaction_identifiers`, `relay_request_id`, " +
+        "`request_id`.",
+    )
+    .action(async (options: { request: string }) => {
+      const client = getClient()
+      let body: TransactionReceiptRequest
+      try {
+        body = JSON.parse(
+          readFileSync(options.request, "utf8"),
+        ) as TransactionReceiptRequest
+      } catch (err) {
+        const cause = err instanceof Error ? err.message : String(err)
+        throw new Error(
+          `--request: could not read or parse '${options.request}': ${cause}`,
+        )
+      }
+      const result = await client.post<TransactionReceiptResponse>(
+        "/api/v2/transactions/receipt",
+        body,
+      )
+      console.log(formatOutput(result, getFormat()))
+    })
+
+  return cmd
+}