ProjectOpenSea · ryanio · Feb 25, 2026 · Feb 25, 2026
diff --git a/src/cli.ts b/src/cli.ts
@@ -11,6 +11,7 @@ import {
   swapsCommand,
   tokensCommand,
 } from "./commands/index.js"
+import { parseIntOption } from "./parse.js"
 
 const BANNER = `
    ____                   _____
@@ -34,12 +35,16 @@ program
   .option("--chain <chain>", "Default chain", "ethereum")
   .option("--format <format>", "Output format (json or table)", "json")
   .option("--base-url <url>", "API base URL")
+  .option("--timeout <ms>", "Request timeout in milliseconds", "30000")
+  .option("--verbose", "Log request and response info to stderr")
 
 function getClient(): OpenSeaClient {
   const opts = program.opts<{
     apiKey?: string
     chain: string
     baseUrl?: string
+    timeout: string
+    verbose?: boolean
   }>()
 
   const apiKey = opts.apiKey ?? process.env.OPENSEA_API_KEY
@@ -54,6 +59,8 @@ function getClient(): OpenSeaClient {
     apiKey,
     chain: opts.chain,
     baseUrl: opts.baseUrl,
+    timeout: parseIntOption(opts.timeout, "--timeout"),
+    verbose: opts.verbose,
   })
 }
 
@@ -91,7 +98,19 @@ async function main() {
       )
       process.exit(1)
     }
-    throw error
+    const label =
+      error instanceof TypeError ? "Network Error" : (error as Error).name
+    console.error(
+      JSON.stringify(
+        {
+          error: label,
+          message: (error as Error).message,
+        },
+        null,
+        2,
+      ),
+    )
+    process.exit(1)
   }
 }
 

diff --git a/src/client.ts b/src/client.ts
@@ -2,18 +2,23 @@ import type { OpenSeaClientConfig } from "./types/index.js"
 
 const DEFAULT_BASE_URL = "https://api.opensea.io"
 const DEFAULT_GRAPHQL_URL = "https://gql.opensea.io/graphql"
+const DEFAULT_TIMEOUT_MS = 30_000
 
 export class OpenSeaClient {
   private apiKey: string
   private baseUrl: string
   private graphqlUrl: string
   private defaultChain: string
+  private timeoutMs: number
+  private verbose: boolean
 
   constructor(config: OpenSeaClientConfig) {
     this.apiKey = config.apiKey
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL
     this.graphqlUrl = config.graphqlUrl ?? DEFAULT_GRAPHQL_URL
     this.defaultChain = config.chain ?? "ethereum"
+    this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS
+    this.verbose = config.verbose ?? false
   }
 
   async get<T>(path: string, params?: Record<string, unknown>): Promise<T> {
@@ -27,14 +32,23 @@ export class OpenSeaClient {
       }
     }
 
+    if (this.verbose) {
+      console.error(`[verbose] GET ${url.toString()}`)
+    }
+
     const response = await fetch(url.toString(), {
       method: "GET",
       headers: {
         Accept: "application/json",
         "x-api-key": this.apiKey,
       },
+      signal: AbortSignal.timeout(this.timeoutMs),
     })
 
+    if (this.verbose) {
+      console.error(`[verbose] ${response.status} ${response.statusText}`)
+    }
+
     if (!response.ok) {
       const body = await response.text()
       throw new OpenSeaAPIError(response.status, body, path)
@@ -43,20 +57,48 @@ export class OpenSeaClient {
     return response.json() as Promise<T>
   }
 
-  async post<T>(path: string): Promise<T> {
+  async post<T>(
+    path: string,
+    body?: Record<string, unknown>,
+    params?: Record<string, unknown>,
+  ): Promise<T> {
     const url = new URL(`${this.baseUrl}${path}`)
 
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value))
+        }
+      }
+    }
+
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "x-api-key": this.apiKey,
+    }
+
+    if (body) {
+      headers["Content-Type"] = "application/json"
+    }
+
+    if (this.verbose) {
+      console.error(`[verbose] POST ${url.toString()}`)
+    }
+
     const response = await fetch(url.toString(), {
       method: "POST",
-      headers: {
-        Accept: "application/json",
-        "x-api-key": this.apiKey,
-      },
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(this.timeoutMs),
     })
 
+    if (this.verbose) {
+      console.error(`[verbose] ${response.status} ${response.statusText}`)
+    }
+
     if (!response.ok) {
-      const body = await response.text()
-      throw new OpenSeaAPIError(response.status, body, path)
+      const text = await response.text()
+      throw new OpenSeaAPIError(response.status, text, path)
     }
 
     return response.json() as Promise<T>
@@ -66,6 +108,10 @@ export class OpenSeaClient {
     query: string,
     variables?: Record<string, unknown>,
   ): Promise<T> {
+    if (this.verbose) {
+      console.error(`[verbose] POST ${this.graphqlUrl}`)
+    }
+
     const response = await fetch(this.graphqlUrl, {
       method: "POST",
       headers: {
@@ -74,8 +120,13 @@ export class OpenSeaClient {
         "x-api-key": this.apiKey,
       },
       body: JSON.stringify({ query, variables }),
+      signal: AbortSignal.timeout(this.timeoutMs),
     })
 
+    if (this.verbose) {
+      console.error(`[verbose] ${response.status} ${response.statusText}`)
+    }
+
     if (!response.ok) {
       const body = await response.text()
       throw new OpenSeaAPIError(response.status, body, "graphql")

diff --git a/src/commands/collections.ts b/src/commands/collections.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import type {
   Chain,
   Collection,
@@ -57,7 +58,7 @@ export function collectionsCommand(
           order_by: options.orderBy as CollectionOrderBy | undefined,
           creator_username: options.creator,
           include_hidden: options.includeHidden,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))

diff --git a/src/commands/events.ts b/src/commands/events.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import type { AssetEvent } from "../types/index.js"
 
 export function eventsCommand(
@@ -36,12 +37,14 @@ export function eventsCommand(
           next?: string
         }>("/api/v2/events", {
           event_type: options.eventType,
-          after: options.after ? Number.parseInt(options.after, 10) : undefined,
+          after: options.after
+            ? parseIntOption(options.after, "--after")
+            : undefined,
           before: options.before
-            ? Number.parseInt(options.before, 10)
+            ? parseIntOption(options.before, "--before")
             : undefined,
           chain: options.chain,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -73,7 +76,7 @@ export function eventsCommand(
         }>(`/api/v2/events/accounts/${address}`, {
           event_type: options.eventType,
           chain: options.chain,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -102,7 +105,7 @@ export function eventsCommand(
           next?: string
         }>(`/api/v2/events/collection/${slug}`, {
           event_type: options.eventType,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -137,7 +140,7 @@ export function eventsCommand(
           `/api/v2/events/chain/${chain}/contract/${contract}/nfts/${tokenId}`,
           {
             event_type: options.eventType,
-            limit: Number.parseInt(options.limit, 10),
+            limit: parseIntOption(options.limit, "--limit"),
             next: options.next,
           },
         )

diff --git a/src/commands/listings.ts b/src/commands/listings.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import type { Listing } from "../types/index.js"
 
 export function listingsCommand(
@@ -22,7 +23,7 @@ export function listingsCommand(
           listings: Listing[]
           next?: string
         }>(`/api/v2/listings/collection/${collection}/all`, {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -42,7 +43,7 @@ export function listingsCommand(
           listings: Listing[]
           next?: string
         }>(`/api/v2/listings/collection/${collection}/best`, {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))

diff --git a/src/commands/nfts.ts b/src/commands/nfts.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import type { Contract, NFT } from "../types/index.js"
 
 export function nftsCommand(
@@ -34,7 +35,7 @@ export function nftsCommand(
       const result = await client.get<{ nfts: NFT[]; next?: string }>(
         `/api/v2/collection/${slug}/nfts`,
         {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         },
       )
@@ -58,7 +59,7 @@ export function nftsCommand(
         const result = await client.get<{ nfts: NFT[]; next?: string }>(
           `/api/v2/chain/${chain}/contract/${contract}/nfts`,
           {
-            limit: Number.parseInt(options.limit, 10),
+            limit: parseIntOption(options.limit, "--limit"),
             next: options.next,
           },
         )
@@ -83,7 +84,7 @@ export function nftsCommand(
         const result = await client.get<{ nfts: NFT[]; next?: string }>(
           `/api/v2/chain/${chain}/account/${address}/nfts`,
           {
-            limit: Number.parseInt(options.limit, 10),
+            limit: parseIntOption(options.limit, "--limit"),
             next: options.next,
           },
         )

diff --git a/src/commands/offers.ts b/src/commands/offers.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import type { Offer } from "../types/index.js"
 
 export function offersCommand(
@@ -22,7 +23,7 @@ export function offersCommand(
           offers: Offer[]
           next?: string
         }>(`/api/v2/offers/collection/${collection}/all`, {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -42,7 +43,7 @@ export function offersCommand(
           offers: Offer[]
           next?: string
         }>(`/api/v2/offers/collection/${collection}`, {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))
@@ -87,7 +88,7 @@ export function offersCommand(
         }>(`/api/v2/offers/collection/${collection}/traits`, {
           type: options.type,
           value: options.value,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next,
         })
         console.log(formatOutput(result, getFormat()))

diff --git a/src/commands/search.ts b/src/commands/search.ts
@@ -1,6 +1,7 @@
 import { Command } from "commander"
 import type { OpenSeaClient } from "../client.js"
 import { formatOutput } from "../output.js"
+import { parseIntOption } from "../parse.js"
 import {
   SEARCH_ACCOUNTS_QUERY,
   SEARCH_COLLECTIONS_QUERY,
@@ -35,7 +36,7 @@ export function searchCommand(
           collectionsByQuery: SearchCollectionResult[]
         }>(SEARCH_COLLECTIONS_QUERY, {
           query,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           chains: options.chains?.split(","),
         })
         console.log(formatOutput(result.collectionsByQuery, getFormat()))
@@ -60,7 +61,7 @@ export function searchCommand(
         }>(SEARCH_NFTS_QUERY, {
           query,
           collectionSlug: options.collection,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           chains: options.chains?.split(","),
         })
         console.log(formatOutput(result.itemsByQuery, getFormat()))
@@ -80,7 +81,7 @@ export function searchCommand(
           currenciesByQuery: SearchTokenResult[]
         }>(SEARCH_TOKENS_QUERY, {
           query,
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           chain: options.chain,
         })
         console.log(formatOutput(result.currenciesByQuery, getFormat()))
@@ -98,7 +99,7 @@ export function searchCommand(
         accountsByQuery: SearchAccountResult[]
       }>(SEARCH_ACCOUNTS_QUERY, {
         query,
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
       })
       console.log(formatOutput(result.accountsByQuery, getFormat()))
     })