Add Search API endpoint (#1918)

* Add Search API endpoint and bump version to 8.0.17

Add search endpoint for discovering collections, tokens, NFTs, and accounts
with support for chain and asset type filtering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add search endpoint integration tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ryanio

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensea-js",
-  "version": "8.0.16",
+  "version": "8.0.17",
   "description": "TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data",
   "license": "MIT",
   "author": "OpenSea Developers",

src/api/api.ts

@@ -6,6 +6,7 @@ import { EventsAPI } from "./events";
 import { ListingsAPI } from "./listings";
 import { NFTsAPI } from "./nfts";
 import { OffersAPI } from "./offers";
+import { SearchAPI } from "./search";
 import { TokensAPI } from "./tokens";
 import {
   FulfillmentDataResponse,
@@ -50,6 +51,8 @@ import {
   GetSwapQuoteArgs,
   GetSwapQuoteResponse,
   GetTokenResponse,
+  SearchArgs,
+  SearchResponse,
 } from "./types";
 import { executeWithRateLimit } from "../utils/rateLimit";
 
@@ -82,6 +85,7 @@ export class OpenSeaAPI {
   private nftsAPI: NFTsAPI;
   private accountsAPI: AccountsAPI;
   private eventsAPI: EventsAPI;
+  private searchAPI: SearchAPI;
   private tokensAPI: TokensAPI;
 
   /**
@@ -116,6 +120,7 @@ export class OpenSeaAPI {
     this.nftsAPI = new NFTsAPI(fetcher, this.chain);
     this.accountsAPI = new AccountsAPI(fetcher, this.chain);
     this.eventsAPI = new EventsAPI(fetcher);
+    this.searchAPI = new SearchAPI(fetcher);
     this.tokensAPI = new TokensAPI(fetcher);
   }
 
@@ -705,6 +710,16 @@ export class OpenSeaAPI {
     return this.tokensAPI.getToken(chain, address);
   }
 
+  /**
+   * Search across collections, tokens, NFTs, and accounts.
+   * Results are ranked by relevance.
+   * @param args Query parameters including query text, optional chain/asset type filters, and limit.
+   * @returns The {@link SearchResponse} returned by the API.
+   */
+  public async search(args: SearchArgs): Promise<SearchResponse> {
+    return this.searchAPI.search(args);
+  }
+
   /**
    * Gets all active offers for a specific NFT (not just the best offer).
    * @param assetContractAddress The NFT contract address.

src/api/apiPaths.ts

@@ -159,3 +159,7 @@ export const getSwapQuotePath = () => {
 export const getTokenPath = (chain: string, address: string) => {
   return `/api/v2/chain/${chain}/token/${address}`;
 };
+
+export const getSearchPath = () => {
+  return "/api/v2/search";
+};

src/api/search.ts

@@ -0,0 +1,21 @@
+import { getSearchPath } from "./apiPaths";
+import { Fetcher } from "./fetcher";
+import { SearchArgs, SearchResponse } from "./types";
+
+/**
+ * Search-related API operations
+ */
+export class SearchAPI {
+  constructor(private fetcher: Fetcher) {}
+
+  /**
+   * Search across collections, tokens, NFTs, and accounts.
+   */
+  async search(args: SearchArgs): Promise<SearchResponse> {
+    const response = await this.fetcher.get<SearchResponse>(
+      getSearchPath(),
+      args,
+    );
+    return response;
+  }
+}

src/api/types.ts

@@ -756,3 +756,120 @@ export type GetSwapQuoteResponse = {
  * @category API Response Types
  */
 export type GetTokenResponse = Token;
+
+/**
+ * Query args for the Search endpoint.
+ * @category API Query Args
+ */
+export interface SearchArgs {
+  /** Search query text */
+  query: string;
+  /** Filter by blockchain(s) */
+  chains?: string[];
+  /** Filter by asset type(s): collection, nft, token, account */
+  asset_types?: string[];
+  /** Number of results to return (default: 20, max: 50) */
+  limit?: number;
+}
+
+/**
+ * Collection search result.
+ * @category API Models
+ */
+export type CollectionSearchResult = {
+  /** The collection slug */
+  collection: string;
+  /** The collection name */
+  name: string;
+  /** URL of the collection image */
+  image_url: string | null;
+  /** Whether trading is disabled for this collection */
+  is_disabled: boolean;
+  /** Whether this collection is marked as NSFW */
+  is_nsfw: boolean;
+  /** URL to the collection on OpenSea */
+  opensea_url: string;
+};
+
+/**
+ * Token (currency) search result.
+ * @category API Models
+ */
+export type TokenSearchResult = {
+  /** Contract address of the token */
+  address: string;
+  /** Blockchain the token is on */
+  chain: string;
+  /** Token name */
+  name: string;
+  /** Token symbol */
+  symbol: string;
+  /** URL of the token image */
+  image_url: string | null;
+  /** Current USD price of the token */
+  usd_price: string;
+  /** Number of decimal places for the token */
+  decimals: number;
+  /** URL to the token on OpenSea */
+  opensea_url: string;
+};
+
+/**
+ * NFT search result.
+ * @category API Models
+ */
+export type NftSearchResult = {
+  /** Token ID of the NFT */
+  identifier: string;
+  /** Collection slug the NFT belongs to */
+  collection: string;
+  /** Contract address of the NFT */
+  contract: string;
+  /** Name of the NFT */
+  name: string | null;
+  /** URL of the NFT image */
+  image_url: string | null;
+  /** URL to the NFT on OpenSea */
+  opensea_url: string;
+};
+
+/**
+ * Account search result.
+ * @category API Models
+ */
+export type AccountSearchResult = {
+  /** Primary wallet address of the account */
+  address: string;
+  /** Username of the account */
+  username: string | null;
+  /** URL of the account's profile image */
+  profile_image_url: string | null;
+  /** URL to the account on OpenSea */
+  opensea_url: string;
+};
+
+/**
+ * A single search result with a type discriminator and the corresponding typed object.
+ * @category API Models
+ */
+export type SearchResult = {
+  /** The type of search result */
+  type: string;
+  /** Collection details, present when type is 'collection' */
+  collection?: CollectionSearchResult;
+  /** Token details, present when type is 'token' */
+  token?: TokenSearchResult;
+  /** NFT details, present when type is 'nft' */
+  nft?: NftSearchResult;
+  /** Account details, present when type is 'account' */
+  account?: AccountSearchResult;
+};
+
+/**
+ * Response from OpenSea API for search.
+ * @category API Response Types
+ */
+export type SearchResponse = {
+  /** List of search results ranked by relevance */
+  results: SearchResult[];
+};