---
updatedAt: 2026-09-24T00:12:39.000Z
agentTools:
  projectIndex: https://docs.opensea.io/llms.txt
---

# TypeScript SDK

TypeScript SDK for creating listings, making offers, fulfilling orders, and querying NFT data via the Seaport protocol. Supports both ethers.js and viem.

### What is @opensea/sdk?

`@opensea/sdk` is the TypeScript SDK for trading NFTs on OpenSea via the Seaport protocol. Create listings, make offers, fulfill orders, and query NFT data programmatically.

Supports both **ethers.js** and **viem** as wallet/provider libraries.

### Quick Start

```bash
npm install @opensea/sdk
```

#### With ethers.js

```typescript
import { ethers } from "ethers";
import { OpenSeaSDK, Chain } from "@opensea/sdk";

const provider = new ethers.JsonRpcProvider("https://your-rpc-url");

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("https://your-rpc-url") });
const walletClient = createWalletClient({ chain: mainnet, transport: http("https://your-rpc-url"), account: "0x..." });

const sdk = new OpenSeaSDK(
  { publicClient, walletClient },
  { chain: Chain.Mainnet, apiKey: "YOUR_API_KEY" },
);
```

#### Usage (same for both)

```typescript
// Get a collection
const collection = await sdk.api.getCollection("boredapeyachtclub");

// Make an offer
const offer = await sdk.createOffer({
  asset: { tokenAddress: "0x...", tokenId: "1" },
  accountAddress: "0x...",
  amount: 0.5,
});

// Create a listing
const listing = await sdk.createListing({
  asset: { tokenAddress: "0x...", tokenId: "1" },
  accountAddress: "0x...",
  amount: 3,
});

// Fulfill an order (buy or accept offer)
await sdk.fulfillOrder({ order, accountAddress: "0x..." });
```

### Wallet authentication

Server-side agents can use `OpenSeaAuth` with an ethers-compatible signer. It handles SIWE, creates a scoped PAT, and exchanges it for the short-lived wallet JWT used by REST and MCP:

```typescript
import { ethers } from "ethers";
import { OpenSeaAPI, OpenSeaAuth } from "@opensea/sdk";

const privateKey = process.env.OPENSEA_PRIVATE_KEY;
if (!privateKey) throw new Error("OPENSEA_PRIVATE_KEY is required");

const signer = new ethers.Wallet(privateKey);
const auth = new OpenSeaAuth();
const token = await auth.authenticate(signer, {
  scopes: ["read:favorites"],
});

try {
  const api = new OpenSeaAPI({
    apiKey: process.env.OPENSEA_API_KEY,
    authToken: token.accessToken,
  });
  await api.walletAuth.getFavorites(await signer.getAddress(), { limit: 10 });
} finally {
  const current = await auth.getValidToken();
  await auth.revoke(current.accessToken);
}
```

`OpenSeaAuth` keeps the PAT and SIWE session in memory. PAT management is session-only, so a wallet JWT cannot create, list, rotate, or revoke PATs. See [Authentication](https://docs.opensea.io/reference/auth) for the full flow and scope list.

### Requirements

* Node.js >= 20.0.0
* OpenSea API key ([get one here](https://docs.opensea.io/reference/api-keys))
* **ethers.js** (v6+) or **viem** (v2+) as your wallet/provider library

> **Security Warning:** Do not use the SDK in client-side code, since your API key would be exposed. Use it on a backend server and return transaction data to your frontend.

Keep private keys, API keys, PATs, JWTs, session cookies, signatures, and authorization headers out of logs and client-side code.

### Documentation

Full documentation including a getting started guide, API reference, advanced use cases (bulk orders, cancellation, event listeners), and FAQ is maintained in the GitHub repository:

<Anchor label="github.com/ProjectOpenSea/opensea-sdk" target="_blank" href="https://github.com/ProjectOpenSea/opensea-sdk">github.com/ProjectOpenSea/opensea-sdk</Anchor>

### Links

* <Anchor label="GitHub Repository" target="_blank" href="https://github.com/ProjectOpenSea/opensea-sdk">github.com/ProjectOpenSea/opensea-sdk</Anchor>
* <Anchor label="npm Package" target="_blank" href="https://www.npmjs.com/package/@opensea/sdk">@opensea/sdk on npm</Anchor>
* <Anchor label="Demo Project" target="_blank" href="https://github.com/ProjectOpenSea/buy-sell-opensea-sdk-demo">buy-sell-opensea-sdk-demo</Anchor>