@opensea/cli 0.2.1 → 0.4.0

package/dist/cli.js

@@ -6,16 +6,21 @@ import { Command as Command10 } from "commander";
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.opensea.io";
 var DEFAULT_GRAPHQL_URL = "https://gql.opensea.io/graphql";
+var DEFAULT_TIMEOUT_MS = 3e4;
 var OpenSeaClient = class {
   apiKey;
   baseUrl;
   graphqlUrl;
   defaultChain;
+  timeoutMs;
+  verbose;
   constructor(config) {
     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(path, params) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -26,35 +31,64 @@ var OpenSeaClient = class {
         }
       }
     }
+    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);
     }
     return response.json();
   }
-  async post(path) {
+  async post(path, body, params) {
     const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const headers = {
+      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) : void 0,
+      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();
   }
   async graphql(query, variables) {
+    if (this.verbose) {
+      console.error(`[verbose] POST ${this.graphqlUrl}`);
+    }
     const response = await fetch(this.graphqlUrl, {
       method: "POST",
       headers: {
@@ -62,8 +96,12 @@ var OpenSeaClient = class {
         Accept: "application/json",
         "x-api-key": this.apiKey
       },
-      body: JSON.stringify({ query, variables })
+      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");
@@ -98,11 +136,284 @@ var OpenSeaAPIError = class extends Error {
 // src/commands/accounts.ts
 import { Command } from "commander";
 
+// src/toon.ts
+var INDENT = "  ";
+var NUMERIC_RE = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+var LEADING_ZERO_RE = /^0\d+$/;
+var UNQUOTED_KEY_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+function escapeString(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+}
+function needsQuoting(value, delimiter) {
+  if (value === "") return true;
+  if (value !== value.trim()) return true;
+  if (value === "true" || value === "false" || value === "null") return true;
+  if (NUMERIC_RE.test(value) || LEADING_ZERO_RE.test(value)) return true;
+  if (/[:"\\[\]{}]/.test(value)) return true;
+  if (/[\n\r\t]/.test(value)) return true;
+  if (value.includes(delimiter)) return true;
+  if (value.startsWith("-")) return true;
+  return false;
+}
+function encodeKey(key) {
+  if (UNQUOTED_KEY_RE.test(key)) return key;
+  return `"${escapeString(key)}"`;
+}
+function encodePrimitive(value, delimiter) {
+  if (value === null) return "null";
+  if (value === void 0) return "null";
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") {
+    if (needsQuoting(value, delimiter)) {
+      return `"${escapeString(value)}"`;
+    }
+    return value;
+  }
+  return `"${escapeString(String(value))}"`;
+}
+function isPrimitive(value) {
+  return value === null || value === void 0 || typeof value === "boolean" || typeof value === "number" || typeof value === "string";
+}
+function isTabular(arr) {
+  if (arr.length === 0) return false;
+  const first = arr[0];
+  if (first === null || typeof first !== "object" || Array.isArray(first))
+    return false;
+  const keys = Object.keys(first).sort();
+  for (const item of arr) {
+    if (item === null || typeof item !== "object" || Array.isArray(item))
+      return false;
+    const itemKeys = Object.keys(item).sort();
+    if (itemKeys.length !== keys.length) return false;
+    for (let i = 0; i < keys.length; i++) {
+      if (itemKeys[i] !== keys[i]) return false;
+    }
+    for (const k of keys) {
+      if (!isPrimitive(item[k])) return false;
+    }
+  }
+  return true;
+}
+function isPrimitiveArray(arr) {
+  return arr.every(isPrimitive);
+}
+function encodeValue(value, depth, delimiter) {
+  if (isPrimitive(value)) {
+    return encodePrimitive(value, delimiter);
+  }
+  if (Array.isArray(value)) {
+    return encodeArray(value, depth, delimiter);
+  }
+  if (typeof value === "object" && value !== null) {
+    return encodeObject(value, depth, delimiter);
+  }
+  return encodePrimitive(value, delimiter);
+}
+function encodeObject(obj, depth, delimiter) {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) return "";
+  const lines = [];
+  const prefix = INDENT.repeat(depth);
+  for (const [key, value] of entries) {
+    const encodedKey = encodeKey(key);
+    if (isPrimitive(value)) {
+      lines.push(`${prefix}${encodedKey}: ${encodePrimitive(value, delimiter)}`);
+    } else if (Array.isArray(value)) {
+      lines.push(encodeArrayField(encodedKey, value, depth, delimiter));
+    } else if (typeof value === "object" && value !== null) {
+      const nested = value;
+      if (Object.keys(nested).length === 0) {
+        lines.push(`${prefix}${encodedKey}:`);
+      } else {
+        lines.push(`${prefix}${encodedKey}:`);
+        lines.push(encodeObject(nested, depth + 1, delimiter));
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function encodeArrayField(encodedKey, arr, depth, delimiter) {
+  const prefix = INDENT.repeat(depth);
+  if (arr.length === 0) {
+    return `${prefix}${encodedKey}[0]:`;
+  }
+  if (isPrimitiveArray(arr)) {
+    const values = arr.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+    return `${prefix}${encodedKey}[${arr.length}]: ${values}`;
+  }
+  if (isTabular(arr)) {
+    const firstObj = arr[0];
+    const fields = Object.keys(firstObj);
+    const fieldHeader = fields.map(encodeKey).join(delimiter);
+    const lines = [];
+    lines.push(`${prefix}${encodedKey}[${arr.length}]{${fieldHeader}}:`);
+    const rowPrefix = INDENT.repeat(depth + 1);
+    for (const item of arr) {
+      const obj = item;
+      const row = fields.map((f) => encodePrimitive(obj[f], delimiter)).join(delimiter);
+      lines.push(`${rowPrefix}${row}`);
+    }
+    return lines.join("\n");
+  }
+  return encodeExpandedList(encodedKey, arr, depth, delimiter);
+}
+function encodeExpandedList(encodedKey, arr, depth, delimiter) {
+  const prefix = INDENT.repeat(depth);
+  const itemPrefix = INDENT.repeat(depth + 1);
+  const lines = [];
+  lines.push(`${prefix}${encodedKey}[${arr.length}]:`);
+  for (const item of arr) {
+    if (isPrimitive(item)) {
+      lines.push(`${itemPrefix}- ${encodePrimitive(item, delimiter)}`);
+    } else if (Array.isArray(item)) {
+      if (isPrimitiveArray(item)) {
+        const values = item.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+        lines.push(`${itemPrefix}- [${item.length}]: ${values}`);
+      } else {
+        lines.push(`${itemPrefix}- [${item.length}]:`);
+        for (const inner of item) {
+          lines.push(encodeValue(inner, depth + 2, delimiter));
+        }
+      }
+    } else if (typeof item === "object" && item !== null) {
+      const obj = item;
+      const entries = Object.entries(obj);
+      if (entries.length === 0) {
+        lines.push(`${itemPrefix}-`);
+      } else {
+        const [firstKey, firstValue] = entries[0];
+        const ek = encodeKey(firstKey);
+        if (Array.isArray(firstValue)) {
+          const arrayLine = encodeArrayField(ek, firstValue, 0, delimiter);
+          lines.push(`${itemPrefix}- ${arrayLine.trimStart()}`);
+        } else if (isPrimitive(firstValue)) {
+          lines.push(
+            `${itemPrefix}- ${ek}: ${encodePrimitive(firstValue, delimiter)}`
+          );
+        } else {
+          lines.push(`${itemPrefix}- ${ek}:`);
+          lines.push(
+            encodeObject(
+              firstValue,
+              depth + 2,
+              delimiter
+            )
+          );
+        }
+        for (let i = 1; i < entries.length; i++) {
+          const [k, v] = entries[i];
+          const encodedK = encodeKey(k);
+          if (isPrimitive(v)) {
+            lines.push(
+              `${INDENT.repeat(depth + 2)}${encodedK}: ${encodePrimitive(v, delimiter)}`
+            );
+          } else if (Array.isArray(v)) {
+            lines.push(encodeArrayField(encodedK, v, depth + 2, delimiter));
+          } else if (typeof v === "object" && v !== null) {
+            lines.push(`${INDENT.repeat(depth + 2)}${encodedK}:`);
+            lines.push(
+              encodeObject(v, depth + 3, delimiter)
+            );
+          }
+        }
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function encodeArray(arr, depth, delimiter) {
+  const prefix = INDENT.repeat(depth);
+  if (arr.length === 0) {
+    return `${prefix}[0]:`;
+  }
+  if (isPrimitiveArray(arr)) {
+    const values = arr.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+    return `${prefix}[${arr.length}]: ${values}`;
+  }
+  if (isTabular(arr)) {
+    const firstObj = arr[0];
+    const fields = Object.keys(firstObj);
+    const fieldHeader = fields.map(encodeKey).join(delimiter);
+    const lines2 = [];
+    lines2.push(`${prefix}[${arr.length}]{${fieldHeader}}:`);
+    const rowPrefix = INDENT.repeat(depth + 1);
+    for (const item of arr) {
+      const obj = item;
+      const row = fields.map((f) => encodePrimitive(obj[f], delimiter)).join(delimiter);
+      lines2.push(`${rowPrefix}${row}`);
+    }
+    return lines2.join("\n");
+  }
+  const lines = [];
+  lines.push(`${prefix}[${arr.length}]:`);
+  const itemPrefix = INDENT.repeat(depth + 1);
+  for (const item of arr) {
+    if (isPrimitive(item)) {
+      lines.push(`${itemPrefix}- ${encodePrimitive(item, delimiter)}`);
+    } else if (Array.isArray(item)) {
+      if (isPrimitiveArray(item)) {
+        const values = item.map((v) => encodePrimitive(v, delimiter)).join(delimiter);
+        lines.push(`${itemPrefix}- [${item.length}]: ${values}`);
+      } else {
+        lines.push(`${itemPrefix}- [${item.length}]:`);
+      }
+    } else if (typeof item === "object" && item !== null) {
+      const obj = item;
+      const entries = Object.entries(obj);
+      if (entries.length > 0) {
+        const [firstKey, firstValue] = entries[0];
+        const ek = encodeKey(firstKey);
+        if (isPrimitive(firstValue)) {
+          lines.push(
+            `${itemPrefix}- ${ek}: ${encodePrimitive(firstValue, delimiter)}`
+          );
+        } else {
+          lines.push(`${itemPrefix}- ${ek}:`);
+          lines.push(encodeValue(firstValue, depth + 2, delimiter));
+        }
+        for (let i = 1; i < entries.length; i++) {
+          const [k, v] = entries[i];
+          const encodedK = encodeKey(k);
+          if (isPrimitive(v)) {
+            lines.push(
+              `${INDENT.repeat(depth + 2)}${encodedK}: ${encodePrimitive(v, delimiter)}`
+            );
+          } else if (Array.isArray(v)) {
+            lines.push(encodeArrayField(encodedK, v, depth + 2, delimiter));
+          } else if (typeof v === "object" && v !== null) {
+            lines.push(`${INDENT.repeat(depth + 2)}${encodedK}:`);
+            lines.push(
+              encodeObject(v, depth + 3, delimiter)
+            );
+          }
+        }
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function formatToon(data) {
+  if (isPrimitive(data)) {
+    return encodePrimitive(data, ",");
+  }
+  if (Array.isArray(data)) {
+    return encodeArray(data, 0, ",");
+  }
+  if (typeof data === "object" && data !== null) {
+    return encodeObject(data, 0, ",");
+  }
+  return String(data);
+}
+
 // src/output.ts
 function formatOutput(data, format) {
   if (format === "table") {
     return formatTable(data);
   }
+  if (format === "toon") {
+    return formatToon(data);
+  }
   return JSON.stringify(data, null, 2);
 }
 function formatTable(data) {
@@ -130,6 +441,7 @@ function formatTable(data) {
   }
   if (data && typeof data === "object") {
     const entries = Object.entries(data);
+    if (entries.length === 0) return "(empty)";
     const maxKeyLength = Math.max(...entries.map(([k]) => k.length));
     return entries.map(([key, value]) => {
       const displayValue = typeof value === "object" && value !== null ? JSON.stringify(value) : String(value ?? "");
@@ -152,6 +464,24 @@ function accountsCommand(getClient2, getFormat2) {
 
 // src/commands/collections.ts
 import { Command as Command2 } from "commander";
+
+// src/parse.ts
+function parseIntOption(value, name) {
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid value for ${name}: "${value}" is not an integer`);
+  }
+  return parsed;
+}
+function parseFloatOption(value, name) {
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid value for ${name}: "${value}" is not a number`);
+  }
+  return parsed;
+}
+
+// src/commands/collections.ts
 function collectionsCommand(getClient2, getFormat2) {
   const cmd = new Command2("collections").description(
     "Manage and query NFT collections"
@@ -172,7 +502,7 @@ function collectionsCommand(getClient2, getFormat2) {
         order_by: options.orderBy,
         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, getFormat2()));
@@ -207,10 +537,10 @@ function eventsCommand(getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.get("/api/v2/events", {
         event_type: options.eventType,
-        after: options.after ? Number.parseInt(options.after, 10) : void 0,
-        before: options.before ? Number.parseInt(options.before, 10) : void 0,
+        after: options.after ? parseIntOption(options.after, "--after") : void 0,
+        before: options.before ? parseIntOption(options.before, "--before") : void 0,
         chain: options.chain,
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       });
       console.log(formatOutput(result, getFormat2()));
@@ -222,7 +552,7 @@ function eventsCommand(getClient2, getFormat2) {
       const result = await client.get(`/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, getFormat2()));
@@ -233,7 +563,7 @@ function eventsCommand(getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.get(`/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, getFormat2()));
@@ -246,7 +576,7 @@ function eventsCommand(getClient2, getFormat2) {
         `/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
         }
       );
@@ -264,7 +594,7 @@ function listingsCommand(getClient2, getFormat2) {
     async (collection, options) => {
       const client = getClient2();
       const result = await client.get(`/api/v2/listings/collection/${collection}/all`, {
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       });
       console.log(formatOutput(result, getFormat2()));
@@ -274,7 +604,7 @@ function listingsCommand(getClient2, getFormat2) {
     async (collection, options) => {
       const client = getClient2();
       const result = await client.get(`/api/v2/listings/collection/${collection}/best`, {
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       });
       console.log(formatOutput(result, getFormat2()));
@@ -306,7 +636,7 @@ function nftsCommand(getClient2, getFormat2) {
     const result = await client.get(
       `/api/v2/collection/${slug}/nfts`,
       {
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       }
     );
@@ -318,7 +648,7 @@ function nftsCommand(getClient2, getFormat2) {
       const result = await client.get(
         `/api/v2/chain/${chain}/contract/${contract}/nfts`,
         {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next
         }
       );
@@ -331,7 +661,7 @@ function nftsCommand(getClient2, getFormat2) {
       const result = await client.get(
         `/api/v2/chain/${chain}/account/${address}/nfts`,
         {
-          limit: Number.parseInt(options.limit, 10),
+          limit: parseIntOption(options.limit, "--limit"),
           next: options.next
         }
       );
@@ -368,7 +698,7 @@ function offersCommand(getClient2, getFormat2) {
     async (collection, options) => {
       const client = getClient2();
       const result = await client.get(`/api/v2/offers/collection/${collection}/all`, {
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       });
       console.log(formatOutput(result, getFormat2()));
@@ -378,7 +708,7 @@ function offersCommand(getClient2, getFormat2) {
     async (collection, options) => {
       const client = getClient2();
       const result = await client.get(`/api/v2/offers/collection/${collection}`, {
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         next: options.next
       });
       console.log(formatOutput(result, getFormat2()));
@@ -397,7 +727,7 @@ function offersCommand(getClient2, getFormat2) {
       const result = await client.get(`/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, getFormat2()));
@@ -512,7 +842,7 @@ function searchCommand(getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.graphql(SEARCH_COLLECTIONS_QUERY, {
         query,
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         chains: options.chains?.split(",")
       });
       console.log(formatOutput(result.collectionsByQuery, getFormat2()));
@@ -524,7 +854,7 @@ function searchCommand(getClient2, getFormat2) {
       const result = await client.graphql(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, getFormat2()));
@@ -535,7 +865,7 @@ function searchCommand(getClient2, getFormat2) {
       const client = getClient2();
       const result = await client.graphql(SEARCH_TOKENS_QUERY, {
         query,
-        limit: Number.parseInt(options.limit, 10),
+        limit: parseIntOption(options.limit, "--limit"),
         chain: options.chain
       });
       console.log(formatOutput(result.currenciesByQuery, getFormat2()));
@@ -545,7 +875,7 @@ function searchCommand(getClient2, getFormat2) {
     const client = getClient2();
     const result = await client.graphql(SEARCH_ACCOUNTS_QUERY, {
       query,
-      limit: Number.parseInt(options.limit, 10)
+      limit: parseIntOption(options.limit, "--limit")
     });
     console.log(formatOutput(result.accountsByQuery, getFormat2()));
   });
@@ -584,7 +914,7 @@ function swapsCommand(getClient2, getFormat2) {
           to_address: options.toAddress,
           quantity: options.quantity,
           address: options.address,
-          slippage: options.slippage ? Number.parseFloat(options.slippage) : void 0,
+          slippage: options.slippage ? parseFloatOption(options.slippage, "--slippage") : void 0,
           recipient: options.recipient
         }
       );
@@ -600,29 +930,31 @@ function tokensCommand(getClient2, getFormat2) {
   const cmd = new Command9("tokens").description(
     "Query trending tokens, top tokens, and token details"
   );
-  cmd.command("trending").description("Get trending tokens based on OpenSea's trending score").option("--chains <chains>", "Comma-separated list of chains to filter by").option("--limit <limit>", "Number of results (max 100)", "20").option("--cursor <cursor>", "Pagination cursor").action(
+  cmd.command("trending").description("Get trending tokens based on OpenSea's trending score").option("--chains <chains>", "Comma-separated list of chains to filter by").option("--limit <limit>", "Number of results (max 100)", "20").option("--next <cursor>", "Pagination cursor").action(
     async (options) => {
       const client = getClient2();
       const result = await client.get(
         "/api/v2/tokens/trending",
         {
           chains: options.chains,
-          limit: Number.parseInt(options.limit, 10),
-          cursor: options.cursor
+          limit: parseIntOption(options.limit, "--limit"),
+          // Tokens API uses "cursor" instead of "next" as the query param
+          cursor: options.next
         }
       );
       console.log(formatOutput(result, getFormat2()));
     }
   );
-  cmd.command("top").description("Get top tokens ranked by 24-hour trading volume").option("--chains <chains>", "Comma-separated list of chains to filter by").option("--limit <limit>", "Number of results (max 100)", "20").option("--cursor <cursor>", "Pagination cursor").action(
+  cmd.command("top").description("Get top tokens ranked by 24-hour trading volume").option("--chains <chains>", "Comma-separated list of chains to filter by").option("--limit <limit>", "Number of results (max 100)", "20").option("--next <cursor>", "Pagination cursor").action(
     async (options) => {
       const client = getClient2();
       const result = await client.get(
         "/api/v2/tokens/top",
         {
           chains: options.chains,
-          limit: Number.parseInt(options.limit, 10),
-          cursor: options.cursor
+          limit: parseIntOption(options.limit, "--limit"),
+          // Tokens API uses "cursor" instead of "next" as the query param
+          cursor: options.next
         }
       );
       console.log(formatOutput(result, getFormat2()));
@@ -650,7 +982,7 @@ var BANNER = `
         |_|
 `;
 var program = new Command10();
-program.name("opensea").description("OpenSea CLI - Query the OpenSea API from the command line").version(process.env.npm_package_version ?? "0.0.0").addHelpText("before", BANNER).option("--api-key <key>", "OpenSea API key (or set OPENSEA_API_KEY env var)").option("--chain <chain>", "Default chain", "ethereum").option("--format <format>", "Output format (json or table)", "json").option("--base-url <url>", "API base URL");
+program.name("opensea").description("OpenSea CLI - Query the OpenSea API from the command line").version(process.env.npm_package_version ?? "0.0.0").addHelpText("before", BANNER).option("--api-key <key>", "OpenSea API key (or set OPENSEA_API_KEY env var)").option("--chain <chain>", "Default chain", "ethereum").option("--format <format>", "Output format (json, table, or toon)", "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() {
   const opts = program.opts();
   const apiKey = opts.apiKey ?? process.env.OPENSEA_API_KEY;
@@ -663,12 +995,16 @@ function getClient() {
   return new OpenSeaClient({
     apiKey,
     chain: opts.chain,
-    baseUrl: opts.baseUrl
+    baseUrl: opts.baseUrl,
+    timeout: parseIntOption(opts.timeout, "--timeout"),
+    verbose: opts.verbose
   });
 }
 function getFormat() {
   const opts = program.opts();
-  return opts.format === "table" ? "table" : "json";
+  if (opts.format === "table") return "table";
+  if (opts.format === "toon") return "toon";
+  return "json";
 }
 program.addCommand(collectionsCommand(getClient, getFormat));
 program.addCommand(nftsCommand(getClient, getFormat));
@@ -698,7 +1034,18 @@ async function main() {
       );
       process.exit(1);
     }
-    throw error;
+    const label = error instanceof TypeError ? "Network Error" : error.name;
+    console.error(
+      JSON.stringify(
+        {
+          error: label,
+          message: error.message
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
   }
 }
 main();