What is @opensea/stream-js?

@opensea/stream-js is a TypeScript SDK for the OpenSea Stream API, a WebSocket-based service that delivers marketplace events in real time, without polling. Subscribe globally or per-collection to receive:

Item listed, sold, transferred, metadata updated, cancelled
Item received bid / offer
Collection offers and trait offers
Order invalidation and revalidation

Getting Started

Install the TypeScript SDK:

npm install @opensea/stream-js

NodeJS only — also install WebSocket and storage dependencies:

npm install ws node-localstorage

Browser

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

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

Node.js

import { OpenSeaStreamClient } from '@opensea/stream-js';
import { WebSocket } from 'ws';
import { LocalStorage } from 'node-localstorage';

const client = new OpenSeaStreamClient({
  token: 'YOUR_OPENSEA_API_KEY',
  connectOptions: {
    transport: WebSocket,
    sessionStorage: LocalStorage
  }
});

Subscribe to Events

// Listen to listings for a specific collection
client.onItemListed('collection-slug', (event) => {
  // handle event
});

// Listen to all bids across all collections
client.onItemReceivedBid('*', (event) => {
  // handle event
});

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

Using Without the SDK

Any language with a WebSocket client can connect directly:

Endpoint: wss://stream.openseabeta.com/socket/websocket?token=<API_KEY>
Heartbeat: Send {"topic": "phoenix", "event": "heartbeat", "payload": {}, "ref": 0} every 30 seconds
Subscribe: Send {"topic": "collection:<slug>", "event": "phx_join", "payload": {}, "ref": 0}
Unsubscribe: Send the same message with "event": "phx_leave"

Documentation

Full documentation including event types, example payloads, configuration options, and API details is maintained in the GitHub repository:

github.com/ProjectOpenSea/stream-js

FAQs

Do I need an API key? Yes. Get one at Settings -> Developer.

Do streamed events count toward rate limits? No.

Can events arrive out of order? Yes. Use the event_timestamp field to determine ordering.

Can events be missed? The Stream API is best-effort delivery. Messages lost during connection errors are not re-sent.