@spectratools/etherscan-cli 0.3.0 → 0.3.2

package/dist/index.js

@@ -0,0 +1,1987 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { Cli as Cli8 } from "incur";
+
+// src/commands/account.ts
+import {
+  checksumAddress,
+  createRateLimiter as createRateLimiter2,
+  formatTimestamp,
+  isAddress,
+  weiToEth,
+  withRateLimit as withRateLimit2
+} from "@spectratools/cli-shared";
+import { Cli, z as z3 } from "incur";
+
+// src/api.ts
+import {
+  createHttpClient,
+  createRateLimiter,
+  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, 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 });
+  function request(params) {
+    return withRetry(
+      () => withRateLimit(
+        () => http.request("", {
+          query: { ...params, apikey: apiKey }
+        }),
+        acquire
+      ),
+      RETRY_OPTIONS
+    );
+  }
+  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, {
+        code: "ETHERSCAN_API_ERROR",
+        params,
+        response
+      });
+    }
+    return parseWithSchema(resultSchema, response.result, "rest", params);
+  }
+  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,
+  ethereum: 1,
+  mainnet: 1,
+  base: 8453,
+  arbitrum: 42161,
+  optimism: 10,
+  polygon: 137,
+  avalanche: 43114,
+  bsc: 56,
+  linea: 59144,
+  scroll: 534352,
+  zksync: 324,
+  mantle: 5e3,
+  blast: 81457,
+  mode: 34443,
+  sepolia: 11155111,
+  goerli: 5
+};
+var DEFAULT_CHAIN = "abstract";
+function resolveChainId(chain) {
+  const id = CHAIN_IDS[chain.toLowerCase()];
+  if (id === void 0) {
+    const known = Object.keys(CHAIN_IDS).join(", ");
+    throw new Error(`Unknown chain "${chain}". Supported chains: ${known}`);
+  }
+  return id;
+}
+
+// src/commands/account.ts
+var rateLimiter = createRateLimiter2({ requestsPerSecond: 5 });
+var chainOption = z3.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+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 internalTxItemSchema = z3.object({
+  hash: z3.string(),
+  from: z3.string(),
+  to: z3.string().nullable().optional(),
+  value: z3.string(),
+  timeStamp: z3.string(),
+  blockNumber: z3.string(),
+  type: z3.string().optional(),
+  traceId: z3.string().optional(),
+  isError: z3.string().optional(),
+  gasUsed: z3.string().optional()
+});
+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()
+});
+var nftTxItemSchema = z3.object({
+  hash: z3.string(),
+  from: z3.string(),
+  to: z3.string(),
+  tokenID: z3.string(),
+  tokenValue: z3.string().optional(),
+  tokenName: z3.string(),
+  tokenSymbol: z3.string(),
+  timeStamp: z3.string(),
+  contractAddress: z3.string()
+});
+function normalizeAddress(address) {
+  try {
+    return checksumAddress(address);
+  } catch {
+    return address;
+  }
+}
+var accountCli = Cli.create("account", {
+  description: "Query account balances, transactions, and token transfers."
+});
+accountCli.command("balance", {
+  description: "Get the native-token balance of an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
+  }),
+  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) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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"
+        },
+        z3.string()
+      ),
+      rateLimiter
+    );
+    return c.ok(
+      { address, wei, eth: weiToEth(wei), chain: c.options.chain },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "account txlist",
+              args: { address },
+              description: "List transactions"
+            },
+            {
+              command: "account tokentx",
+              args: { address },
+              description: "List token transfers"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+accountCli.command("txlist", {
+  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) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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
+        },
+        z3.array(txListItemSchema)
+      ),
+      rateLimiter
+    );
+    const formatted = txs.map((tx) => ({
+      hash: tx.hash,
+      from: normalizeAddress(tx.from),
+      to: tx.to ? normalizeAddress(tx.to) : "",
+      value: tx.value,
+      eth: weiToEth(tx.value),
+      timestamp: formatTimestamp(Number(tx.timeStamp)),
+      block: tx.blockNumber,
+      status: tx.isError === "0" ? "success" : "failed",
+      gasUsed: tx.gasUsed
+    }));
+    const firstHash = formatted[0]?.hash;
+    return c.ok(
+      { address, chain: c.options.chain, count: formatted.length, transactions: formatted },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: firstHash ? [
+            {
+              command: "tx info",
+              args: { txhash: firstHash },
+              description: "Get details for the first transaction"
+            }
+          ] : []
+        }
+      }
+    );
+  }
+});
+accountCli.command("internaltx", {
+  description: "List internal 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(),
+        type: z3.string().optional(),
+        traceId: z3.string().optional(),
+        status: z3.string(),
+        gasUsed: z3.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "ethereum", sort: "desc", offset: 5 },
+      description: "List recent internal transactions for an address"
+    }
+  ],
+  async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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: "txlistinternal",
+          address,
+          startblock: c.options.startblock,
+          endblock: c.options.endblock,
+          page: c.options.page,
+          offset: c.options.offset,
+          sort: c.options.sort
+        },
+        z3.array(internalTxItemSchema)
+      ),
+      rateLimiter
+    );
+    const formatted = txs.map((tx) => ({
+      hash: tx.hash,
+      from: normalizeAddress(tx.from),
+      to: tx.to ? normalizeAddress(tx.to) : "",
+      value: tx.value,
+      eth: weiToEth(tx.value),
+      timestamp: formatTimestamp(Number(tx.timeStamp)),
+      block: tx.blockNumber,
+      type: tx.type,
+      traceId: tx.traceId,
+      status: tx.isError === "0" || tx.isError === void 0 ? "success" : "failed",
+      gasUsed: tx.gasUsed ?? "0"
+    }));
+    return c.ok({
+      address,
+      chain: c.options.chain,
+      count: formatted.length,
+      transactions: formatted
+    });
+  }
+});
+accountCli.command("tokentx", {
+  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) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    if (c.options.contractaddress && !isAddress(c.options.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = normalizeAddress(c.args.address);
+    const contract = c.options.contractaddress ? normalizeAddress(c.options.contractaddress) : void 0;
+    const client = createEtherscanClient(apiKey);
+    const transfers = await withRateLimit2(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "tokentx",
+          address,
+          contractaddress: contract,
+          page: c.options.page,
+          offset: c.options.offset
+        },
+        z3.array(tokenTxItemSchema)
+      ),
+      rateLimiter
+    );
+    const formatted = transfers.map((tx) => ({
+      hash: tx.hash,
+      from: normalizeAddress(tx.from),
+      to: normalizeAddress(tx.to),
+      value: tx.value,
+      token: tx.tokenSymbol,
+      tokenName: tx.tokenName,
+      decimals: tx.tokenDecimal,
+      timestamp: formatTimestamp(Number(tx.timeStamp)),
+      contract: normalizeAddress(tx.contractAddress)
+    }));
+    return c.ok(
+      { address, chain: c.options.chain, count: formatted.length, transfers: formatted },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "account balance",
+              args: { address },
+              description: "Check ETH balance"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+accountCli.command("nfttx", {
+  description: "List ERC-721 NFT transfers for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
+  }),
+  options: z3.object({
+    contractaddress: z3.string().optional().describe("Filter by NFT contract address"),
+    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(20).describe("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(),
+    transfers: z3.array(
+      z3.object({
+        hash: z3.string(),
+        from: z3.string(),
+        to: z3.string(),
+        tokenId: z3.string(),
+        tokenName: z3.string(),
+        tokenSymbol: z3.string(),
+        timestamp: z3.string(),
+        contract: z3.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "ethereum", offset: 10, sort: "desc" },
+      description: "List recent ERC-721 transfers for an address"
+    }
+  ],
+  async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    if (c.options.contractaddress && !isAddress(c.options.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = normalizeAddress(c.args.address);
+    const contract = c.options.contractaddress ? normalizeAddress(c.options.contractaddress) : void 0;
+    const client = createEtherscanClient(apiKey);
+    const transfers = await withRateLimit2(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "tokennfttx",
+          address,
+          contractaddress: contract,
+          startblock: c.options.startblock,
+          endblock: c.options.endblock,
+          page: c.options.page,
+          offset: c.options.offset,
+          sort: c.options.sort
+        },
+        z3.array(nftTxItemSchema)
+      ),
+      rateLimiter
+    );
+    const formatted = transfers.map((tx) => ({
+      hash: tx.hash,
+      from: normalizeAddress(tx.from),
+      to: normalizeAddress(tx.to),
+      tokenId: tx.tokenID,
+      tokenName: tx.tokenName,
+      tokenSymbol: tx.tokenSymbol,
+      timestamp: formatTimestamp(Number(tx.timeStamp)),
+      contract: normalizeAddress(tx.contractAddress)
+    }));
+    return c.ok({
+      address,
+      chain: c.options.chain,
+      count: formatted.length,
+      transfers: formatted
+    });
+  }
+});
+accountCli.command("erc1155tx", {
+  description: "List ERC-1155 token transfers for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet address")
+  }),
+  options: z3.object({
+    contractaddress: z3.string().optional().describe("Filter by ERC-1155 contract address"),
+    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(20).describe("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(),
+    transfers: z3.array(
+      z3.object({
+        hash: z3.string(),
+        from: z3.string(),
+        to: z3.string(),
+        tokenId: z3.string(),
+        amount: z3.string(),
+        tokenName: z3.string(),
+        tokenSymbol: z3.string(),
+        timestamp: z3.string(),
+        contract: z3.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      options: { chain: "ethereum", offset: 10, sort: "desc" },
+      description: "List recent ERC-1155 transfers for an address"
+    }
+  ],
+  async run(c) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    if (c.options.contractaddress && !isAddress(c.options.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = normalizeAddress(c.args.address);
+    const contract = c.options.contractaddress ? normalizeAddress(c.options.contractaddress) : void 0;
+    const client = createEtherscanClient(apiKey);
+    const transfers = await withRateLimit2(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "account",
+          action: "token1155tx",
+          address,
+          contractaddress: contract,
+          startblock: c.options.startblock,
+          endblock: c.options.endblock,
+          page: c.options.page,
+          offset: c.options.offset,
+          sort: c.options.sort
+        },
+        z3.array(nftTxItemSchema)
+      ),
+      rateLimiter
+    );
+    const formatted = transfers.map((tx) => ({
+      hash: tx.hash,
+      from: normalizeAddress(tx.from),
+      to: normalizeAddress(tx.to),
+      tokenId: tx.tokenID,
+      amount: tx.tokenValue ?? "0",
+      tokenName: tx.tokenName,
+      tokenSymbol: tx.tokenSymbol,
+      timestamp: formatTimestamp(Number(tx.timeStamp)),
+      contract: normalizeAddress(tx.contractAddress)
+    }));
+    return c.ok({
+      address,
+      chain: c.options.chain,
+      count: formatted.length,
+      transfers: formatted
+    });
+  }
+});
+accountCli.command("tokenbalance", {
+  description: "Get ERC-20 token balance for an address.",
+  args: z3.object({
+    address: z3.string().describe("Wallet 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) {
+    if (!isAddress(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    if (!isAddress(c.options.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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"
+        },
+        z3.string()
+      ),
+      rateLimiter
+    );
+    return c.ok(
+      { address, contract, balance, chain: c.options.chain },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: contract },
+              description: "Get token info"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/contract.ts
+import {
+  checksumAddress as checksumAddress2,
+  createRateLimiter as createRateLimiter3,
+  isAddress as isAddress2,
+  withRateLimit as withRateLimit3
+} from "@spectratools/cli-shared";
+import { Cli as Cli2, z as z4 } from "incur";
+var rateLimiter2 = createRateLimiter3({ requestsPerSecond: 5 });
+var chainOption2 = z4.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var contractCli = Cli2.create("contract", {
+  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: z4.object({
+    address: z4.string().describe("Contract address")
+  }),
+  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) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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
+        },
+        z4.string()
+      ),
+      rateLimiter2
+    );
+    return c.ok(
+      { address, chain: c.options.chain, abi: JSON.parse(abi) },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "contract source",
+              args: { address },
+              description: "Get verified source code"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+contractCli.command("source", {
+  description: "Get verified source code for a contract.",
+  args: z4.object({
+    address: z4.string().describe("Contract address")
+  }),
+  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) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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
+        },
+        z4.array(sourceResultSchema)
+      ),
+      rateLimiter2
+    );
+    const result = results[0];
+    if (!result) {
+      return c.error({ code: "NOT_FOUND", message: "No source code found for this contract" });
+    }
+    return c.ok(
+      {
+        address,
+        chain: c.options.chain,
+        name: result.ContractName,
+        compiler: result.CompilerVersion,
+        optimized: result.OptimizationUsed === "1",
+        runs: result.Runs,
+        license: result.LicenseType,
+        proxy: result.Proxy !== "0",
+        implementation: result.Implementation || void 0,
+        sourceCode: result.SourceCode,
+        constructorArguments: result.ConstructorArguments
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "contract abi",
+              args: { address },
+              description: "Get the ABI"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+contractCli.command("creation", {
+  description: "Get the deployment transaction and creator for a contract.",
+  args: z4.object({
+    address: z4.string().describe("Contract address")
+  }),
+  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) {
+    if (!isAddress2(c.args.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid address: "${c.args.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    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
+        },
+        z4.array(creationResultSchema)
+      ),
+      rateLimiter2
+    );
+    const result = results[0];
+    if (!result) {
+      return c.error({ code: "NOT_FOUND", message: "Contract creation info not found" });
+    }
+    return c.ok(
+      {
+        address: checksumAddress2(result.contractAddress),
+        creator: checksumAddress2(result.contractCreator),
+        txHash: result.txHash,
+        chain: c.options.chain
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "tx info",
+              args: { txhash: result.txHash },
+              description: "Get the creation transaction details"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/gas.ts
+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 = z5.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var gasCli = Cli3.create("gas", {
+  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: 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 = 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"
+        },
+        gasOracleSchema
+      ),
+      rateLimiter3
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        lastBlock: oracle.LastBlock,
+        slow: `${oracle.SafeGasPrice} Gwei`,
+        standard: `${oracle.ProposeGasPrice} Gwei`,
+        fast: `${oracle.FastGasPrice} Gwei`,
+        baseFee: `${oracle.suggestBaseFee} Gwei`,
+        gasUsedRatio: oracle.gasUsedRatio
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "gas estimate",
+              options: { gasprice: oracle.ProposeGasPrice },
+              description: "Estimate cost at standard gas price"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+gasCli.command("estimate", {
+  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 = 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
+        },
+        z5.string()
+      ),
+      rateLimiter3
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        gasprice: c.options.gasprice,
+        estimatedSeconds: estimate
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "gas oracle",
+              description: "See current gas price recommendations"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/logs.ts
+import {
+  checksumAddress as checksumAddress3,
+  createRateLimiter as createRateLimiter5,
+  formatTimestamp as formatTimestamp2,
+  isAddress as isAddress3,
+  withRateLimit as withRateLimit5
+} from "@spectratools/cli-shared";
+import { Cli as Cli4, z as z6 } from "incur";
+var rateLimiter4 = createRateLimiter5({ requestsPerSecond: 5 });
+var chainOption4 = z6.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var topicOperatorOption = z6.enum(["and", "or"]);
+var logsItemSchema = z6.object({
+  address: z6.string(),
+  topics: z6.array(z6.string()),
+  data: z6.string(),
+  blockNumber: z6.string(),
+  timeStamp: z6.string(),
+  gasPrice: z6.string().optional(),
+  gasUsed: z6.string().optional(),
+  logIndex: z6.string(),
+  transactionHash: z6.string(),
+  transactionIndex: z6.string().optional()
+});
+function normalizeAddress2(address) {
+  try {
+    return checksumAddress3(address);
+  } catch {
+    return address;
+  }
+}
+var logsCli = Cli4.create("logs", {
+  description: "Query event logs with topic, address, and block-range filters."
+});
+logsCli.command("get", {
+  description: "Get event logs from Etherscan logs.getLogs.",
+  args: z6.object({}),
+  options: z6.object({
+    fromblock: z6.string().optional().default("0").describe("Start block number"),
+    toblock: z6.string().optional().default("latest").describe("End block number"),
+    address: z6.string().optional().describe("Filter by contract address"),
+    topic0: z6.string().optional().describe("First indexed topic"),
+    topic1: z6.string().optional().describe("Second indexed topic"),
+    topic2: z6.string().optional().describe("Third indexed topic"),
+    topic3: z6.string().optional().describe("Fourth indexed topic"),
+    topic0_1_opr: topicOperatorOption.optional().describe("Operator between topic0 and topic1"),
+    topic1_2_opr: topicOperatorOption.optional().describe("Operator between topic1 and topic2"),
+    topic2_3_opr: topicOperatorOption.optional().describe("Operator between topic2 and topic3"),
+    page: z6.number().optional().default(1).describe("Page number"),
+    offset: z6.number().optional().default(100).describe("Results per page"),
+    chain: chainOption4
+  }),
+  env: etherscanEnv,
+  output: z6.object({
+    chain: z6.string(),
+    fromBlock: z6.string(),
+    toBlock: z6.string(),
+    address: z6.string().optional(),
+    count: z6.number(),
+    logs: z6.array(
+      z6.object({
+        address: z6.string(),
+        topics: z6.array(z6.string()),
+        data: z6.string(),
+        block: z6.string(),
+        timestamp: z6.string(),
+        transactionHash: z6.string(),
+        logIndex: z6.string(),
+        transactionIndex: z6.string().optional(),
+        gasPrice: z6.string().optional(),
+        gasUsed: z6.string().optional()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: {},
+      options: {
+        chain: "ethereum",
+        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        topic0: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55aebec6f6f3c",
+        fromblock: "20000000",
+        toblock: "latest",
+        offset: 25
+      },
+      description: "Query ERC-20 Transfer logs for USDC"
+    }
+  ],
+  async run(c) {
+    if (c.options.address && !isAddress3(c.options.address)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.options.address}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const logs = await withRateLimit5(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "logs",
+          action: "getLogs",
+          fromBlock: c.options.fromblock,
+          toBlock: c.options.toblock,
+          address: c.options.address ? normalizeAddress2(c.options.address) : void 0,
+          topic0: c.options.topic0,
+          topic1: c.options.topic1,
+          topic2: c.options.topic2,
+          topic3: c.options.topic3,
+          topic0_1_opr: c.options.topic0_1_opr,
+          topic1_2_opr: c.options.topic1_2_opr,
+          topic2_3_opr: c.options.topic2_3_opr,
+          page: c.options.page,
+          offset: c.options.offset
+        },
+        z6.array(logsItemSchema)
+      ),
+      rateLimiter4
+    );
+    const formatted = logs.map((log) => ({
+      address: normalizeAddress2(log.address),
+      topics: log.topics,
+      data: log.data,
+      block: log.blockNumber,
+      timestamp: formatTimestamp2(Number(log.timeStamp)),
+      transactionHash: log.transactionHash,
+      logIndex: log.logIndex,
+      transactionIndex: log.transactionIndex,
+      gasPrice: log.gasPrice,
+      gasUsed: log.gasUsed
+    }));
+    return c.ok({
+      chain: c.options.chain,
+      fromBlock: c.options.fromblock,
+      toBlock: c.options.toblock,
+      address: c.options.address ? normalizeAddress2(c.options.address) : void 0,
+      count: formatted.length,
+      logs: formatted
+    });
+  }
+});
+
+// src/commands/stats.ts
+import { 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 = z7.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var statsCli = Cli5.create("stats", {
+  description: "Query ETH price and total supply statistics."
+});
+var ethPriceSchema = z7.object({
+  ethbtc: z7.string(),
+  ethbtc_timestamp: z7.string(),
+  ethusd: z7.string(),
+  ethusd_timestamp: z7.string()
+});
+statsCli.command("ethprice", {
+  description: "Get latest ETH price in USD and BTC.",
+  options: z7.object({
+    chain: chainOption5
+  }),
+  env: etherscanEnv,
+  output: z7.object({
+    chain: z7.string(),
+    usd: z7.string(),
+    btc: z7.string(),
+    usdTimestamp: z7.string(),
+    btcTimestamp: z7.string()
+  }),
+  examples: [{ options: { chain: "ethereum" }, description: "Get ETH spot price on Ethereum" }],
+  async run(c) {
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const price = await withRateLimit6(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "ethprice"
+        },
+        ethPriceSchema
+      ),
+      rateLimiter5
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        usd: price.ethusd,
+        btc: price.ethbtc,
+        usdTimestamp: new Date(Number(price.ethusd_timestamp) * 1e3).toISOString(),
+        btcTimestamp: new Date(Number(price.ethbtc_timestamp) * 1e3).toISOString()
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "stats ethsupply",
+              description: "Get total ETH supply"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+statsCli.command("ethsupply", {
+  description: "Get total ETH supply in wei.",
+  options: z7.object({
+    chain: chainOption5
+  }),
+  env: etherscanEnv,
+  output: z7.object({
+    chain: z7.string(),
+    totalSupplyWei: z7.string()
+  }),
+  examples: [{ options: { chain: "ethereum" }, description: "Get total ETH supply" }],
+  async run(c) {
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const supply = await withRateLimit6(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "ethsupply"
+        },
+        z7.string()
+      ),
+      rateLimiter5
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        totalSupplyWei: supply
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "stats ethprice",
+              description: "Get current ETH price"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/token.ts
+import {
+  checksumAddress as checksumAddress4,
+  createRateLimiter as createRateLimiter7,
+  isAddress as isAddress4,
+  withRateLimit as withRateLimit7
+} from "@spectratools/cli-shared";
+import { Cli as Cli6, z as z8 } from "incur";
+var rateLimiter6 = createRateLimiter7({ requestsPerSecond: 5 });
+var chainOption6 = z8.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var tokenCli = Cli6.create("token", {
+  description: "Query token metadata, holders, and supply."
+});
+var tokenInfoSchema = z8.object({
+  contractAddress: z8.string(),
+  tokenName: z8.string(),
+  symbol: z8.string(),
+  divisor: z8.string(),
+  tokenType: z8.string(),
+  totalSupply: z8.string(),
+  blueCheckmark: z8.string(),
+  description: z8.string(),
+  website: z8.string(),
+  email: z8.string(),
+  blog: z8.string(),
+  reddit: z8.string(),
+  slack: z8.string(),
+  facebook: z8.string(),
+  twitter: z8.string(),
+  bitcointalk: z8.string(),
+  github: z8.string(),
+  telegram: z8.string(),
+  wechat: z8.string(),
+  linkedin: z8.string(),
+  discord: z8.string(),
+  whitepaper: z8.string(),
+  tokenPriceUSD: z8.string()
+});
+var holderEntrySchema = z8.object({
+  TokenHolderAddress: z8.string(),
+  TokenHolderQuantity: z8.string()
+});
+tokenCli.command("info", {
+  description: "Get metadata for a token contract.",
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
+  }),
+  options: z8.object({
+    chain: chainOption6
+  }),
+  env: etherscanEnv,
+  output: z8.object({
+    address: z8.string(),
+    chain: z8.string(),
+    name: z8.string(),
+    symbol: z8.string(),
+    type: z8.string(),
+    totalSupply: z8.string(),
+    decimals: z8.string(),
+    priceUsd: z8.string().optional(),
+    website: z8.string().optional(),
+    description: z8.string().optional()
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Get token metadata for USDC"
+    }
+  ],
+  async run(c) {
+    if (!isAddress4(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress4(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const results = await withRateLimit7(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "token",
+          action: "tokeninfo",
+          contractaddress: address
+        },
+        z8.array(tokenInfoSchema)
+      ),
+      rateLimiter6
+    );
+    const info = results[0];
+    if (!info) {
+      return c.error({ code: "NOT_FOUND", message: "Token info not found" });
+    }
+    return c.ok(
+      {
+        address,
+        chain: c.options.chain,
+        name: info.tokenName,
+        symbol: info.symbol,
+        type: info.tokenType,
+        totalSupply: info.totalSupply,
+        decimals: info.divisor,
+        priceUsd: info.tokenPriceUSD || void 0,
+        website: info.website || void 0,
+        description: info.description || void 0
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "token supply",
+              args: { contractaddress: address },
+              description: "Get circulating supply"
+            },
+            {
+              command: "token holders",
+              args: { contractaddress: address },
+              description: "List top holders"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+tokenCli.command("holders", {
+  description: "List top token holders.",
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
+  }),
+  options: z8.object({
+    page: z8.number().optional().default(1).describe("Page number"),
+    offset: z8.number().optional().default(10).describe("Results per page"),
+    chain: chainOption6
+  }),
+  env: etherscanEnv,
+  output: z8.object({
+    contractAddress: z8.string(),
+    chain: z8.string(),
+    count: z8.number(),
+    holders: z8.array(
+      z8.object({
+        rank: z8.number(),
+        address: z8.string(),
+        quantity: z8.string()
+      })
+    )
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { page: 1, offset: 20, chain: "ethereum" },
+      description: "List top 20 holders for a token"
+    }
+  ],
+  async run(c) {
+    if (!isAddress4(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress4(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const holders = await withRateLimit7(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "token",
+          action: "tokenholderlist",
+          contractaddress: address,
+          page: c.options.page,
+          offset: c.options.offset
+        },
+        z8.array(holderEntrySchema)
+      ),
+      rateLimiter6
+    );
+    const formatted = holders.map((h, i) => ({
+      rank: (c.options.page - 1) * c.options.offset + i + 1,
+      address: checksumAddress4(h.TokenHolderAddress),
+      quantity: h.TokenHolderQuantity
+    }));
+    return c.ok(
+      {
+        contractAddress: address,
+        chain: c.options.chain,
+        count: formatted.length,
+        holders: formatted
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: address },
+              description: "Get token details"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+tokenCli.command("supply", {
+  description: "Get total token supply.",
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
+  }),
+  options: z8.object({
+    chain: chainOption6
+  }),
+  env: etherscanEnv,
+  output: z8.object({
+    contractAddress: z8.string(),
+    chain: z8.string(),
+    totalSupply: z8.string()
+  }),
+  examples: [
+    {
+      args: { contractaddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" },
+      options: { chain: "ethereum" },
+      description: "Get total supply for a token"
+    }
+  ],
+  async run(c) {
+    if (!isAddress4(c.args.contractaddress)) {
+      return c.error({
+        code: "INVALID_ADDRESS",
+        message: `Invalid contract address: "${c.args.contractaddress}". Use a valid 0x-prefixed 20-byte hex address.`
+      });
+    }
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress4(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const supply = await withRateLimit7(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "stats",
+          action: "tokensupply",
+          contractaddress: address
+        },
+        z8.string()
+      ),
+      rateLimiter6
+    );
+    return c.ok(
+      { contractAddress: address, chain: c.options.chain, totalSupply: supply },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: address },
+              description: "Get full token info"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/tx.ts
+import { createRateLimiter as createRateLimiter8, withRateLimit as withRateLimit8 } from "@spectratools/cli-shared";
+import { Cli as Cli7, z as z9 } from "incur";
+var rateLimiter7 = createRateLimiter8({ requestsPerSecond: 5 });
+function hexToDecimal(hex) {
+  return BigInt(hex).toString();
+}
+var chainOption7 = z9.string().default(DEFAULT_CHAIN).describe(
+  "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
+);
+var txCli = Cli7.create("tx", {
+  description: "Query transaction details, receipts, and execution status."
+});
+var transactionInfoSchema = z9.object({
+  hash: z9.string(),
+  from: z9.string(),
+  to: z9.string().nullable(),
+  value: z9.string(),
+  gas: z9.string(),
+  gasPrice: z9.string(),
+  nonce: z9.string(),
+  blockNumber: z9.string(),
+  blockHash: z9.string(),
+  input: z9.string()
+});
+var transactionReceiptSchema = z9.object({
+  transactionHash: z9.string(),
+  blockNumber: z9.string(),
+  blockHash: z9.string(),
+  from: z9.string(),
+  to: z9.string().nullable(),
+  status: z9.string(),
+  gasUsed: z9.string(),
+  cumulativeGasUsed: z9.string(),
+  contractAddress: z9.string().nullable(),
+  logs: z9.array(z9.unknown())
+});
+var txStatusSchema = z9.object({
+  isError: z9.string(),
+  errDescription: z9.string()
+});
+txCli.command("info", {
+  description: "Get transaction details by hash.",
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
+  }),
+  options: z9.object({
+    chain: chainOption7
+  }),
+  env: etherscanEnv,
+  output: z9.object({
+    hash: z9.string(),
+    from: z9.string(),
+    to: z9.string().nullable(),
+    value: z9.string(),
+    gas: z9.string(),
+    gasPrice: z9.string(),
+    nonce: z9.string(),
+    block: z9.string(),
+    chain: z9.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "abstract" },
+      description: "Inspect one transaction on Abstract"
+    }
+  ],
+  async run(c) {
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const tx = await withRateLimit8(
+      () => client.callProxy(
+        {
+          chainid: chainId,
+          module: "proxy",
+          action: "eth_getTransactionByHash",
+          txhash: c.args.txhash
+        },
+        transactionInfoSchema
+      ),
+      rateLimiter7
+    );
+    return c.ok(
+      {
+        hash: tx.hash,
+        from: tx.from,
+        to: tx.to,
+        value: hexToDecimal(tx.value),
+        gas: hexToDecimal(tx.gas),
+        gasPrice: hexToDecimal(tx.gasPrice),
+        nonce: hexToDecimal(tx.nonce),
+        block: hexToDecimal(tx.blockNumber),
+        chain: c.options.chain
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "tx receipt",
+              args: { txhash: c.args.txhash },
+              description: "Get the transaction receipt"
+            },
+            {
+              command: "tx status",
+              args: { txhash: c.args.txhash },
+              description: "Check execution status"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+txCli.command("receipt", {
+  description: "Get the receipt for a transaction.",
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
+  }),
+  options: z9.object({
+    chain: chainOption7
+  }),
+  env: etherscanEnv,
+  output: z9.object({
+    hash: z9.string(),
+    block: z9.string(),
+    from: z9.string(),
+    to: z9.string().nullable(),
+    status: z9.string(),
+    gasUsed: z9.string(),
+    contractAddress: z9.string().nullable(),
+    logCount: z9.number(),
+    chain: z9.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "ethereum" },
+      description: "Get receipt details including status and logs"
+    }
+  ],
+  async run(c) {
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const receipt = await withRateLimit8(
+      () => client.callProxy(
+        {
+          chainid: chainId,
+          module: "proxy",
+          action: "eth_getTransactionReceipt",
+          txhash: c.args.txhash
+        },
+        transactionReceiptSchema
+      ),
+      rateLimiter7
+    );
+    return c.ok(
+      {
+        hash: receipt.transactionHash,
+        block: hexToDecimal(receipt.blockNumber),
+        from: receipt.from,
+        to: receipt.to,
+        status: receipt.status === "0x1" ? "success" : "failed",
+        gasUsed: hexToDecimal(receipt.gasUsed),
+        contractAddress: receipt.contractAddress,
+        logCount: receipt.logs.length,
+        chain: c.options.chain
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "tx info",
+              args: { txhash: c.args.txhash },
+              description: "Get full transaction details"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+txCli.command("status", {
+  description: "Check whether a transaction succeeded or failed.",
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
+  }),
+  options: z9.object({
+    chain: chainOption7
+  }),
+  env: etherscanEnv,
+  output: z9.object({
+    hash: z9.string(),
+    status: z9.string(),
+    error: z9.string().optional(),
+    chain: z9.string()
+  }),
+  examples: [
+    {
+      args: { txhash: "0x1234...abcd" },
+      options: { chain: "base" },
+      description: "Get pass/fail status for a transaction"
+    }
+  ],
+  async run(c) {
+    const apiKey = c.env.ETHERSCAN_API_KEY;
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const result = await withRateLimit8(
+      () => client.call(
+        {
+          chainid: chainId,
+          module: "transaction",
+          action: "getstatus",
+          txhash: c.args.txhash
+        },
+        txStatusSchema
+      ),
+      rateLimiter7
+    );
+    return c.ok(
+      {
+        hash: c.args.txhash,
+        status: result.isError === "0" ? "success" : "failed",
+        error: result.errDescription || void 0,
+        chain: c.options.chain
+      },
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          commands: [
+            {
+              command: "tx receipt",
+              args: { txhash: c.args.txhash },
+              description: "Get the full receipt"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/cli.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
+var cli = Cli8.create("etherscan", {
+  version: pkg.version,
+  description: "Query Etherscan API data from the command line."
+});
+cli.command(accountCli);
+cli.command(contractCli);
+cli.command(txCli);
+cli.command(tokenCli);
+cli.command(gasCli);
+cli.command(statsCli);
+cli.command(logsCli);
+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 {
+  cli
+};