@opensea/sdk

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

npm install @opensea/sdk

With ethers.js

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

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)

// 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:

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 for the full flow and scope list.

Requirements

Node.js >= 20.0.0
OpenSea API key (get one here)
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:

github.com/ProjectOpenSea/opensea-js