Overview

The OpenSea Stream API is a websocket-based service that enables developers to receive events as they occur, ensuring that your service has the most up-to-date details without the need to continuously poll for updates. With the Stream API, your service can subscribe to receive a range of different types of events, either globally or for specific collections that you’re interested in.

The Stream API currently supports the following set of events:

  • Item listed - an item listed for sale on the OpenSea marketplace
  • Item sold - sale of an item on the OpenSea marketplace
  • Item transferred - transfer of an item between wallets
  • Item metadata update - update detected on the metadata provided in tokenURI for an item
  • Item cancelled - cancellation of an order on the OpenSea marketplace
  • Item received offer - offer received on an item in the OpenSea marketplace
  • Item received bid - bid received on an item in the OpenSea marketplace

Note: Stream API is currently in beta and can be subject to sporadic instability and changes as we work to improve the service in collaboration with the ecosystem.

What can you build with Stream API?

The real-time, push nature of the Stream API enables a variety of use cases that rely on dynamic, up-to-date information. Here are some examples of services that can be built using the Stream API:

  • Push Notifications - Developers can create a push notifications service in their product that provides their users with timely updates as events happen on NFTs and in the OpenSea marketplace.
  • Activity Feed - Developers can build an activity feed into their product that provides their users with a timeline of events as they happen on NFTs and in the OpenSea marketplace.
  • Real-Time Data Monitoring - Developers can create real-time dashboards that enable people to visualize and track key trends, metrics, etc as part of an analytics service.
  • Ownership Changes - Developers can automatically reflect any changes in ownership of an NFT in a person’s connected wallet.
  • Metadata Updates - Developers can ensure that NFT metadata is always up-to-date, immediately reflecting any changes that take place.

Getting Started

We’ve created a JavaScript SDK to help developers manage connections and individual subscriptions to the Stream API and its various events. To get started, we recommend that you install our Stream SDK and following the setup instructions in its readme.

Client Setup

Our SDK includes a client that manages authentication, connections and event subscriptions on the Stream API. To create a new client in your project, you can create it as follows:

import { OpenSeaStreamClient } from '@opensea/stream-js';

const client = new OpenSeaStreamClient({
    token: 'openseaApiKey'
});

Authentication with the Stream API uses the same API key as our other APIs. If you don’t have an API key, please request one from us.

The client also supports the following optional configuration parameters:

Parameter

Description

Values

network

The network for which events will be returned by the Stream API. Please see below for blockchain coverage.

Network.MAINNET (Default), Network.TESTNET

onError

A callback to handle errors from the client.

Specified callback handler in your projects. Defaults to console.error.

logLevel

Specifies the scope of logging on the client.

LogLevel.DEBUG, LogLevel.INFO (Default), LogLevel.WARN, LogLevel.ERROR

The Stream API is available for both Mainnet and Testnet networks:

Network

Endpoint

Supported Blockchains

Mainnet

wss://stream.openseabeta.com/socket

Ethereum, Polygon mainnet, Klaytn mainnet, Solana mainnet

Testnet

wss://testnets-stream.openseabeta.com/socket

Rinkeby, Polygon testnet (Mumbai), Klaytn testnet (Baobab)

Connecting & Subscribing to Events

The client will automatically connect to the socket as soon as you setup your first subscription to one of the event types listed below. If you’d prefer to manually connect to the socket, we provide a function to explicitly establish the connection:

client.connect();

The following event subscriptions are available on the Stream API:

Event

Client Subscription

Event Schema

Item listed

onItemListed

Item Listed Payload Schema

Item sold

onItemSold

Item Sold Payload Schema

Item transferred

onItemTransferred

Item Transferred Payload Schema

Item metadata update

onItemMetadataUpdated

Item Metadata Update Payload Schema

Item cancelled

onItemCancelled

Item Cancelled Update Schema

Item received offer

onItemReceivedOffer

Item Received Offer Schema

Item received bid

onItemReceivedBid

Item Received Bid Schema

Each subscription function includes a collectionSlug parameter which can be used to subscribe to an event from a specific collection. Here’s how to subscribe to receive all new listings of items from a specific collection:

client.onItemListed('collection-slug', (event) => {
  // handle event
});

If you’d like to subscribe to events across all collections, you can use * wildcard for the collectionSlug parameter. Here’s how to subscriber to all new offers across all collections:

client.onItemReceivedOffer('*', (event) => {
  // handle event
});

Unsubscribing from Events

Each subscription method returns a callback function that is used to unsubscribe from a set of events when invoked.

const unsubscribe = client.onItemMetadataUpdated('collection-slug', noop);

unsubscribe();

Disconnecting

To disconnect your client from the socket completely, simply call its disconnect() method.

client.disconnect();

FAQs

Do the events received from my subscriptions count towards any rate limits on my API key?

No, events are not counted towards any API rate limits.

What is the typical streaming rate that I should expect from the Stream API?

The streaming rate depends on a range of factors - from the amount of collections that you’re monitoring to the type and amount of events that you’re subscribed to. For instance, if you’re subscribed to receive bid events across all collections on OpenSea, you’ll be receiving messages at a significantly higher rate than you will for a subscription to order cancellations on a small collection.

Should I expect that some events can be received out of order?

You should be prepared to handle receipt of events out of order as we don’t guarantee delivery of events in the order that they occur. Payloads include the event_timestamp field, which represents the time at which the event occurred and is the most definitive resource in determining order. We also include a sent_at field that refers to the time at which we sent the message out through the websocket.

Is it possible for some events to be missing?

The Stream API is a best-effort delivery messaging system and messages that are not received due to connection errors will not be re-sent. So it’s possible that there can be missing messages if the socket connection is unstable.

What blockchains does the Stream API support?

The following blockchains are supported on Mainnet networks:

  • Ethereum
  • Polygon mainnet
  • Klaytn mainnet
  • Solana mainnet

The following blockchains are supported on Testnet networks:

  • Rinkeby
  • Polygon testnet (Mumbai)
  • Klaytn testnet (Baobab)