Docs
OpenSea

Search and Discovery

Build search and browse experiences using the OpenSea API and SDK.

The OpenSea API provides powerful search and browse endpoints for finding collections, tokens, NFTs, and accounts across all supported chains. Build search experiences, explore pages, and discovery features with the tools below.

Prerequisites

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

Setup

npm install @opensea/sdk ethers
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",
});

The examples below use ethers.js. For viem setup, see Buy and Sell NFTs — With viem. All SDK methods work the same with either library.

Universal Search

Search across collections, tokens, NFTs, and accounts in a single query. Results are typed so you can distinguish between result kinds.

SDK

const results = await sdk.api.search({
  query: "cool cats",
  chains: ["ethereum"],
  asset_types: ["collection", "nft"],
  limit: 10,
});

for (const result of results.results) {
  switch (result.type) {
    case "collection":
      console.log("Collection:", result.collection.name);
      break;
    case "nft":
      console.log("NFT:", result.nft.name);
      break;
    case "token":
      console.log("Token:", result.token.name);
      break;
    case "account":
      console.log("Account:", result.account.address);
      break;
  }
}

curl

curl -X GET "https://api.opensea.io/api/v2/search?query=cool+cats&chains=ethereum&asset_types=collection&asset_types=nft&limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"

Parameters:

ParameterDescription
querySearch query (required)
chainsFilter by chain(s) (e.g., ethereum, base, solana)
asset_typesFilter by type(s): collection, nft, token, account
limitMax results (1–50, default 20)

Browse Collections

List collections with optional filters for chain, creator, and ordering.

SDK

const collections = await sdk.api.getCollections({
  chain: "ethereum",
  limit: 20,
});

for (const collection of collections.collections) {
  console.log(collection.name, collection.collection);
}

curl

curl -X GET "https://api.opensea.io/api/v2/collections?chain=ethereum&limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"

Fetch NFTs

By Collection

const nfts = await sdk.api.getNFTsByCollection("boredapeyachtclub", 10);
curl -X GET "https://api.opensea.io/api/v2/collection/boredapeyachtclub/nfts?limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"

By Contract

const nfts = await sdk.api.getNFTsByContract(
  "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
  10,
);
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/contract/0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/nfts?limit=10" \
  -H "X-API-KEY: YOUR_API_KEY"

By Account (Owned NFTs)

const owned = await sdk.api.getNFTsByAccount("0xWALLET_ADDRESS", 20);
curl -X GET "https://api.opensea.io/api/v2/chain/ethereum/account/0xWALLET_ADDRESS/nfts?limit=20" \
  -H "X-API-KEY: YOUR_API_KEY"

Trait-Based Filtering

Retrieve the available traits for a collection, then use them to filter NFTs.

Get Available Traits

const traits = await sdk.api.getTraits("boredapeyachtclub");
console.log(traits);
// { "Background": { "values": ["Aquamarine", "Gold", "Orange", ...] }, ... }
curl -X GET "https://api.opensea.io/api/v2/traits/boredapeyachtclub" \
  -H "X-API-KEY: YOUR_API_KEY"

Filter by Trait

Use traits with the search or listing endpoints to narrow results. For example, find all "Gold" background Bored Apes with active listings:

curl -X GET "https://api.opensea.io/api/v2/listings/collection/boredapeyachtclub/all?string_traits=Background:Gold" \
  -H "X-API-KEY: YOUR_API_KEY"

Account Lookup

Get Account Details

const account = await sdk.api.getAccount("0xWALLET_ADDRESS");
console.log(account.username, account.address);
curl -X GET "https://api.opensea.io/api/v2/accounts/0xWALLET_ADDRESS" \
  -H "X-API-KEY: YOUR_API_KEY"

Resolve ENS or Username

const resolved = await sdk.api.resolveAccount("vitalik.eth");
console.log(resolved.address);

Chain Discovery

List all supported chains:

SDK

const chains = await sdk.api.getChains();
for (const chain of chains.chains) {
  console.log(chain.chain, chain.name);
}

curl

curl -X GET "https://api.opensea.io/api/v2/chains" \
  -H "X-API-KEY: YOUR_API_KEY"

CLI

The OpenSea CLI supports search and discovery:

# Universal search
opensea search "cool cats"

# Collection details
opensea collections get boredapeyachtclub

# NFTs in a collection
opensea nfts list-by-collection boredapeyachtclub --limit 5

# Account lookup
opensea accounts get 0xWALLET_ADDRESS

Next Steps

Updated 1 day ago