stream-js: An SDK to receive pushed updates from OpenSea over websocket.

代码拉取完成,页面将自动刷新

开源项目 > 区块链 > NFT &&

扫描微信二维码支付

取消

支付完成

richgiteeai

Watch

不关注关注所有动态仅关注版本发行动态关注但不提醒动态

2 Star 20 Fork 0

ProjectOpenSea/stream-js

代码 Issues 0 Pull Requests 0 Wiki 统计流水线

服务

加入 Gitee

与超过 1400万开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)

免费加入

已有帐号? 立即登录

克隆/下载

HTTPS SSH SVN SVN+SSH 下载ZIP

提示

下载代码请复制以下命令到终端执行

为确保你提交的代码身份被 Gitee 正确识别,请执行以下命令完成配置

git config --global user.name userName 
git config --global user.email userEmail

初次使用 SSH 协议进行代码克隆、推送等操作时,需按下述提示完成 SSH 配置

1 生成 RSA 密钥

2 获取 RSA 公钥内容,并配置到 SSH公钥中

在 Gitee 上使用 SVN,请访问使用指南

使用 HTTPS 协议时,命令行会出现如下账号密码验证步骤。基于安全考虑,Gitee 建议配置并使用私人令牌替代登录密码进行克隆、推送等操作

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # 私人令牌

新建文件新建 Diagram 文件

新建子模块

上传文件

分支 98

标签 23

贡献代码

同步代码

创建 Pull Request

了解更多

对比差异通过 Pull Request 同步

同步更新到分支

通过 Pull Request 同步

将会在向当前分支创建一个 Pull
Request,合入后将完成同步

Ryan Ghods Release v0.4.0 57e1905

388 次提交

.github

.vscode

img

src

test

.nvmrc

AGENTS.md

CHANGELOG.md

CONTRIBUTING.md

LICENSE

README.md

biome.json

package-lock.json

package.json

renovate.json

tsconfig.base.json

tsconfig.json

tsconfig.node-cjs.json

tsconfig.node-esm.json

tsup.config.base.ts

tsup.config.ts

vitest.config.base.ts

vitest.config.ts

README

MIT

[![Version][version-badge]][version-link]
[![npm][npm-badge]][npm-link]
[![Test CI][ci-badge]][ci-link]
[![Coverage Status][coverage-badge]][coverage-link]
[![License][license-badge]][license-link]
[![Docs][docs-badge]][docs-link]

# OpenSea Stream API - TypeScript SDK

A TypeScript SDK for receiving updates from the OpenSea Stream API - pushed over websockets. We currently support the following event types on a per-collection basis:

- item listed
- item sold
- item transferred
- item metadata updates
- item cancelled
- item received offer
- item received bid

This is a best effort delivery messaging system. Messages that are not received due to connection errors will not be re-sent. Messages may be delivered out of order. This SDK is offered as a beta experience as we work with developers in the ecosystem to make this a more robust and reliable system.

Documentation: https://docs.opensea.io/reference/stream-js

# Installation

Please use Node.js version 16 or greater to make sure common crypto dependencies work.

- Install this package: `npm install @opensea/stream-js`
- Install types for phoenix: `npm install --save-dev @types/phoenix`
- **NodeJS only:** Install required libraries: `npm install ws node-localstorage`

# Getting Started

## Authentication

In order to make onboarding easy, we've integrated the OpenSea Stream API with our existing API key system. The API keys you have been using for the REST API should work here as well.

Get an API key instantly (no signup needed):

```bash
curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key'
```

Or get a full key at [opensea.io/settings/developer](https://opensea.io/settings/developer) for higher rate limits.

## Create a client

### Browser

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

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

### Node.js

```typescript
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
 }
});
```

You can also optionally pass in:

- a `network` parameter (defaults to `Network.MAINNET`)
- `apiUrl` if you would like to access another OpenSea Stream API endpoint. Not needed if you provide a network or use the default values.
- an `onError` callback to handle errors. The default behavior is to `console.error` the error.
- a `logLevel` to set the log level. The default is `LogLevel.INFO`.

## Available Networks

The OpenSea Stream API is available on mainnet:

### Mainnet

`wss://stream-api.opensea.io/socket`

## Manually connecting to the socket (optional)

The client will automatically connect to the socket as soon as you subscribe to the first channel.
If you would like to connect to the socket manually (before that), you can do so:

```typescript
client.connect();
```

After successfully connecting to our websocket it is time to listen to specific events you're interested in!

## Streaming metadata updates

We will only send out metadata updates when we detect that the metadata provided in `tokenURI` has changed from what OpenSea has previously cached.

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

## Streaming item listed events

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

## Streaming item sold events

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

## Streaming item transferred events

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

## Streaming bids and offers

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

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

## Streaming multiple event types

```typescript
client.onEvents(
 'collection-slug',
 [EventType.ITEM_RECEIVED_OFFER, EventType.ITEM_TRANSFERRED],
 (event) => {
 // handle event
 }
);
```

## Streaming order cancellations events

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

# Subscribing to events from all collections

If you'd like to listen to an event from all collections use wildcard `*` for the `collectionSlug` parameter.

# Event Versioning

Every stream event includes a numeric `version` field that is **monotonically increasing per source entity**. Use it to handle out-of-order event delivery: when two events arrive for the same entity, the one with the higher `version` is the newer state.

## Version scale depends on event type

The backend emits whichever authoritative monotonic counter exists for the underlying entity, so the *scale* of `version` varies:

| Event types | `version` semantic |
| --- | --- |
| `item_listed`, `item_cancelled`, `item_received_offer`, `item_received_bid`, `collection_offer`, `trait_offer`, `order_invalidate`, `order_revalidate` | Order revision counter (small monotonic integer per order) |
| `item_transferred`, `item_sold`, `item_metadata_updated` | Epoch milliseconds of the event's source timestamp |

Both representations are monotonic and sufficient for resolving out-of-order delivery, but the two scales are **not comparable to each other**. Never compare `version` across different event families or across unrelated entities — only compare versions for the same entity within the same event family.

## Usage

Scope your stored versions by event type (or by the source entity — order id for order-derived events, nft_id for item events):

```typescript
const latestOrderVersion = new Map<string, number>();

client.onItemListed('*', (event) => {
 const orderHash = event.payload.order_hash;
 const prev = latestOrderVersion.get(orderHash) ?? 0;
 if (event.version > prev) {
 latestOrderVersion.set(orderHash, event.version);
 // Process — this is newer state for this order
 }
 // Otherwise discard — we already have newer state for this order
});
```

Multiple backend pods process events, DLQ replays can deliver older state, and normal Kafka processing can deliver events out of order. Comparing `version` within the same entity lets consumers always converge to the correct current state.

# Types

Types are included to make working with our event payload objects easier.

# Disconnecting

## From a specific stream

All subscription methods return a callback function that will unsubscribe from a stream when invoked.

```typescript
const unsubscribe = client.onItemMetadataUpdated('collection-slug', () => {});

unsubscribe();
```

## From the socket

```typescript
client.disconnect();
```

## Contributing

This repository is a read-only mirror synced from an internal monorepo. We can't merge pull requests directly, but we review every one — if your fix or idea is solid, we'll recreate it internally and it will ship in the next release.

Issues and bug reports are the best way to contribute. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.

## License

[version-badge]: https://img.shields.io/github/package-json/v/ProjectOpenSea/stream-js
[version-link]: https://github.com/ProjectOpenSea/stream-js/releases
[npm-badge]: https://img.shields.io/npm/v/@opensea/stream-js?color=red
[npm-link]: https://www.npmjs.com/package/@opensea/stream-js
[ci-badge]: https://github.com/ProjectOpenSea/stream-js/actions/workflows/ci.yml/badge.svg
[ci-link]: https://github.com/ProjectOpenSea/stream-js/actions/workflows/ci.yml
[coverage-badge]: https://coveralls.io/repos/github/ProjectOpenSea/stream-js/badge.svg?branch=main
[coverage-link]: https://coveralls.io/github/ProjectOpenSea/stream-js?branch=main
[license-badge]: https://img.shields.io/github/license/ProjectOpenSea/stream-js
[license-link]: https://github.com/ProjectOpenSea/stream-js/blob/main/LICENSE
[docs-badge]: https://img.shields.io/badge/Stream.js-documentation-informational
[docs-link]: https://github.com/ProjectOpenSea/stream-js#getting-started

MIT License Copyright (c) 2022 OpenSea Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.