@spectratools/etherscan-cli 0.1.0 → 0.1.2

package/dist/cli.js

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { Cli as Cli7 } from "incur";
 
 // src/commands/account.ts
 import {
-  apiKeyAuth,
   checksumAddress,
   createRateLimiter as createRateLimiter2,
   formatTimestamp,
   weiToEth,
   withRateLimit as withRateLimit2
 } from "@spectratools/cli-shared";
-import { Cli, z } from "incur";
+import { Cli, z as z3 } from "incur";
 
 // src/api.ts
 import {
@@ -22,14 +22,49 @@ import {
   withRateLimit,
   withRetry
 } from "@spectratools/cli-shared";
+import { z } from "incur";
 var DEFAULT_BASE_URL = "https://api.etherscan.io/v2/api";
 var RETRY_OPTIONS = { maxRetries: 3, baseMs: 500, maxMs: 1e4 };
+var etherscanResponseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.unknown()
+});
+var proxyResponseSchema = z.object({
+  jsonrpc: z.string(),
+  id: z.union([z.number(), z.string()]),
+  result: z.unknown()
+});
 var EtherscanError = class extends Error {
-  constructor(message) {
+  constructor(message, details) {
     super(message);
+    this.details = details;
     this.name = "EtherscanError";
   }
 };
+var EtherscanValidationError = class extends EtherscanError {
+  constructor(debug) {
+    super("Etherscan response validation failed", {
+      code: "INVALID_API_RESPONSE",
+      mode: debug.mode,
+      params: debug.params,
+      issues: debug.issues,
+      response: debug.response
+    });
+    this.debug = debug;
+    this.name = "EtherscanValidationError";
+  }
+};
+function parseWithSchema(schema, data, mode, params) {
+  const parsed = schema.safeParse(data);
+  if (parsed.success) return parsed.data;
+  throw new EtherscanValidationError({
+    mode,
+    params,
+    issues: parsed.error.issues,
+    response: data
+  });
+}
 function createEtherscanClient(apiKey, baseUrl = DEFAULT_BASE_URL) {
   const http = createHttpClient({ baseUrl });
   const acquire = createRateLimiter({ requestsPerSecond: 5 });
@@ -44,21 +79,33 @@ function createEtherscanClient(apiKey, baseUrl = DEFAULT_BASE_URL) {
       RETRY_OPTIONS
     );
   }
-  async function call(params) {
-    const response = await request(params);
+  async function call(params, resultSchema) {
+    const rawResponse = await request(params);
+    const response = parseWithSchema(etherscanResponseSchema, rawResponse, "rest", params);
     if (response.status === "0") {
       const msg = typeof response.result === "string" ? response.result : response.message;
-      throw new EtherscanError(msg);
+      throw new EtherscanError(msg, {
+        code: "ETHERSCAN_API_ERROR",
+        params,
+        response
+      });
     }
-    return response.result;
+    return parseWithSchema(resultSchema, response.result, "rest", params);
   }
-  async function callProxy(params) {
-    const response = await request(params);
-    return response.result;
+  async function callProxy(params, resultSchema) {
+    const rawResponse = await request(params);
+    const response = parseWithSchema(proxyResponseSchema, rawResponse, "proxy", params);
+    return parseWithSchema(resultSchema, response.result, "proxy", params);
   }
   return { call, callProxy };
 }
 
+// src/auth.ts
+import { z as z2 } from "incur";
+var etherscanEnv = z2.object({
+  ETHERSCAN_API_KEY: z2.string().describe("Etherscan V2 API key")
+});
+
 // src/chains.ts
 var CHAIN_IDS = {
   abstract: 2741,
@@ -91,7 +138,28 @@ function resolveChainId(chain) {
 
 // src/commands/account.ts
 var rateLimiter = createRateLimiter2({ requestsPerSecond: 5 });
-var chainOption = z.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption = z3.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var txListItemSchema = z3.object({
+  hash: z3.string(),
+  from: z3.string(),
+  to: z3.string(),
+  value: z3.string(),
+  timeStamp: z3.string(),
+  blockNumber: z3.string(),
+  isError: z3.string(),
+  gasUsed: z3.string()
+});
+var tokenTxItemSchema = z3.object({
+  hash: z3.string(),
+  from: z3.string(),
+  to: z3.string(),
+  value: z3.string(),
+  tokenName: z3.string(),
+  tokenSymbol: z3.string(),
+  tokenDecimal: z3.string(),
+  timeStamp: z3.string(),
+  contractAddress: z3.string()
+});
 function normalizeAddress(address) {
   try {
     return checksumAddress(address);
@@ -100,29 +168,46 @@ function normalizeAddress(address) {
   }
 }
 var accountCli = Cli.create("account", {
-  description: "Query account balances, transactions, and token transfers"
+  description: "Query account balances, transactions, and token transfers."
 });
 accountCli.command("balance", {
-  description: "Get the ETH balance of an address",
-  args: z.object({
-    address: z.string().describe("Ethereum address")
+  description: "Get the native-token balance of an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
   }),
-  options: z.object({
+  options: z3.object({
     chain: chainOption
   }),
+  env: etherscanEnv,
+  output: z3.object({
+    address: z3.string(),
+    wei: z3.string(),
+    eth: z3.string(),
+    chain: z3.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "abstract" },
+      description: "Get ETH balance on Abstract"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
     const client = createEtherscanClient(apiKey);
     const wei = await withRateLimit2(
-      () => client.call({
-        chainid: chainId,
-        module: "account",
-        action: "balance",
-        address,
-        tag: "latest"
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "balance",
+          address,
+          tag: "latest"
+        },
+        z3.string()
+      ),
       rateLimiter
     );
     return c.ok(
@@ -143,35 +228,64 @@ accountCli.command("balance", {
   }
 });
 accountCli.command("txlist", {
-  description: "List normal transactions for an address",
-  args: z.object({
-    address: z.string().describe("Ethereum address")
-  }),
-  options: z.object({
-    startblock: z.number().optional().default(0).describe("Start block number"),
-    endblock: z.string().optional().default("latest").describe("End block number"),
-    page: z.number().optional().default(1).describe("Page number"),
-    offset: z.number().optional().default(10).describe("Number of results per page"),
-    sort: z.string().optional().default("asc").describe("Sort order (asc or desc)"),
+  description: "List normal transactions for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
+  }),
+  options: z3.object({
+    startblock: z3.number().optional().default(0).describe("Start block number"),
+    endblock: z3.string().optional().default("latest").describe("End block number"),
+    page: z3.number().optional().default(1).describe("Page number"),
+    offset: z3.number().optional().default(10).describe("Number of results per page"),
+    sort: z3.string().optional().default("asc").describe("Sort order (asc or desc)"),
     chain: chainOption
   }),
+  env: etherscanEnv,
+  output: z3.object({
+    address: z3.string(),
+    chain: z3.string(),
+    count: z3.number(),
+    transactions: z3.array(
+      z3.object({
+        hash: z3.string(),
+        from: z3.string(),
+        to: z3.string(),
+        value: z3.string(),
+        eth: z3.string(),
+        timestamp: z3.string(),
+        block: z3.string(),
+        status: z3.string(),
+        gasUsed: z3.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "ethereum", sort: "desc", offset: 5 },
+      description: "List most recent transactions for an address"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
     const client = createEtherscanClient(apiKey);
     const txs = await withRateLimit2(
-      () => client.call({
-        chainid: chainId,
-        module: "account",
-        action: "txlist",
-        address,
-        startblock: c.options.startblock,
-        endblock: c.options.endblock,
-        page: c.options.page,
-        offset: c.options.offset,
-        sort: c.options.sort
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "txlist",
+          address,
+          startblock: c.options.startblock,
+          endblock: c.options.endblock,
+          page: c.options.page,
+          offset: c.options.offset,
+          sort: c.options.sort
+        },
+        z3.array(txListItemSchema)
+      ),
       rateLimiter
     );
     const formatted = txs.map((tx) => ({
@@ -203,31 +317,60 @@ accountCli.command("txlist", {
   }
 });
 accountCli.command("tokentx", {
-  description: "List ERC-20 token transfers for an address",
-  args: z.object({
-    address: z.string().describe("Ethereum address")
-  }),
-  options: z.object({
-    contractaddress: z.string().optional().describe("Filter by token contract address"),
-    page: z.number().optional().default(1).describe("Page number"),
-    offset: z.number().optional().default(20).describe("Results per page"),
+  description: "List ERC-20 token transfers for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
+  }),
+  options: z3.object({
+    contractaddress: z3.string().optional().describe("Filter by token contract address"),
+    page: z3.number().optional().default(1).describe("Page number"),
+    offset: z3.number().optional().default(20).describe("Results per page"),
     chain: chainOption
   }),
+  env: etherscanEnv,
+  output: z3.object({
+    address: z3.string(),
+    chain: z3.string(),
+    count: z3.number(),
+    transfers: z3.array(
+      z3.object({
+        hash: z3.string(),
+        from: z3.string(),
+        to: z3.string(),
+        value: z3.string(),
+        token: z3.string(),
+        tokenName: z3.string(),
+        decimals: z3.string(),
+        timestamp: z3.string(),
+        contract: z3.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "base", offset: 10 },
+      description: "List recent ERC-20 transfers for an address"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
     const client = createEtherscanClient(apiKey);
     const transfers = await withRateLimit2(
-      () => client.call({
-        chainid: chainId,
-        module: "account",
-        action: "tokentx",
-        address,
-        contractaddress: c.options.contractaddress,
-        page: c.options.page,
-        offset: c.options.offset
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "tokentx",
+          address,
+          contractaddress: c.options.contractaddress,
+          page: c.options.page,
+          offset: c.options.offset
+        },
+        z3.array(tokenTxItemSchema)
+      ),
       rateLimiter
     );
     const formatted = transfers.map((tx) => ({
@@ -258,29 +401,46 @@ accountCli.command("tokentx", {
   }
 });
 accountCli.command("tokenbalance", {
-  description: "Get ERC-20 token balance for an address",
-  args: z.object({
-    address: z.string().describe("Ethereum address")
+  description: "Get ERC-20 token balance for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
   }),
-  options: z.object({
-    contractaddress: z.string().describe("Token contract address"),
+  options: z3.object({
+    contractaddress: z3.string().describe("Token contract address"),
     chain: chainOption
   }),
+  env: etherscanEnv,
+  output: z3.object({
+    address: z3.string(),
+    contract: z3.string(),
+    balance: z3.string(),
+    chain: z3.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", chain: "ethereum" },
+      description: "Get token balance for a wallet + token pair"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = normalizeAddress(c.args.address);
     const contract = normalizeAddress(c.options.contractaddress);
     const client = createEtherscanClient(apiKey);
     const balance = await withRateLimit2(
-      () => client.call({
-        chainid: chainId,
-        module: "account",
-        action: "tokenbalance",
-        address,
-        contractaddress: contract,
-        tag: "latest"
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "tokenbalance",
+          address,
+          contractaddress: contract,
+          tag: "latest"
+        },
+        z3.string()
+      ),
       rateLimiter
     );
     return c.ok(
@@ -301,38 +461,66 @@ accountCli.command("tokenbalance", {
 });
 
 // src/commands/contract.ts
-import {
-  apiKeyAuth as apiKeyAuth2,
-  checksumAddress as checksumAddress2,
-  createRateLimiter as createRateLimiter3,
-  withRateLimit as withRateLimit3
-} from "@spectratools/cli-shared";
-import { Cli as Cli2, z as z2 } from "incur";
+import { checksumAddress as checksumAddress2, createRateLimiter as createRateLimiter3, withRateLimit as withRateLimit3 } from "@spectratools/cli-shared";
+import { Cli as Cli2, z as z4 } from "incur";
 var rateLimiter2 = createRateLimiter3({ requestsPerSecond: 5 });
-var chainOption2 = z2.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption2 = z4.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
 var contractCli = Cli2.create("contract", {
-  description: "Query contract ABI, source code, and deployment info"
+  description: "Query contract ABI, source code, and deployment metadata."
+});
+var sourceResultSchema = z4.object({
+  SourceCode: z4.string(),
+  ABI: z4.string(),
+  ContractName: z4.string(),
+  CompilerVersion: z4.string(),
+  OptimizationUsed: z4.string(),
+  Runs: z4.string(),
+  ConstructorArguments: z4.string(),
+  LicenseType: z4.string(),
+  Proxy: z4.string(),
+  Implementation: z4.string()
+});
+var creationResultSchema = z4.object({
+  contractAddress: z4.string(),
+  contractCreator: z4.string(),
+  txHash: z4.string()
 });
 contractCli.command("abi", {
-  description: "Get the ABI for a verified contract",
-  args: z2.object({
-    address: z2.string().describe("Contract address")
+  description: "Get the ABI for a verified contract.",
+  args: z4.object({
+    address: z4.string().describe("Contract address")
   }),
-  options: z2.object({
+  options: z4.object({
     chain: chainOption2
   }),
+  env: etherscanEnv,
+  output: z4.object({
+    address: z4.string(),
+    chain: z4.string(),
+    abi: z4.array(z4.unknown())
+  }),
+  examples: [
+    {
+      args: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Fetch ABI for a verified ERC-20 contract"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth2("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
     const client = createEtherscanClient(apiKey);
     const abi = await withRateLimit3(
-      () => client.call({
-        chainid: chainId,
-        module: "contract",
-        action: "getabi",
-        address
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "contract",
+          action: "getabi",
+          address
+        },
+        z4.string()
+      ),
       rateLimiter2
     );
     return c.ok(
@@ -352,25 +540,49 @@ contractCli.command("abi", {
   }
 });
 contractCli.command("source", {
-  description: "Get verified source code for a contract",
-  args: z2.object({
-    address: z2.string().describe("Contract address")
+  description: "Get verified source code for a contract.",
+  args: z4.object({
+    address: z4.string().describe("Contract address")
   }),
-  options: z2.object({
+  options: z4.object({
     chain: chainOption2
   }),
+  env: etherscanEnv,
+  output: z4.object({
+    address: z4.string(),
+    chain: z4.string(),
+    name: z4.string(),
+    compiler: z4.string(),
+    optimized: z4.boolean(),
+    runs: z4.string(),
+    license: z4.string(),
+    proxy: z4.boolean(),
+    implementation: z4.string().optional(),
+    sourceCode: z4.string(),
+    constructorArguments: z4.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Fetch verified source code metadata"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth2("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
     const client = createEtherscanClient(apiKey);
     const results = await withRateLimit3(
-      () => client.call({
-        chainid: chainId,
-        module: "contract",
-        action: "getsourcecode",
-        address
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "contract",
+          action: "getsourcecode",
+          address
+        },
+        z4.array(sourceResultSchema)
+      ),
       rateLimiter2
     );
     const result = results[0];
@@ -406,25 +618,42 @@ contractCli.command("source", {
   }
 });
 contractCli.command("creation", {
-  description: "Get the creation transaction for a contract",
-  args: z2.object({
-    address: z2.string().describe("Contract address")
+  description: "Get the deployment transaction and creator for a contract.",
+  args: z4.object({
+    address: z4.string().describe("Contract address")
   }),
-  options: z2.object({
+  options: z4.object({
     chain: chainOption2
   }),
+  env: etherscanEnv,
+  output: z4.object({
+    address: z4.string(),
+    creator: z4.string(),
+    txHash: z4.string(),
+    chain: z4.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Find deployment tx for a contract"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth2("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress2(c.args.address);
     const client = createEtherscanClient(apiKey);
     const results = await withRateLimit3(
-      () => client.call({
-        chainid: chainId,
-        module: "contract",
-        action: "getcontractcreation",
-        contractaddresses: address
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "contract",
+          action: "getcontractcreation",
+          contractaddresses: address
+        },
+        z4.array(creationResultSchema)
+      ),
       rateLimiter2
     );
     const result = results[0];
@@ -454,28 +683,50 @@ contractCli.command("creation", {
 });
 
 // src/commands/gas.ts
-import { apiKeyAuth as apiKeyAuth3, createRateLimiter as createRateLimiter4, withRateLimit as withRateLimit4 } from "@spectratools/cli-shared";
-import { Cli as Cli3, z as z3 } from "incur";
+import { createRateLimiter as createRateLimiter4, withRateLimit as withRateLimit4 } from "@spectratools/cli-shared";
+import { Cli as Cli3, z as z5 } from "incur";
 var rateLimiter3 = createRateLimiter4({ requestsPerSecond: 5 });
-var chainOption3 = z3.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption3 = z5.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
 var gasCli = Cli3.create("gas", {
-  description: "Query gas oracle and estimate gas costs"
+  description: "Query gas oracle data and estimate confirmation latency."
+});
+var gasOracleSchema = z5.object({
+  LastBlock: z5.string(),
+  SafeGasPrice: z5.string(),
+  ProposeGasPrice: z5.string(),
+  FastGasPrice: z5.string(),
+  suggestBaseFee: z5.string(),
+  gasUsedRatio: z5.string()
 });
 gasCli.command("oracle", {
-  description: "Get current gas price recommendations",
-  options: z3.object({
+  description: "Get current gas price recommendations.",
+  options: z5.object({
     chain: chainOption3
   }),
+  env: etherscanEnv,
+  output: z5.object({
+    chain: z5.string(),
+    lastBlock: z5.string(),
+    slow: z5.string(),
+    standard: z5.string(),
+    fast: z5.string(),
+    baseFee: z5.string(),
+    gasUsedRatio: z5.string()
+  }),
+  examples: [{ options: { chain: "abstract" }, description: "Get gas oracle on Abstract" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth3("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const oracle = await withRateLimit4(
-      () => client.call({
-        chainid: chainId,
-        module: "gastracker",
-        action: "gasoracle"
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "gastracker",
+          action: "gasoracle"
+        },
+        gasOracleSchema
+      ),
       rateLimiter3
     );
     return c.ok(
@@ -503,22 +754,37 @@ gasCli.command("oracle", {
   }
 });
 gasCli.command("estimate", {
-  description: "Estimate gas cost in wei for a given gas price",
-  options: z3.object({
-    gasprice: z3.string().describe("Gas price in wei"),
+  description: "Estimate confirmation time in seconds for a gas price (wei).",
+  options: z5.object({
+    gasprice: z5.string().describe("Gas price in wei"),
     chain: chainOption3
   }),
+  env: etherscanEnv,
+  output: z5.object({
+    chain: z5.string(),
+    gasprice: z5.string(),
+    estimatedSeconds: z5.string()
+  }),
+  examples: [
+    {
+      options: { gasprice: "1000000000", chain: "ethereum" },
+      description: "Estimate confirmation time at 1 gwei"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth3("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const estimate = await withRateLimit4(
-      () => client.call({
-        chainid: chainId,
-        module: "gastracker",
-        action: "gasestimate",
-        gasprice: c.options.gasprice
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "gastracker",
+          action: "gasestimate",
+          gasprice: c.options.gasprice
+        },
+        z5.string()
+      ),
       rateLimiter3
     );
     return c.ok(
@@ -542,28 +808,46 @@ gasCli.command("estimate", {
 });
 
 // src/commands/stats.ts
-import { apiKeyAuth as apiKeyAuth4, createRateLimiter as createRateLimiter5, withRateLimit as withRateLimit5 } from "@spectratools/cli-shared";
-import { Cli as Cli4, z as z4 } from "incur";
+import { createRateLimiter as createRateLimiter5, withRateLimit as withRateLimit5 } from "@spectratools/cli-shared";
+import { Cli as Cli4, z as z6 } from "incur";
 var rateLimiter4 = createRateLimiter5({ requestsPerSecond: 5 });
-var chainOption4 = z4.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption4 = z6.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
 var statsCli = Cli4.create("stats", {
-  description: "Query ETH price and supply statistics"
+  description: "Query ETH price and total supply statistics."
+});
+var ethPriceSchema = z6.object({
+  ethbtc: z6.string(),
+  ethbtc_timestamp: z6.string(),
+  ethusd: z6.string(),
+  ethusd_timestamp: z6.string()
 });
 statsCli.command("ethprice", {
-  description: "Get the latest ETH price in USD and BTC",
-  options: z4.object({
+  description: "Get latest ETH price in USD and BTC.",
+  options: z6.object({
     chain: chainOption4
   }),
+  env: etherscanEnv,
+  output: z6.object({
+    chain: z6.string(),
+    usd: z6.string(),
+    btc: z6.string(),
+    usdTimestamp: z6.string(),
+    btcTimestamp: z6.string()
+  }),
+  examples: [{ options: { chain: "ethereum" }, description: "Get ETH spot price on Ethereum" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth4("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const price = await withRateLimit5(
-      () => client.call({
-        chainid: chainId,
-        module: "stats",
-        action: "ethprice"
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "ethprice"
+        },
+        ethPriceSchema
+      ),
       rateLimiter4
     );
     return c.ok(
@@ -588,20 +872,29 @@ statsCli.command("ethprice", {
   }
 });
 statsCli.command("ethsupply", {
-  description: "Get the total supply of ETH",
-  options: z4.object({
+  description: "Get total ETH supply in wei.",
+  options: z6.object({
     chain: chainOption4
   }),
+  env: etherscanEnv,
+  output: z6.object({
+    chain: z6.string(),
+    totalSupplyWei: z6.string()
+  }),
+  examples: [{ options: { chain: "ethereum" }, description: "Get total ETH supply" }],
   async run(c) {
-    const { apiKey } = apiKeyAuth4("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const supply = await withRateLimit5(
-      () => client.call({
-        chainid: chainId,
-        module: "stats",
-        action: "ethsupply"
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "ethsupply"
+        },
+        z6.string()
+      ),
       rateLimiter4
     );
     return c.ok(
@@ -624,38 +917,85 @@ statsCli.command("ethsupply", {
 });
 
 // src/commands/token.ts
-import {
-  apiKeyAuth as apiKeyAuth5,
-  checksumAddress as checksumAddress3,
-  createRateLimiter as createRateLimiter6,
-  withRateLimit as withRateLimit6
-} from "@spectratools/cli-shared";
-import { Cli as Cli5, z as z5 } from "incur";
+import { checksumAddress as checksumAddress3, createRateLimiter as createRateLimiter6, withRateLimit as withRateLimit6 } from "@spectratools/cli-shared";
+import { Cli as Cli5, z as z7 } from "incur";
 var rateLimiter5 = createRateLimiter6({ requestsPerSecond: 5 });
-var chainOption5 = z5.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption5 = z7.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
 var tokenCli = Cli5.create("token", {
-  description: "Query token info, holders, and supply"
+  description: "Query token metadata, holders, and supply."
+});
+var tokenInfoSchema = z7.object({
+  contractAddress: z7.string(),
+  tokenName: z7.string(),
+  symbol: z7.string(),
+  divisor: z7.string(),
+  tokenType: z7.string(),
+  totalSupply: z7.string(),
+  blueCheckmark: z7.string(),
+  description: z7.string(),
+  website: z7.string(),
+  email: z7.string(),
+  blog: z7.string(),
+  reddit: z7.string(),
+  slack: z7.string(),
+  facebook: z7.string(),
+  twitter: z7.string(),
+  bitcointalk: z7.string(),
+  github: z7.string(),
+  telegram: z7.string(),
+  wechat: z7.string(),
+  linkedin: z7.string(),
+  discord: z7.string(),
+  whitepaper: z7.string(),
+  tokenPriceUSD: z7.string()
+});
+var holderEntrySchema = z7.object({
+  TokenHolderAddress: z7.string(),
+  TokenHolderQuantity: z7.string()
 });
 tokenCli.command("info", {
-  description: "Get information about a token contract",
-  args: z5.object({
-    contractaddress: z5.string().describe("Token contract address")
+  description: "Get metadata for a token contract.",
+  args: z7.object({
+    contractaddress: z7.string().describe("Token contract address")
   }),
-  options: z5.object({
+  options: z7.object({
     chain: chainOption5
   }),
+  env: etherscanEnv,
+  output: z7.object({
+    address: z7.string(),
+    chain: z7.string(),
+    name: z7.string(),
+    symbol: z7.string(),
+    type: z7.string(),
+    totalSupply: z7.string(),
+    decimals: z7.string(),
+    priceUsd: z7.string().optional(),
+    website: z7.string().optional(),
+    description: z7.string().optional()
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Get token metadata for USDC"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
     const results = await withRateLimit6(
-      () => client.call({
-        chainid: chainId,
-        module: "token",
-        action: "tokeninfo",
-        contractaddress: address
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "token",
+          action: "tokeninfo",
+          contractaddress: address
+        },
+        z7.array(tokenInfoSchema)
+      ),
       rateLimiter5
     );
     const info = results[0];
@@ -695,29 +1035,52 @@ tokenCli.command("info", {
   }
 });
 tokenCli.command("holders", {
-  description: "List top token holders",
-  args: z5.object({
-    contractaddress: z5.string().describe("Token contract address")
+  description: "List top token holders.",
+  args: z7.object({
+    contractaddress: z7.string().describe("Token contract address")
   }),
-  options: z5.object({
-    page: z5.number().optional().default(1).describe("Page number"),
-    offset: z5.number().optional().default(10).describe("Results per page"),
+  options: z7.object({
+    page: z7.number().optional().default(1).describe("Page number"),
+    offset: z7.number().optional().default(10).describe("Results per page"),
     chain: chainOption5
   }),
+  env: etherscanEnv,
+  output: z7.object({
+    contractAddress: z7.string(),
+    chain: z7.string(),
+    count: z7.number(),
+    holders: z7.array(
+      z7.object({
+        rank: z7.number(),
+        address: z7.string(),
+        quantity: z7.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { page: 1, offset: 20, chain: "ethereum" },
+      description: "List top 20 holders for a token"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
     const holders = await withRateLimit6(
-      () => client.call({
-        chainid: chainId,
-        module: "token",
-        action: "tokenholderlist",
-        contractaddress: address,
-        page: c.options.page,
-        offset: c.options.offset
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "token",
+          action: "tokenholderlist",
+          contractaddress: address,
+          page: c.options.page,
+          offset: c.options.offset
+        },
+        z7.array(holderEntrySchema)
+      ),
       rateLimiter5
     );
     const formatted = holders.map((h, i) => ({
@@ -747,25 +1110,41 @@ tokenCli.command("holders", {
   }
 });
 tokenCli.command("supply", {
-  description: "Get the total supply of a token",
-  args: z5.object({
-    contractaddress: z5.string().describe("Token contract address")
+  description: "Get total token supply.",
+  args: z7.object({
+    contractaddress: z7.string().describe("Token contract address")
   }),
-  options: z5.object({
+  options: z7.object({
     chain: chainOption5
   }),
+  env: etherscanEnv,
+  output: z7.object({
+    contractAddress: z7.string(),
+    chain: z7.string(),
+    totalSupply: z7.string()
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Get total supply for a token"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const address = checksumAddress3(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
     const supply = await withRateLimit6(
-      () => client.call({
-        chainid: chainId,
-        module: "stats",
-        action: "tokensupply",
-        contractaddress: address
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "tokensupply",
+          contractaddress: address
+        },
+        z7.string()
+      ),
       rateLimiter5
     );
     return c.ok(
@@ -786,32 +1165,82 @@ tokenCli.command("supply", {
 });
 
 // src/commands/tx.ts
-import { apiKeyAuth as apiKeyAuth6, createRateLimiter as createRateLimiter7, withRateLimit as withRateLimit7 } from "@spectratools/cli-shared";
-import { Cli as Cli6, z as z6 } from "incur";
+import { createRateLimiter as createRateLimiter7, withRateLimit as withRateLimit7 } from "@spectratools/cli-shared";
+import { Cli as Cli6, z as z8 } from "incur";
 var rateLimiter6 = createRateLimiter7({ requestsPerSecond: 5 });
-var chainOption6 = z6.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var chainOption6 = z8.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
 var txCli = Cli6.create("tx", {
-  description: "Query transaction details, receipts, and status"
+  description: "Query transaction details, receipts, and execution status."
+});
+var transactionInfoSchema = z8.object({
+  hash: z8.string(),
+  from: z8.string(),
+  to: z8.string().nullable(),
+  value: z8.string(),
+  gas: z8.string(),
+  gasPrice: z8.string(),
+  nonce: z8.string(),
+  blockNumber: z8.string(),
+  blockHash: z8.string(),
+  input: z8.string()
+});
+var transactionReceiptSchema = z8.object({
+  transactionHash: z8.string(),
+  blockNumber: z8.string(),
+  blockHash: z8.string(),
+  from: z8.string(),
+  to: z8.string().nullable(),
+  status: z8.string(),
+  gasUsed: z8.string(),
+  cumulativeGasUsed: z8.string(),
+  contractAddress: z8.string().nullable(),
+  logs: z8.array(z8.unknown())
+});
+var txStatusSchema = z8.object({
+  status: z8.string(),
+  errDescription: z8.string()
 });
 txCli.command("info", {
-  description: "Get transaction details by hash",
-  args: z6.object({
-    txhash: z6.string().describe("Transaction hash")
+  description: "Get transaction details by hash.",
+  args: z8.object({
+    txhash: z8.string().describe("Transaction hash")
   }),
-  options: z6.object({
+  options: z8.object({
     chain: chainOption6
   }),
+  env: etherscanEnv,
+  output: z8.object({
+    hash: z8.string(),
+    from: z8.string(),
+    to: z8.string().nullable(),
+    value: z8.string(),
+    gas: z8.string(),
+    gasPrice: z8.string(),
+    nonce: z8.string(),
+    block: z8.string(),
+    chain: z8.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "abstract" },
+      description: "Inspect one transaction on Abstract"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const tx = await withRateLimit7(
-      () => client.callProxy({
-        chainid: chainId,
-        module: "proxy",
-        action: "eth_getTransactionByHash",
-        txhash: c.args.txhash
-      }),
+      () => client.callProxy(
+        {
+          chainid: chainId,
+          module: "proxy",
+          action: "eth_getTransactionByHash",
+          txhash: c.args.txhash
+        },
+        transactionInfoSchema
+      ),
       rateLimiter6
     );
     return c.ok(
@@ -846,24 +1275,46 @@ txCli.command("info", {
   }
 });
 txCli.command("receipt", {
-  description: "Get the receipt for a transaction",
-  args: z6.object({
-    txhash: z6.string().describe("Transaction hash")
+  description: "Get the receipt for a transaction.",
+  args: z8.object({
+    txhash: z8.string().describe("Transaction hash")
   }),
-  options: z6.object({
+  options: z8.object({
     chain: chainOption6
   }),
+  env: etherscanEnv,
+  output: z8.object({
+    hash: z8.string(),
+    block: z8.string(),
+    from: z8.string(),
+    to: z8.string().nullable(),
+    status: z8.string(),
+    gasUsed: z8.string(),
+    contractAddress: z8.string().nullable(),
+    logCount: z8.number(),
+    chain: z8.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "ethereum" },
+      description: "Get receipt details including status and logs"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const receipt = await withRateLimit7(
-      () => client.callProxy({
-        chainid: chainId,
-        module: "proxy",
-        action: "eth_getTransactionReceipt",
-        txhash: c.args.txhash
-      }),
+      () => client.callProxy(
+        {
+          chainid: chainId,
+          module: "proxy",
+          action: "eth_getTransactionReceipt",
+          txhash: c.args.txhash
+        },
+        transactionReceiptSchema
+      ),
       rateLimiter6
     );
     return c.ok(
@@ -893,24 +1344,41 @@ txCli.command("receipt", {
   }
 });
 txCli.command("status", {
-  description: "Check whether a transaction succeeded or failed",
-  args: z6.object({
-    txhash: z6.string().describe("Transaction hash")
+  description: "Check whether a transaction succeeded or failed.",
+  args: z8.object({
+    txhash: z8.string().describe("Transaction hash")
   }),
-  options: z6.object({
+  options: z8.object({
     chain: chainOption6
   }),
+  env: etherscanEnv,
+  output: z8.object({
+    hash: z8.string(),
+    status: z8.string(),
+    error: z8.string().optional(),
+    chain: z8.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "base" },
+      description: "Get pass/fail status for a transaction"
+    }
+  ],
   async run(c) {
-    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
     const result = await withRateLimit7(
-      () => client.call({
-        chainid: chainId,
-        module: "transaction",
-        action: "gettxreceiptstatus",
-        txhash: c.args.txhash
-      }),
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "transaction",
+          action: "gettxreceiptstatus",
+          txhash: c.args.txhash
+        },
+        txStatusSchema
+      ),
       rateLimiter6
     );
     return c.ok(
@@ -945,7 +1413,18 @@ cli.command(txCli);
 cli.command(tokenCli);
 cli.command(gasCli);
 cli.command(statsCli);
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+var isMain = (() => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+  try {
+    return realpathSync(entrypoint) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
   cli.serve();
 }
 export {