# opensea-sdk
**Repository Path**: ProjectOpenSea/opensea-sdk
## Basic Information
- **Project Name**: opensea-sdk
- **Description**: TypeScript SDK for the OpenSea marketplace
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-11-17
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[![Version][version-badge]][version-link]
[![npm][npm-badge]][npm-link]
[![Test CI][ci-badge]][ci-link]
[![License][license-badge]][license-link]
[![Docs][docs-badge]][docs-link]
[![Discussions][discussions-badge]][discussions-link]
# @opensea/sdk
TypeScript SDK for [OpenSea](https://opensea.io). Read and filter the orderbook, create and fulfill listings and offers, swap tokens across chains, and subscribe to marketplace events.
## Install
```bash
npm install @opensea/sdk
```
Requires Node.js 22 or newer. `ethers` ships as a dependency; install `viem` too if you use the viem entry point.
## Get an API key
For quick experiments, request a free-tier key in code. It needs no signup and expires after 7 days.
```typescript
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";
const provider = new ethers.JsonRpcProvider("https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY");
const { apiKey } = await OpenSeaSDK.requestInstantApiKey();
const sdk = new OpenSeaSDK(provider, { chain: Chain.Mainnet, apiKey });
```
Or from the shell:
```bash
curl -s -X POST https://api.opensea.io/api/v2/auth/keys | jq -r '.api_key'
```
For production, create a permanent key at [opensea.io/settings/developer](https://opensea.io/settings/developer). These keys don't expire, get higher rate limits, and can be rotated. See the [API key docs](https://docs.opensea.io/reference/api-keys).
## Quick start
Do not ship your API key in frontend code. See [Security warning](#security-warning).
### With ethers.js
```typescript
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";
const provider = new ethers.JsonRpcProvider("https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY");
const sdk = new OpenSeaSDK(provider, { chain: Chain.Mainnet, apiKey: "YOUR_API_KEY" });
```
### With viem
```typescript
import { createPublicClient, createWalletClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { OpenSeaSDK, Chain } from '@opensea/sdk/viem'
const publicClient = createPublicClient({ chain: mainnet, transport: http() })
const sdk = new OpenSeaSDK({ publicClient }, { chain: Chain.Mainnet, apiKey: 'YOUR_API_KEY' })
```
### With a wallet adapter
To sign with a managed wallet (Privy, Turnkey, Fireblocks, Bankr) or a raw private key, wrap a
[`@opensea/wallet-adapters`](https://github.com/ProjectOpenSea/wallet-adapters) adapter in its
ethers bridge and pass the result as the signer. Orders are signed with the adapter's
`signTypedData`. Fulfillments, approvals and onchain cancels go through its `sendTransaction`.
The provider handles reads and receipts only.
```typescript
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";
import { createWalletFromEnv } from "@opensea/wallet-adapters";
import { walletAdapterToEthersSigner } from "@opensea/wallet-adapters/ethers";
const provider = new ethers.JsonRpcProvider("https://mainnet.base.org");
const signer = walletAdapterToEthersSigner(createWalletFromEnv(), provider);
const sdk = new OpenSeaSDK(signer, { chain: Chain.Base, apiKey: "YOUR_API_KEY" });
const listing = await sdk.createListing({
asset: { tokenAddress, tokenId },
accountAddress: await signer.getAddress(),
amount: "0.5",
});
```
Creating listings and offers requires an adapter that supports typed-data signing
(`wallet.capabilities.signTypedData`).
## Calling the API
`sdk.api` groups methods by domain: `accounts`, `assets`, `chains`, `collections`, `drops`,
`events`, `listings`, `nfts`, `offers`, `orders`, `tokens`, `tools` (beta), `transactions` and
`walletAuth`. For example, `sdk.api.collections.getCollection(slug)` or
`sdk.api.offers.getAllOffers(...)`. Search is the one flat method: `sdk.api.search(args)`.
Version 14 removed the older flat methods such as `sdk.api.getCollection(slug)`. Each one maps to
the namespaced method of the same name, except four that were renamed; see the
[API reference](developerDocs/api-reference.md#calling-the-api).
## Response casing
The API uses snake_case. The SDK converts response keys to camelCase, and converts camelCase
request bodies and query params to snake_case. You read `collection.bannerImageUrl`; the wire
carries `banner_image_url`.
`@opensea/api-types` describes the wire format, so its types are snake_case. Don't use them to
annotate a value an SDK method returned:
```typescript
import type { AccountResolveResponse } from "@opensea/api-types";
// Wrong. This compiles, and every snake_case field reads undefined at runtime.
const account: AccountResolveResponse = await sdk.api.accounts.resolveAccount("vitalik.eth");
console.log(account.ens_name); // undefined; the runtime key is `ensName`
```
TypeScript only rejects this when the wire type has a required snake_case key somewhere in its
tree. `AccountResolveResponse` has one required property, `address`, which has no underscore, so
the camelCase object type-checks and every snake_case field is `undefined` at runtime.
Use the SDK's own response type, which is already camelCase:
```typescript
import type { ResolveAccountResponse } from "@opensea/sdk";
const account: ResolveAccountResponse = await sdk.api.accounts.resolveAccount("vitalik.eth");
console.log(account.ensName);
```
Or, for a response with no SDK alias, wrap the wire type in `Camelize`:
```typescript
import type { AccountResolveResponse } from "@opensea/api-types";
import type { Camelize } from "@opensea/sdk";
const account: Camelize = await sdk.api.accounts.resolveAccount("vitalik.eth");
```
Pass `camelizeResponse: false` to skip the conversion for one call. Use it when response keys are
data rather than field names. `getTraits`, for example, is keyed by trait names the collection
chose, so conversion would turn a `dark_brown` trait into `darkBrown` and merge two traits that
differ only in casing.
Write it as the literal `false`. `api.get`, `api.post` and `api.request` have an overload for
that literal that returns the raw `T`, so the declared type matches the response:
```typescript
type UploadPolicy = { upload_url: string; success_action_status: string };
const policy = await sdk.api.get("/api/v2/some/path", undefined, {
camelizeResponse: false,
});
console.log(policy.success_action_status); // typed, and present at runtime
// @ts-expect-error the rewrite did not run, so there is no `successActionStatus`
console.log(policy.successActionStatus);
```
TypeScript keeps the literal only when the option is written inline at the call site or the
object is declared `as const`. In the cases below the runtime still skips the conversion, but the
declared type is `Camelize`, which claims camelCase properties the response doesn't have:
```typescript
type UploadPolicy = { upload_url: string; success_action_status: string };
declare const skipRewrite: boolean;
// A boolean whose value the compiler cannot see.
await sdk.api.get("/api/v2/some/path", undefined, {
camelizeResponse: skipRewrite,
});
// A `const` declaration widens `false` to `boolean`; `as const` keeps the literal.
const options = { camelizeResponse: false };
await sdk.api.get("/api/v2/some/path", undefined, options);
```
## Examples
### Wallet-authenticated API
For a server-side EVM signer, `OpenSeaAuth` signs in with SIWE, creates a scoped personal access
token (PAT), and exchanges it for the short-lived JWT that REST and MCP accept.
```typescript
import { Wallet } from "ethers"
import { OpenSeaAPI, OpenSeaAuth } from "@opensea/sdk"
const signer = new Wallet(process.env.OPENSEA_PRIVATE_KEY!)
const auth = new OpenSeaAuth()
let token = await auth.authenticate(signer, { scopes: ["read:favorites"] })
try {
token = await auth.getValidToken()
const api = new OpenSeaAPI({
apiKey: process.env.OPENSEA_API_KEY,
authToken: token.accessToken,
})
await api.walletAuth.getFavorites(await signer.getAddress(), { limit: 10 })
await api.walletAuth.declareAgentAccount()
} finally {
await auth.revoke(token.accessToken)
}
```
Keep the same `OpenSeaAuth` instance until you revoke, because it holds the SIWE session.
`revoke()` takes the current JWT as a guard, revokes the PAT behind it, and clears the in-memory
auth state. `walletAuth` has a typed helper for every deployed scoped operation. Request only the
scopes the task needs. See the [wallet-auth guide](https://docs.opensea.io/reference/auth).
### Cross-chain drop minting
Build the ordered transactions to pay on one chain and mint a drop on another:
```typescript
const mint = await sdk.api.drops.buildCrossChainMintTransactions("pyro-on-ape", {
payer: "0x1111111111111111111111111111111111111111",
minter: "0x1111111111111111111111111111111111111111",
quantity: 1,
payment: {
chain: "base",
tokenAddress: "0x0000000000000000000000000000000000000000",
},
})
// Submit mint.transactions in order, then poll the exact returned request.
const receipt = await sdk.api.transactions.getTransactionReceipt(mint.receiptRequest)
```
### Order actions on EVM and Solana
The action APIs return the ordered approval, signing and transaction steps a wallet needs to
run. On Solana, pass `svm_order.id` as the order identifier and keep base58 addresses in their
original case.
```typescript
const actions = await sdk.api.listings.createListingFulfillmentActions({
listing: {
hash: "",
chain: "solana",
protocolAddress: "",
},
fulfiller: { address: "" },
includeOptionalCreatorFees: false,
})
// Also available:
// sdk.api.offers.createOfferActions(request)
// sdk.api.offers.createOfferFulfillmentActions(request)
// sdk.api.orders.createCancelOrderActions(protocol, orderIdentifier, request, chain)
```
Run `actions.steps` in order. If a Solana step includes a partially signed transaction or needs a
Jito bundle, submit it exactly as the response directs. Don't rebuild it or broadcast it through a
public RPC.
### Token activity stats
Get precomputed trade count and USD volume for a token without aggregating raw events:
```typescript
import { Chain } from "@opensea/sdk";
const activity = await sdk.api.tokens.getTokenActivityStats(
Chain.Base,
"0x4200000000000000000000000000000000000006",
{ windows: ["1h", "24h"] },
)
console.log(activity.windows["24h"]?.trades)
console.log(activity.windows["24h"]?.volumeUsd)
```
A requested window is missing from `windows` when the token had no swaps in that period.
### Real-time events
Subscribe to marketplace events over WebSocket with the `@opensea/sdk/stream` subpath. Stream
events don't count toward your API rate limits.
```typescript
import { OpenSeaStreamClient, EventType } from "@opensea/sdk/stream";
const client = new OpenSeaStreamClient({ apiKey: "YOUR_API_KEY" });
// Listings for one collection, by slug
const unsubscribe = client.onItemListed("doodles-official", event => {
console.log(event.payload.item.nft_id, event.payload.base_price);
});
// Sales across every collection
client.onItemSold("*", event => console.log(event.payload.sale_price));
// Several event types at once, filtered server-side
client.onEvents(
"doodles-official",
[EventType.ITEM_SOLD, EventType.ITEM_CANCELLED],
console.log,
);
unsubscribe();
```
It runs in Node 22+ and browsers with no extra dependencies. After a dropped connection, the
client reconnects with backoff and re-subscribes to every topic it was watching.
Before version 0.4.0 this client was published as `@opensea/stream-js`. See the
[migration guide](developerDocs/stream-migration.md).
## Documentation
- [Quick start guide](developerDocs/quick-start.md)
- [Getting started guide](developerDocs/getting-started.md)
- [API reference](developerDocs/api-reference.md)
- [Stream migration from @opensea/stream-js](developerDocs/stream-migration.md)
- [Advanced use cases](developerDocs/advanced-use-cases.md)
- [FAQ](developerDocs/faq.md)
- [Contributing](CONTRIBUTING.md)
## Security warning
Don't use this SDK in frontend code. It needs your API key, and anyone can extract a key embedded
in a browser or mobile app, then abuse it or burn through your rate limit.
For a frontend app:
1. Run your own backend that stores the API key.
2. Call `@opensea/sdk` from that backend.
3. Return what the frontend needs, such as transaction parameters.
4. Have users sign transactions in the browser with their own wallet (for example, MetaMask).
## Changelog
- @opensea/sdk: https://github.com/ProjectOpenSea/opensea-sdk/releases
- OpenSea API: https://docs.opensea.io/changelog
## Contributing
Read-only mirror of a private monorepo, updated on each release. Pull requests are welcome, and we bring accepted changes into the monorepo.
## Security
Found a vulnerability? Report it through OpenSea's Bugcrowd program at https://bugcrowd.com/engagements/opensea rather than opening a public issue. See [SECURITY.md](SECURITY.md).
[version-badge]: https://img.shields.io/github/package-json/v/ProjectOpenSea/opensea-sdk
[version-link]: https://github.com/ProjectOpenSea/opensea-sdk/releases
[npm-badge]: https://img.shields.io/npm/v/@opensea/sdk?color=red
[npm-link]: https://www.npmjs.com/package/@opensea/sdk
[ci-badge]: https://github.com/ProjectOpenSea/opensea-sdk/actions/workflows/ci.yml/badge.svg
[ci-link]: https://github.com/ProjectOpenSea/opensea-sdk/actions/workflows/ci.yml
[license-badge]: https://img.shields.io/github/license/ProjectOpenSea/opensea-sdk
[license-link]: https://github.com/ProjectOpenSea/opensea-sdk/blob/main/LICENSE
[docs-badge]: https://img.shields.io/badge/@opensea/sdk-documentation-informational
[docs-link]: https://github.com/ProjectOpenSea/opensea-sdk#documentation
[discussions-badge]: https://img.shields.io/badge/@opensea/sdk-discussions-blueviolet
[discussions-link]: https://github.com/ProjectOpenSea/opensea-sdk/discussions