Release v12.0.0

Origin-SHA: 93f028c503642e7e8e8e08080074ef23ea95cc05

Author: ryanio

AGENTS.md

@@ -27,16 +27,8 @@ pnpm run lint
 3. **Dual provider support**. Changes to `BaseOpenSeaSDK` affect both ethers and viem paths; update both provider adapters if provider-specific logic changes.
 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.
 5. **No secret leakage**. API keys live in `OpenSeaAPIConfig.apiKey`; never log them.
-6. **Stream stays on its own subpath**. `EventType`, `Trait`, `TraitOfferEvent`,
-   and `CollectionOfferEvent` exist in both surfaces with different shapes, so
-   `src/stream/` must never be re-exported from `src/index.ts`.
-7. **The stream transport is internal**. `src/stream/transport/` is not exported
-   from `src/stream/index.ts`. Stream API v2 will not speak Phoenix Channels, so
-   the interface must stay free to change without a breaking release. Client code
-   talks to `StreamTransport`, never to `PhoenixChannelsTransport` directly.
-8. **No dependency for the stream client**. `@opensea/sdk/stream` resolves to six
-   local files and nothing else. Verify with a require-graph walk before adding
-   any import there.
+6. **Auth scopes are coupled to the spec in both directions**. `src/scopes.ts` asserts at compile time that `OPENSEA_SCOPES` matches `AuthScope` from `@opensea/api-types`, so a new scope has to land in the spec and in the constant in the same commit, and that commit cannot pass the `Mirror layout` gate until api-types publishes. Read [Spec changes and release order](../../AGENTS.md#spec-changes-and-release-order) before starting.
+7. **Stream client is subpath-only and dependency-free**. `src/stream/` is exported from `./stream` and never from `src/index.ts` — `EventType`, `Trait`, `TraitOfferEvent`, and `CollectionOfferEvent` exist in both surfaces with different shapes. `src/stream/transport/` stays internal so a non-Phoenix Stream v2 can replace it without a breaking release; client code uses `StreamTransport`, never `PhoenixChannelsTransport`. The built entry resolves to six local files with zero external requires, so check the require graph before adding an import. Live tests are in `test/integration/stream.spec.ts` and need real network access, see `test/README-integration.md`.
 
 ## Conventions
 

CHANGELOG.md

@@ -1,5 +1,63 @@
 # @opensea/sdk
 
+## 12.0.0
+
+### Major Changes
+
+- 75aa2c2: **Breaking:** removes the retired wallet-level agent designation.
+
+  SDK: `WalletAuthAPI.markWalletAsAgent` and `WalletAuthAPI.removeWalletAgentDesignation` are gone. CLI: `opensea accounts mark-agent` and `opensea accounts remove-agent`, along with `client.accounts.markAgent` and `client.accounts.removeAgent` on `OpenSeaCLI`.
+
+  The endpoints they called, `PUT` and `DELETE /api/v2/accounts/wallets/{wallet}/agent`, no longer exist. os2-core removed them in ProjectOpenSea/os2-core#52946: over the 7 days before that, every `PUT` was rejected with 403 by a kill switch and no wallet's agent flag changed at all. Keeping the methods would mean shipping calls that 404.
+
+  An agent is an account, not a flag on a wallet. Use `declareAgentAccount`, `withdrawAgentAccountDeclaration`, and the `proposeAgentRelationship` / `confirmAgentRelationship` / `revokeAgentRelationship` handshake, or the `opensea agent` command group. Both are unchanged by this release.
+
+  `WalletAgentStatusResponse` is no longer re-exported from the CLI's `types/api`, since the schema goes away with the next spec sync.
+
+### Minor Changes
+
+- 6c0ee99: Add SDK and CLI support for agent accounts, so an agent can declare itself and complete the ownership handshake without hand-rolling HTTP.
+
+  An agent is an account, not a flag on a wallet. Ownership is a relationship between two accounts, mutually confirmed. It is a declaration, not an authorization: naming an account as your agent grants it no ability to act for you. It is self-reported and OpenSea does not verify it. An agent can have no owner at all, and at most one confirmed owner. Either side may withdraw or revoke at any time, which deletes the relationship. Only confirmed relationships are public.
+
+  SDK, on `WalletAuthAPI`: `declareAgentAccount`, `withdrawAgentAccountDeclaration`, `proposeAgentRelationship`, `confirmAgentRelationship`, `revokeAgentRelationship`, and `listOwnAgentRelationships`. `AccountsAPI.getAgentProfileRelationships` already covered the public read.
+
+  CLI, a new `agent` group: `declare`, `withdraw`, `propose`, `confirm`, `revoke`, `list`, and `profile`, plus a matching `client.agent` namespace on `OpenSeaCLI`.
+
+  The scopes differ, which is easy to get wrong. Every write takes `write:wallets` but listing your own relationships takes `read:wallets`, so a client driving the whole handshake must request both or the list call returns 403. `read:wallets` is now in `OPENSEA_SCOPES`, so the default OAuth grant carries it.
+
+  The OpenAPI snapshot is refreshed to generate all of this. That also picks up `read:wallets` in `AuthScope`, which was already live in the scope registry but missing from the committed snapshot, so `scripts/check-auth-scope-drift.mjs` was failing on main beforehand.
+
+  `AgentProfileRelationshipsResponse` no longer surfaces `agent_owner_profile` or `public_agent_wallets`. Both read the retired wallet-level designation, are permanently null and empty, and are removed by os2-core AGE-51. Read `agentOwner` and `agents` instead.
+
+  `markWalletAsAgent` and `removeWalletAgentDesignation` are deprecated. They set a flag on a wallet rather than declaring an account, and the server now rejects new designations; only the removal still works, so an account that set the old flag can clear it.
+
+### Patch Changes
+
+- ddadb41: Replace five hand-rolled API types with the generated ones from `@opensea/api-types`.
+
+  `packages/cli/AGENTS.md` and `packages/api-types/AGENTS.md` both say never to hand-roll API request or response types, but these five predate the rule and duplicated schemas the spec already covered.
+
+  In the SDK: `GetChainsResponse` becomes `Camelize<ChainListResponse>`, `DropMintRequest` and `DropMintResponse` become `Camelize<>` of the identically named generated schemas, `ResolveAccountResponse` becomes `Camelize<AccountResolveResponse>`, and `ValidateMetadataResponse` becomes `Camelize<>` of the generated schema, which decomposes into `ValidateMetadataAssetIdentifier`, `ValidateMetadataDetails`, `ValidateMetadataAttribute` and `MetadataIngestionError`. In the CLI: `ValidateMetadataResponse` becomes a `Schemas[...]` re-export, the one declared violation in a file that is otherwise all re-exports.
+
+  No shape change. Each replacement was diffed field by field against the spec, including required and optional, and they match exactly, so this is types-only with no runtime or behavioral effect. Four of the five were already correct re-exports in the CLI and hand-rolled only in the SDK, so the two packages had disagreed about the same names.
+
+- cfbb465: `onItemReceivedOffer` is now a no-op. The Stream API does not emit `item_received_offer` and never has, so the method only ever registered a handler that could not fire. Confirmed against production: four minutes on `collection:*` delivered 736k events across ten event names and this was not among them, while every other type appeared within 1.8s.
+
+  Item-level offers arrive as `item_received_bid`, which carries an identical payload. Use `onItemReceivedBid`.
+
+  The method stays callable so existing code compiles and runs unchanged, and it no longer opens a connection for a topic that yields nothing. `EventType.ITEM_RECEIVED_OFFER`, `ItemReceivedOfferEvent`, and `ItemReceivedOfferEventPayload` are kept for source compatibility but marked deprecated and hidden from the generated docs.
+
+- 6e77b5e: `fulfillOrder` now appends the attribution suffix the fulfillment endpoints return, so fills built by the SDK are attributed to OpenSea onchain. They were not before: the API returns `calldata_suffix` (the first four bytes of `keccak256("api.opensea.io")`) and carries it as trailing calldata on its own transactions, but the SDK re-encodes the call from `input_data` and signed that instead, which dropped it. Seaport reads its arguments from offsets and ignores trailing bytes, so the suffix does not affect execution. A missing or malformed suffix is ignored rather than raised.
+
+  Private listings are unaffected. They are fulfilled locally through seaport-js and never receive API calldata, so there is no suffix to re-attach. `fulfillPrivateOrder` already takes a `domain` for that purpose; `fulfillOrder` neither accepts nor forwards one, so private fills through it stay unattributed.
+
+  `FulfillmentDataResponse` is now derived from `@opensea/api-types` instead of hand-rolled. It had drifted: no `calldataSuffix`, no `valueHex`, four `inputData` members against the spec's seven, and a basic-order member named `basicOrderParameters` where the API sends `parameters`, so that branch never matched and the fallback built the arguments instead. Same result for a single-field struct, so no behavior change there.
+
+- f74c0be: Deduplicate Stream API payload types and logging internals without changing the public API.
+- Updated dependencies [5fdac00]
+  - @opensea/api-types@0.8.10
+
 ## 11.9.0
 
 ### Minor Changes

README.md

@@ -82,8 +82,7 @@ try {
     authToken: token.accessToken,
   })
   await api.walletAuth.getFavorites(await signer.getAddress(), { limit: 10 })
-  await api.walletAuth.markWalletAsAgent(await signer.getAddress())
-  await api.walletAuth.removeWalletAgentDesignation(await signer.getAddress())
+  await api.walletAuth.declareAgentAccount()
 } finally {
   await auth.revoke(token.accessToken)
 }

developerDocs/stream-migration.md

@@ -145,8 +145,8 @@ seaport, and no third-party runtime code.
 ## What did not change
 
 - Every `on*` method: `onItemListed`, `onItemSold`, `onItemTransferred`,
-  `onItemMetadataUpdated`, `onItemCancelled`, `onItemReceivedOffer`,
-  `onItemReceivedBid`, `onCollectionOffer`, `onTraitOffer`,
+  `onItemMetadataUpdated`, `onItemCancelled`, `onItemReceivedBid`,
+  `onCollectionOffer`, `onTraitOffer`,
   `onOrderInvalidate`, `onOrderRevalidate`, and `onEvents`.
 - Every event and payload type, unchanged field for field.
 - `EventType`, `LogLevel`, `Network`, `OnClientEvent`, and `Callback`.