Migrating to the Seaport protocol
Chris Ackermann
0x9400
May 25th, 2022

Last week, we unpacked the early details of OpenSea’s new open-source protocol – Seaport – for the developer community. Seaport will become the foundation for OpenSea’s core products, unlocking a range of new use cases for creators, collectors, and the broader developer ecosystem. The protocol is non-custodial, non-upgradeable, and decentralized at its core — it belongs to the community first & foremost. And in that spirit, we’re inviting the community to join us in early testing via a $1M Code4rena contest.

The new Seaport protocol will open up a range of new paths for OpenSea and the developer ecosystem more broadly:

  • A composable, open-source contract on top of which developers can build their own marketplaces
  • The ability to create custom rulesets for the fulfillment of a listing or offer, using a concept called “zones”
  • Support for multiple fees and custom creator fees
  • Potential for new types of transactions: collection offers and batch fulfillment (including floor sweeping), batch listing, and more

Required changes for developers

As we migrate the OpenSea marketplace over to Seaport, there are a few implications to our APIs and SDK that will affect our existing developers.  When we initially launch the new protocol, we will operate Wyvern and Seaport in parallel for a period of one week following the launch - and this means that you’ll need to update your project in order to fetch and interact with orders from both contracts.

We’ve summarized the set of changes that are required in order for projects to be compatible with the new Seaport protocol when it launches on OpenSea in the coming weeks. If your project does not incorporate these updates, it will not be able to fetch or interact with offers or listings on OpenSea that use the Seaport contract as we deploy it to our marketplace.

Here’s an overview of what to expect, with more details about each step in the sections that follow:

Today (May 25)

API: Begin using new Seaport offers and listings endpoints on Testnets

API: Begin parsing new Seaport orders from /assets and /bundles endpoints on Testnets

Tomorrow (May 26)

SDK: Begin using new Seaport-ready functions in SDK v.4.0.0-beta on Testnets (May 26)

Seaport live on OpenSea

API: Begin using new Seaport offers and listings endpoints on Mainnet

API: Begin parsing new Seaport offers and listings from /assets and /bundles endpoints on Testnets

SDK: Begin using new Seaport-ready functions in SDK v.4.0.0 on Mainnet

Seaport live + 7 days

API+ SDK: Offers and listings can no longer be posted to Wyvern v2.3 contract using OpenSea

Seaport live + 30 days

API + SDK: Offers and listings can no longer be fetched from Wyvern v2.3 contract using OpenSea

OpenSea API

When we begin to use the new contract, our API will enable developers to fetch and post offers and listings from both the Wyvern and Seaport contracts. Since offers and listings from the new contract will differ from those on the Wyvern contract, developers will need to update their OpenSea API integrations to account for these differences. Current API implementations will continue to function against the Wyvern contract, however changes are required to fetch and post offers and listings from the new contract.

In order to be compatible with the Seaport contract, developers will need to make the following changes to their projects:

  • Developers using the existing /wyvern endpoints will need to migrate to the new endpoint that supports offers and listings on the Seaport contract.
  • Developers using the existing /assets and /bundles endpoints will need to begin parsing orders from the Seaport contract that are returned from these endpoints.

Migrating from /wyvern endpoints to new Seaport orders endpoints

With the launch of the Seaport contract, we will be deprecating the /wyvern endpoints - at this point, POST requests will no longer be supported and GET requests will only continue to function for 30 days post-launch.

The new Seaport offers and listings endpoints enable developers to create and fetch both listings and offers on the new contract.  Developers will need to begin using these new endpoints to interact with the Seaport contract via the OpenSea API.

Starting today, we have enabled support for these new endpoints on our Testnets API (Rinkeby) so that developers can begin to prepare for the migration. More details on these new endpoints can be found in our developer documentation:

Parsing Seaport orders from /assets and /bundles endpoints

Since the format of Seaport orders differs from those on the Wyvern contract, we’re adding a new field to the /assets and /bundles endpoints through which Seaport orders will be returned separately from Wyvern offers and listings.

Developers using these endpoints will need to update any parsing logic on the responses from these endpoints in order to specifically handle orders returned from the Seaport contract.  Each item in these responses will now include the seaport_sell_orders field, which will contain an array of listings from the Seaport contract on the NFT.

This new field matches the way in which Wyvern listings are currently returned through the existing sell_orders field:

"asset": {
  ...
  "sell_orders": [],
  "seaport_sell_orders": [],
  ...
}

Once the Seaport contract integration is live on OpenSea, all new offers and listings that are created will be returned in the new seaport_sell_orders array.  As liquidity moves over to the new contract, you will see fewer and fewer listings being returned in the legacy sell_orders array, so we recommend that you cease to rely on this field after our forthcoming launch of Seaport on OpenSea.

OpenSea SDK

Similar to the OpenSea API, our JavaScript SDK has been updated to support the fetching and posting of offers and listings on the new contract. Developers should plan to adopt Version 4.0.0 of our SDK when we begin using Seaport on OpenSea and begin to use our new methods that have been updated to support orders on the new contract.

With this SDK update to support the new Seaport contract, there are notable changes that developers will need to address within their projects:

  • All Wyvern-specific models will be deprecated in the new version of the SDK.  Wyvern support will be maintained through a legacy set of functions that developers can continue to use while the contract is still enabled on OpenSea.
  • For each of these deprecated functions, we’re providing a new function that is compatible with orders on the new Seaport protocol.

With this upgrade to Version 4.0.0, the function names from Version 3.0.4 are now connected to the Seaport contract and will only begin to function when Seaport launches on OpenSea. In order to preserve support for Wyvern, developers can use the following functions to maintain support for offers and listings on the Wyvern contract:

  • isOrderFulfillableLegacyWyvern
  • cancelOrderLegacyWyvern
  • fulfillOrderLegacyWyvern
  • createBuyOrderLegacyWyvern
  • createBundleBuyOrderLegacyWyvern
  • createSellOrderLegacyWyvern
  • createBundleSellOrderLegacyWyvern
  • getCurrentPriceLegacyWyvern
  • getOrderLegacyWyvern

Starting on May 26, developers can begin testing against Version 4.0.0-beta on Rinkeby in order to prepare for the migration.

Using the new contract

While our API and SDK provide helpful abstraction layers on top of the underlying contracts that we use here at OpenSea, we also realize that a growing part of the developer ecosystem is interested in building directly off of these contracts themselves. With the release of this new contract, we’re excited to expand our developer stack by opening up this contract for the entire ecosystem to build around and participate in its ongoing development.

If you’re interested in getting started, we’ve released a set of reference documentation that you can use to learn more and begin building.

We also currently have a two-week audit contest running with code4rena with a $1 million prize pool, where we’d love participation from the community in reviewing the Seaport contracts. Please join us for the largest pool size in code4rena’s history!

Arweave TX
3YY9TcRZFQPtoq5Ud3FwtHHzWuP0QHw6b83pNa6_DJw
Ethereum Address
0x9400DCbd547b8D324dB071Bd70818e833c710A15
Content Digest
Bi_UbdXOi4AU3LtHT3WoLAN0a9YIWE2gYQmkyZ5whVM