@opensea/sdk

TypeScript SDK for OpenSea. Read and filter the orderbook, create and fulfill listings and offers, swap tokens across chains, and subscribe to marketplace events.

Install

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.

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:

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. These keys don't expire, get higher rate limits, and can be rotated. See the API key docs.

Quick start

Do not ship your API key in frontend code. See Security warning.

With ethers.js

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

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 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.

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.

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:

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:

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:

import type { AccountResolveResponse } from "@opensea/api-types";
import type { Camelize } from "@opensea/sdk";

const account: Camelize<AccountResolveResponse> = 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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗