Release v10.4.0

Author: ryanio

CHANGELOG.md

@@ -1,5 +1,59 @@
 # @opensea/sdk
 
+## 10.4.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
+
 ## 10.3.1
 
 ### Patch Changes

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensea/sdk",
-  "version": "10.3.1",
+  "version": "10.4.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",
@@ -45,7 +45,7 @@
   "types": "lib/index.d.ts",
   "dependencies": {
     "@noble/hashes": "^2.0.1",
-    "@opensea/api-types": "^0.2.3",
+    "@opensea/api-types": "^0.3.0",
     "@opensea/seaport-js": "^4.1.1",
     "ethers": "^6.16.0"
   },

src/api/api.ts

@@ -1,11 +1,5 @@
 import { API_BASE_MAINNET } from "../constants"
-import type {
-  FulfillmentDataResponse,
-  OrderAPIOptions,
-  OrdersQueryOptions,
-  OrderV2,
-  ProtocolData,
-} from "../orders/types"
+import type { FulfillmentDataResponse, ProtocolData } from "../orders/types"
 import {
   Chain,
   type OpenSeaAccount,
@@ -30,6 +24,7 @@ import { OffersAPI } from "./offers"
 import { OrdersAPI } from "./orders"
 import { SearchAPI } from "./search"
 import { TokensAPI } from "./tokens"
+import { TransactionsAPI } from "./transactions"
 import {
   type BuildOfferResponse,
   type CancelOrderResponse,
@@ -58,7 +53,6 @@ import {
   type GetNFTResponse,
   type GetOffersResponse,
   type GetOrderByHashResponse,
-  type GetOrdersResponse,
   type GetSwapQuoteArgs,
   type GetSwapQuoteResponse,
   type GetTokenGroupResponse,
@@ -78,7 +72,13 @@ import {
   type ResolveAccountResponse,
   type SearchArgs,
   type SearchResponse,
+  type SwapExecuteRequest,
+  type SwapExecuteResponse,
+  type SweepCollectionRequest,
+  type SweepCollectionResponse,
   type TraitFilter,
+  type TransactionReceiptRequest,
+  type TransactionReceiptResponse,
   type ValidateMetadataResponse,
 } from "./types"
 
@@ -115,6 +115,7 @@ export class OpenSeaAPI {
   private tokensAPI: TokensAPI
   private chainsAPI: ChainsAPI
   private dropsAPI: DropsAPI
+  private transactionsAPI: TransactionsAPI
 
   /**
    * Create an instance of the OpenSeaAPI
@@ -143,7 +144,7 @@ export class OpenSeaAPI {
     // Initialize specialized API clients
     this.ordersAPI = new OrdersAPI(fetcher, this.chain)
     this.offersAPI = new OffersAPI(fetcher, this.chain)
-    this.listingsAPI = new ListingsAPI(fetcher, this.chain)
+    this.listingsAPI = new ListingsAPI(fetcher)
     this.collectionsAPI = new CollectionsAPI(fetcher)
     this.nftsAPI = new NFTsAPI(fetcher, this.chain)
     this.accountsAPI = new AccountsAPI(fetcher, this.chain)
@@ -152,20 +153,7 @@ export class OpenSeaAPI {
     this.tokensAPI = new TokensAPI(fetcher)
     this.chainsAPI = new ChainsAPI(fetcher)
     this.dropsAPI = new DropsAPI(fetcher)
-  }
-
-  /**
-   * Gets an order from API based on query options.
-   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
-   * @param options Query options for fetching an order
-   * @returns The first {@link OrderV2} returned by the API
-   *
-   * @throws An error if there are no matching orders.
-   */
-  public async getOrder(
-    options: Omit<OrdersQueryOptions, "limit">,
-  ): Promise<OrderV2> {
-    return this.ordersAPI.getOrder(options)
+    this.transactionsAPI = new TransactionsAPI(fetcher)
   }
 
   /**
@@ -184,18 +172,6 @@ export class OpenSeaAPI {
     return this.ordersAPI.getOrderByHash(orderHash, protocolAddress, chain)
   }
 
-  /**
-   * Gets a list of orders from API based on query options.
-   * @deprecated Use collection-based endpoints instead: getAllOffers, getAllListings, getBestOffer, getBestListing.
-   * @param options Query options for fetching orders
-   * @returns The {@link GetOrdersResponse} returned by the API.
-   */
-  public async getOrders(
-    options: Omit<OrdersQueryOptions, "limit">,
-  ): Promise<GetOrdersResponse> {
-    return this.ordersAPI.getOrders({ ...options, pageSize: this.pageSize })
-  }
-
   /**
    * Gets all offers for a given collection.
    * @param collectionSlug The slug of the collection.
@@ -371,20 +347,6 @@ export class OpenSeaAPI {
     )
   }
 
-  /**
-   * Post an order to OpenSea.
-   * @deprecated Use postListing or postOffer instead.
-   * @param order The order to post
-   * @param apiOptions API options for the order
-   * @returns The {@link OrderV2} posted to the API.
-   */
-  public async postOrder(
-    order: ProtocolData,
-    apiOptions: OrderAPIOptions,
-  ): Promise<OrderV2> {
-    return this.ordersAPI.postOrder(order, apiOptions)
-  }
-
   /**
    * Post a listing to OpenSea. Returns the new v2 Listing response format.
    * @param order The order to post
@@ -864,55 +826,61 @@ export class OpenSeaAPI {
 
   /**
    * Gets all active offers for a specific NFT (not just the best offer).
-   * @param assetContractAddress The NFT contract address.
-   * @param tokenId The token identifier.
-   * @param limit The number of offers to return. Must be between 1 and 100.
-   * @param next The cursor for the next page of results. This is returned from a previous request.
-   * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor.
+   * @param collectionSlug The collection slug.
+   * @param identifier The NFT token id.
+   * @param limit The number of offers to return. Must be between 1 and 200.
+   * @param next The cursor for the next page of results.
    * @returns The {@link GetOffersResponse} returned by the API.
    */
-  public async getNFTOffers(
-    assetContractAddress: string,
-    tokenId: string,
+  public async getOffersByNFT(
+    collectionSlug: string,
+    identifier: string | number,
     limit?: number,
     next?: string,
-    chain: Chain = this.chain,
   ): Promise<GetOffersResponse> {
-    return this.offersAPI.getNFTOffers(
-      assetContractAddress,
-      tokenId,
+    return this.offersAPI.getOffersByNFT(
+      collectionSlug,
+      identifier,
       limit,
       next,
-      chain,
     )
   }
 
   /**
-   * Gets all active listings for a specific NFT (not just the best listing).
-   * @param assetContractAddress The NFT contract address.
-   * @param tokenId The token identifier.
-   * @param limit The number of listings to return. Must be between 1 and 100.
-   * @param next The cursor for the next page of results. This is returned from a previous request.
-   * @param chain The chain where the NFT is located. Defaults to the chain set in the constructor.
-   * @param includePrivateListings Whether to include private listings (default: false)
-   * @returns The {@link GetListingsResponse} returned by the API.
+   * Bulk-buy items from a collection using any payment token, including
+   * cross-chain. Returns an ordered list of transactions to execute.
+   * @param request The sweep request containing buyer, collection, payment, and item caps.
+   * @returns The {@link SweepCollectionResponse} returned by the API.
    */
-  public async getNFTListings(
-    assetContractAddress: string,
-    tokenId: string,
-    limit?: number,
-    next?: string,
-    chain: Chain = this.chain,
-    includePrivateListings?: boolean,
-  ): Promise<GetListingsResponse> {
-    return this.listingsAPI.getNFTListings(
-      assetContractAddress,
-      tokenId,
-      limit,
-      next,
-      chain,
-      includePrivateListings,
-    )
+  public async sweepCollection(
+    request: SweepCollectionRequest,
+  ): Promise<SweepCollectionResponse> {
+    return this.listingsAPI.sweepCollection(request)
+  }
+
+  /**
+   * Get executable transactions for a token swap. Companion to
+   * {@link OpenSeaAPI.getSwapQuote} — quote first, then execute.
+   * @param request The swap execution request.
+   * @returns The {@link SwapExecuteResponse} with transactions and a quote.
+   */
+  public async executeSwap(
+    request: SwapExecuteRequest,
+  ): Promise<SwapExecuteResponse> {
+    return this.tokensAPI.executeSwap(request)
+  }
+
+  /**
+   * Get the receipt/status for a submitted transaction. Works for all transaction
+   * types: listing fulfillments, cross-chain buys, sweeps, offer fulfillments,
+   * and token swaps. Poll this endpoint to check completion status.
+   * @param request The transaction receipt request.
+   * @returns The {@link TransactionReceiptResponse} returned by the API.
+   */
+  public async getTransactionReceipt(
+    request: TransactionReceiptRequest,
+  ): Promise<TransactionReceiptResponse> {
+    return this.transactionsAPI.getTransactionReceipt(request)
   }
 
   /**

src/api/apiPaths.ts

@@ -1,16 +1,15 @@
 import type { OrderProtocol } from "../orders/types"
-import { type Chain, OrderSide } from "../types"
+import type { Chain } from "../types"
 
 /** Base path prefix for all OpenSea API v2 endpoints. */
 export const API_V2_PREFIX = "/api/v2"
 
-export const getOrdersAPIPath = (
-  chain: Chain,
-  protocol: OrderProtocol,
-  side: OrderSide,
-) => {
-  const sidePath = side === OrderSide.LISTING ? "listings" : "offers"
-  return `${API_V2_PREFIX}/orders/${chain}/${protocol}/${sidePath}`
+export const getPostListingPath = (chain: Chain, protocol: OrderProtocol) => {
+  return `${API_V2_PREFIX}/orders/${chain}/${protocol}/listings`
+}
+
+export const getPostOfferPath = (chain: Chain, protocol: OrderProtocol) => {
+  return `${API_V2_PREFIX}/orders/${chain}/${protocol}/offers`
 }
 
 export const getAllOffersAPIPath = (collectionSlug: string) => {
@@ -119,6 +118,25 @@ export const getTraitOffersPath = (collectionSlug: string) => {
   return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/traits`
 }
 
+export const getOffersByNFTPath = (
+  collectionSlug: string,
+  identifier: string | number,
+) => {
+  return `${API_V2_PREFIX}/offers/collection/${collectionSlug}/nfts/${identifier}`
+}
+
+export const getSweepListingsPath = () => {
+  return `${API_V2_PREFIX}/listings/sweep`
+}
+
+export const getSwapExecutePath = () => {
+  return `${API_V2_PREFIX}/swap/execute`
+}
+
+export const getTransactionReceiptPath = () => {
+  return `${API_V2_PREFIX}/transactions/receipt`
+}
+
 export const getEventsAPIPath = () => {
   return `${API_V2_PREFIX}/events`
 }