Wyvern 2.3 will soon be the new marketplace contract for OpenSea, and is located here.

We will be making some platform changes to go along with the new contract. These changes have implications for developers building on top of the OpenSea.js SDK and our API. The primary takeaways:

• orders made on OpenSea now require v2 of the SDK to fulfill,
• new orders will require v2 on February 18th and old orders will stop functioning on February 25th,
• we’re introducing cursor-based pagination for events on the API, and
• a few API parameters will be changing.

Read below to learn more about the upgrade and how you might be affected.

About the Upgrade

On February 1, we deployed and proposed the upgrade of OpenSea’s marketplace contract, called Wyvern. OpenSea has leveraged Wyvern to conduct sales of NFT since March of 2018; since then, it has grown to the most-used smart contract on Ethereum:

Wyvern was the first smart contract we found with an off-chain order architecture for NFTs. It offered a flexible view for the future of NFT liquidity, including gas-free listings and schema-agnostic transfers, so we used it as our contract. But in the past few years, it started to show some limitations, including the inability to cancel offers in bulk.

Wyvern 2.3 fixes some of these limitations, introducing:

• EIP-1271: Smart contract wallets can now sign orders and submit them to OpenSea without paying gas. This also enables a host of new apps to work with OpenSea, including Argent, Skyweaver’s Sequence wallet, and many others.
• Bulk cancellations: You can listen to the new NonceIncremented event yourself to see when a user bulk-cancels orders

Timeline

On February 4, we initiated a mandatory two-week on-chain switchover period to transition to the new contract.

On February 18th, the old contract for Wyvern 2.2 will begin a seven-day shutdown process. Older versions of our SDK will no longer be able to post orders to OpenSea (more on that below).

On February 25th, orders made on the old contract will no longer be fulfillable on-chain, and we will no longer make them available to consumers of our API.

SDK Changes

Today we launched a new version (2.0) of our SDK to take advantage of Wyvern 2.3. While function signatures have not changed, there are a few breaking changes that require an update:

1. Prior versions of the SDK will continue to function, but orders created using the new SDK (and on opensea.io starting yesterday, Feb 9) will not be fulfillable using the old SDK. An upgrade will be required to match them.
2. On February 18th, versions of the SDK older than 2.0 will no longer be able to create new orders. OpenSea will not accept them. This new version of the SDK will start automatically signing and submitting orders for Wyvern 2.3.
3. The Ethereum provider passed into the SDK must either support <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">eth_signTypedData</span> or <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">eth_signTypedData_v4</span>. It will try <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">v4</span> first and then fall back to the former.

Read more about our SDK here: https://github.com/ProjectOpenSea/opensea-js

API Changes

We’re making three changes to our API: introducing cursor pagination, removing last-sale sorting parameters, and creating a scrollable endpoint to get orders on a single item.

1. Cursors

We will be rolling out an update to one of our API endpoints, the events API, to introduce cursor-based pagination.

We are taking a slow and steady approach of enabling backwards compatibility for a few weeks to transition over and give developers the opportunity to slowly switch.

This means that existing requests won’t suddenly fail; they’ll just stop behaving the way they normally do. We will fully deprecate these fields and you should expect them to no longer work by March 1, 2022.

What changes were made? The <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/events</span> endpoint will now by default return next and previous cursors, which will be ready-to-use links to the next page in the resulting dataset.

This will lead to significantly faster API response times for you and less intensive APIs for us (and therefore less platform instability!). If you choose to, you will be able to continue using <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">limit</span>, <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">offset</span>, and occurred_after for a period of time in order to not break any existing API calls you might be making now. The <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">occurred_before</span> field will remain to allow you to start your search at a particular point in time.

Eventually, we will deprecate these fields completely. These four fields, which are being used by API users to get the next page of results, will now only be retained for backwards compatibility. The API response for this endpoint will now have two new fields:

{
	"asset_events": [...], <- existing field with data
	"next_page:": "<https://api.opensea.io/api/v1/events?cursor=cj0xJnA9MjAyMi0wMi0wMiswMiUzQTQ1JTNBMTIuNjQ3MDM2>", <- new field
	"previous_page": "<https://api.opensea.io/api/v1/events?cursor=cD0yMDIyLTAyLTAyKzAxJTNBNDglM0EzNC4xMzE4Nzk%3D>", <- new field
}

‍

When users want to get to the next page, they will need to use the next page as the request endpoint.

Why? This update not only simplifies things for users wanting to get to the next page but also leads to much faster response times. Additionally, you will also not be restricted to a smaller result dataset of 10,000 with this change. This is a design limitation of how offset-based queries work, which is not the case with cursor-based pagination.

We are focused on improving operational excellence this will improve the experience for our users, leading to improved performance and reliability.

We plan on eventually rolling cursor pagination to all our list endpoints. You can read more about the advantages of cursor pagination here.

2. Removing Last-Sale Sorting

What: We are deprecating and eventually removing <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_date</span>, <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_count</span>, and <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_price</span> as sort options from <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/assets</span>

👉🏽 https://docs.opensea.io/reference/getting-assets

Why: A very small percent of requests for the /assets/ endpoint use these as sorting options. However, they lead to some of the slowest and least efficient queries on our platform. This leads to a poorly optimized OpenSea.

In the near future, we will be rolling our cursor pagination to the <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/assets</span> endpoint, which means these ordering options will not work.

In the long run, this will lead to an enhanced developer experience with improved API requests, and a more reliable platform. We will evaluate re-introducing the ability to fetch assets ordered by these options in the future.

Developer Action: If you are currently relying on <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_date</span>, <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_count</span>, and <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">sale_price</span> as sort options from <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/assets</span> for your API requests you will need to update your logic to stop relying on them. For now, you may continue using these ordering options, but eventually requests with these ordering inputs will fail.

3. New Orders Endpoint for Items

What: We are rolling out a new endpoint for fetching the open orders on an asset <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id/orders</span>, and eventually deprecating and removing orders returned in the <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id</span> and the <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/assets</span> endpoint

Edit: Instead of a single endpoint for orders, we’ve rolled out two separate endpoints to fetch listings (<span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id/listings</span) and offers (<span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id/offers</span>).

Why: Returning detailed asset information including a full list of orders has led to underperforming APIs on our platform.

This resulted in reduced platform performance as a whole, and we are working to improve OpenSea’s reliability. You will still be able to access the same data from an optimized dedicated endpoint.

The orders returned for each asset were also limited to 50 orders per asset. There is currently no way to fetch additional pages of these orders, leading to a less than ideal experience for developers. The new orders endpoint will have cursor pagination enabled, meaning that you will be able to see greater than 50 open orders for an asset.

Developer Action: In the coming weeks, we will slowly be rolling out the new <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id/orders</span> endpoint. If you rely on the <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id</span> endpoint for finding all the orders for an asset, we recommend you prepare to move your logic to call the new endpoint.

We will continue returning orders on the original <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id</span> endpoint until March 1st.  After this date, we will only return orders on that endpoint if you also pass in <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">include_orders=true</span> as a query parameter to the original endpoint. After March 21st, we will stop returning orders altogether on the <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id</span> endpoint. At that point, the only way to fetch those orders will be with the new <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">/asset/:contract_address/:token_id/orders</span> endpoint.

Reminder About API Keys

To request an API Key, please visit https://docs.opensea.io/reference/request-an-api-key

We’ve listened to our community and understand that speed matters, and we are committed to a five-day processing of all API Key requests. For API updates, follow us on Twitter @APIOpenSea and join our Developer Discord Channel.

Coming Soon

In addition to the new features from Wyvern 2.3, the new SDK lays the tracks for allowing users and developers to create orders with advanced criteria. Stay tuned for some exciting updates on the types of orders you can create!

Note: a consequence of this change is that orders created on Wyvern 2.2 and 2.3 have their <span id="code" class="pink-text" style="color: #e83e8c;" fs-test-element="code">target</span> set to a special new validator contract and will proxy matches through it.

Check out our docs for some interesting tips and tutorials that leverage the SDK and our free API for NFTs: https://docs.opensea.io/. We added a new tutorial for creating your own NFT smart contract, usable on any marketplace.

We’ll be around in the #developers channel in our Discord to help with the migration.