You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: AGENTS.md
+12Lines changed: 12 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,7 @@ pnpm run lint
16
16
## Responsibilities
17
17
18
18
- Provide `OpenSeaSDK` (ethers) and `OpenSeaViemSDK` (viem) entry points.
19
+
- Provide the Stream API client at the `@opensea/sdk/stream` subpath.
19
20
- Camelize API responses and expose typed helpers for orders, fulfillment, assets, and wallet auth.
20
21
- Keep the `Chain` enum in sync with `ChainIdentifier` from `@opensea/api-types`.
21
22
@@ -26,9 +27,20 @@ pnpm run lint
26
27
3.**Dual provider support**. Changes to `BaseOpenSeaSDK` affect both ethers and viem paths; update both provider adapters if provider-specific logic changes.
27
28
4.**OAuth token contract**. `OpenSeaOAuth` requests `offline_access`; refresh responses may omit rotation — keep the previous refresh token. The top-level `wallet` JWT claim is wallet identity; `sub` is an account id.
28
29
5.**No secret leakage**. API keys live in `OpenSeaAPIConfig.apiKey`; never log them.
30
+
6.**Stream stays on its own subpath**. `EventType`, `Trait`, `TraitOfferEvent`,
31
+
and `CollectionOfferEvent` exist in both surfaces with different shapes, so
32
+
`src/stream/` must never be re-exported from `src/index.ts`.
33
+
7.**The stream transport is internal**. `src/stream/transport/` is not exported
34
+
from `src/stream/index.ts`. Stream API v2 will not speak Phoenix Channels, so
35
+
the interface must stay free to change without a breaking release. Client code
36
+
talks to `StreamTransport`, never to `PhoenixChannelsTransport` directly.
37
+
8.**No dependency for the stream client**. `@opensea/sdk/stream` resolves to six
38
+
local files and nothing else. Verify with a require-graph walk before adding
39
+
any import there.
29
40
30
41
## Conventions
31
42
32
43
- CommonJS (`"type": "commonjs"`) for broad consumer support.
44
+
- Node 22+ is the floor. The stream client relies on a global `WebSocket`.
33
45
-`viem` is an optional peer dependency; main entry uses ethers.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,35 @@
1
1
# @opensea/sdk
2
2
3
+
## 11.9.0
4
+
5
+
### Minor Changes
6
+
7
+
- d355093: Three fixes from community reports on the public mirror, each of which changes behavior for input that previously produced a wrong answer or an unhelpful crash.
8
+
9
+
**`getTraits` no longer camelizes its response.** The fetcher rewrites every response's keys from snake_case to camelCase, which is right for the spec-derived endpoints and wrong for this one: its keys are the collection's own trait names and trait values. A `fur_color` trait was reported as `furColor`, and a collection with both `dark_brown` and `darkBrown` values had them merged into one entry whose count was wrong, with nothing in the response to indicate it. `RequestOptions` gains a `camelizeResponse` opt-out, honored by both reads and writes, and `getTraits` is the only caller that sets it. If you have been reading camelized trait keys since 11.0.0, they now come back as the collection authored them. (ProjectOpenSea/opensea-js#1989)
10
+
11
+
**`parseUnits` accepts scientific notation from strings.** It only stripped exponent notation when the value was a `number`, so `parseUnits("1e-8", 18)` reached `BigInt` intact and threw `Cannot convert 1e-8000000000000000000 to a BigInt`. Any caller that stringifies an amount first hit this, including the SDK's own `wrapEth`, `unwrapWeth`, and listing/offer price paths, which all call `amount.toString()`. Expansion is now done with string math rather than `Number.prototype.toFixed`, so large values stay exact (`toFixed` corrupts above 2^53 and returns exponential notation again at or above 1e21) and a value below the token's precision throws `Too many decimal places` rather than silently truncating to zero. Malformed input now throws `Invalid decimal value` instead of a raw `SyntaxError` from `BigInt`, and an empty string throws rather than parsing as `0`. (ProjectOpenSea/opensea-js#1990)
12
+
13
+
**Private listings reject payment items in different tokens.**`constructPrivateListingCounterOrder` checked that every payment item shared an `itemType` but not that they shared a token, then summed them into a single offer item denominated in the first item's token: 100 TOKEN_A plus 20 TOKEN_B became 120 TOKEN_A. Seaport rejected the resulting match, so the failure surfaced as an onchain revert instead of an SDK error. Token comparison is case-insensitive, so the same address in checksummed and lowercase form is still one currency. (ProjectOpenSea/opensea-js#1991)
14
+
15
+
- 8527112: Add the OpenSea Stream API client at the `@opensea/sdk/stream` subpath, replacing the standalone `@opensea/stream-js` package.
16
+
17
+
The client speaks the Phoenix Channels wire protocol directly instead of depending on `phoenix`, so the subpath resolves to six local files and no third-party runtime code. Importing it pulls in neither ethers nor seaport. The transport sits behind an internal interface so a future Stream API v2, which will not use Phoenix framing, can be added without a breaking change.
18
+
19
+
Migrating from `@opensea/stream-js` is mostly an import change. See `developerDocs/stream-migration.md`.
20
+
21
+
- Node users no longer need `ws` or `node-localstorage`. Node 22+ and browsers supply a global `WebSocket`, and `sessionStorage` was only read by an unused long-poll fallback.
22
+
-`apiKey` replaces `token` in `ClientConfig`. `token` still works and is deprecated.
23
+
-`connectOptions` is now `StreamConnectOptions` rather than `Partial<SocketConnectOption>` from `@types/phoenix`. Options that only fed the long-poll fallback and binary serializer are gone.
24
+
- Unsubscribing now removes a single handler instead of leaving the whole collection channel. Previously, two subscriptions on one collection meant unsubscribing from one silently stopped the other.
25
+
-`engines.node` is raised to `>=22.0.0`. Node 20 reached end of life in April 2026.
26
+
27
+
### Patch Changes
28
+
29
+
- 8715ac2: Point the package metadata at the renamed public repo, `ProjectOpenSea/opensea-sdk`. `repository.url` and `bugs.url` both moved, so the npm page links to the right place rather than relying on GitHub's rename redirect. The npm package name is unchanged.
30
+
31
+
Also drops the TypeDoc setup that fed the GitHub Pages site at `projectopensea.github.io/opensea-js`. Nothing published it: no workflow built the `gh-pages` branch, so the site had been serving v8.0.20 docs against a shipped 11.8.0 for months. The `docs-build` and `docs-build-md` scripts, the `typedoc` and `typedoc-plugin-markdown` devDependencies, and `.config/typedoc.json` are gone, along with the dead Coveralls badge (that project returns 403 and no CI job has uploaded coverage in a long time). Method-level reference docs live in `developerDocs/api-reference.md`.
Copy file name to clipboardExpand all lines: developerDocs/faq.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,19 +15,19 @@ hidden: false
15
15
16
16
## How do I access the source code?
17
17
18
-
The source code for the SDK can be found on [GitHub](https://github.com/ProjectOpenSea/opensea-js).
18
+
The source code for the SDK can be found on [GitHub](https://github.com/ProjectOpenSea/opensea-sdk).
19
19
20
20
## What chains are supported?
21
21
22
-
See the `Chain` enum in [`src/types.ts`](https://github.com/ProjectOpenSea/opensea-js/blob/main/src/types.ts) for a complete list of supported chains.
22
+
See the `Chain` enum in [`src/types.ts`](https://github.com/ProjectOpenSea/opensea-sdk/blob/main/src/types.ts) for a complete list of supported chains.
23
23
24
24
Please use methods in the v2 API for multichain capabilities.
25
25
26
26
## Why is there no SDK method for the API request I am trying to call?
27
27
28
28
First, check the [API Reference](api-reference.md) to see all available SDK methods - many OpenSea API v2 endpoints are now supported.
29
29
30
-
If the SDK does not currently have a specific API, you can use the generic `get` and `post` methods on the `OpenSeaAPI` class in [`src/api/api.ts`](https://github.com/ProjectOpenSea/opensea-js/blob/main/src/api/api.ts) to make any API request. This repository is also open source, so please feel free to create a pull request.
30
+
If the SDK does not currently have a specific API, you can use the generic `get` and `post` methods on the `OpenSeaAPI` class in [`src/api/api.ts`](https://github.com/ProjectOpenSea/opensea-sdk/blob/main/src/api/api.ts) to make any API request. This repository is also open source, so please feel free to create a pull request.
0 commit comments