@spectratools/etherscan-cli 0.2.4 → 0.3.0

package/README.md

@@ -43,12 +43,13 @@ export ETHERSCAN_API_KEY=your_api_key
 
 ## Command Group Intent Summary
 
-- `account` — Wallet balances, normal tx history, token transfer history
+- `account` — Wallet balances, normal/internal tx history, ERC-20/ERC-721/ERC-1155 transfers
 - `contract` — ABI, verified source, and deployment transaction metadata
 - `tx` — Transaction detail, receipt, and pass/fail status checks
 - `token` — Token metadata, holder distribution, and supply
 - `gas` — Current gas oracle and time-to-confirmation estimates
 - `stats` — ETH price and supply snapshots
+- `logs` — Event log queries with address/topic/block filters
 
 ## Agent-Oriented Examples
 
@@ -56,20 +57,28 @@ export ETHERSCAN_API_KEY=your_api_key
 # 1) Wallet risk scan: balance + recent txs
 etherscan-cli account balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --format json
 etherscan-cli account txlist 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --sort desc --offset 20 --format json
+etherscan-cli account internaltx 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --sort desc --offset 20 --format json
 
-# 2) Contract triage for unknown addresses
+# 2) NFT transfer monitoring
+etherscan-cli account nfttx 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --sort desc --offset 20 --format json
+etherscan-cli account erc1155tx 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --sort desc --offset 20 --format json
+
+# 3) Contract triage for unknown addresses
 etherscan-cli contract creation 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
 etherscan-cli contract source 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
 
-# 3) Tx execution diagnosis
+# 4) Tx execution diagnosis
 etherscan-cli tx info 0x1234...abcd --chain abstract --format json
 etherscan-cli tx receipt 0x1234...abcd --chain abstract --format json
 
-# 4) Token monitoring loop
+# 5) Token monitoring loop
 etherscan-cli token info 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
 etherscan-cli token holders 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --offset 25 --chain ethereum --format json
 
-# 5) Gas-aware scheduling
+# 6) Event log indexing
+etherscan-cli logs get --chain ethereum --address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --topic0 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55aebec6f6f3c --fromblock 20000000 --toblock latest --offset 25 --format json
+
+# 7) Gas-aware scheduling
 etherscan-cli gas oracle --chain abstract --format json
 etherscan-cli gas estimate --gasprice 1000000000 --chain abstract --format json
 ```

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { readFileSync, realpathSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
-import { Cli as Cli7 } from "incur";
+import { Cli as Cli8 } from "incur";
 
 // src/commands/account.ts
 import {
@@ -153,6 +153,18 @@ var txListItemSchema = z3.object({
   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(),
@@ -164,6 +176,17 @@ var tokenTxItemSchema = z3.object({
   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);
@@ -336,6 +359,96 @@ accountCli.command("txlist", {
     );
   }
 });
+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({
@@ -380,9 +493,16 @@ accountCli.command("tokentx", {
         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(
@@ -391,7 +511,7 @@ accountCli.command("tokentx", {
           module: "account",
           action: "tokentx",
           address,
-          contractaddress: c.options.contractaddress,
+          contractaddress: contract,
           page: c.options.page,
           offset: c.options.offset
         },
@@ -426,6 +546,194 @@ accountCli.command("tokentx", {
     );
   }
 });
+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({
@@ -872,41 +1180,187 @@ gasCli.command("estimate", {
   }
 });
 
-// src/commands/stats.ts
-import { createRateLimiter as createRateLimiter5, withRateLimit as withRateLimit5 } from "@spectratools/cli-shared";
+// 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 statsCli = Cli4.create("stats", {
-  description: "Query ETH price and total supply statistics."
+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()
 });
-var ethPriceSchema = z6.object({
-  ethbtc: z6.string(),
-  ethbtc_timestamp: z6.string(),
-  ethusd: z6.string(),
-  ethusd_timestamp: z6.string()
+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."
 });
-statsCli.command("ethprice", {
-  description: "Get latest ETH price in USD and BTC.",
+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(),
-    usd: z6.string(),
-    btc: z6.string(),
-    usdTimestamp: z6.string(),
-    btcTimestamp: 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 withRateLimit5(
+    const price = await withRateLimit6(
       () => client.call(
         {
           chainid: chainId,
@@ -915,7 +1369,7 @@ statsCli.command("ethprice", {
         },
         ethPriceSchema
       ),
-      rateLimiter4
+      rateLimiter5
     );
     return c.ok(
       {
@@ -940,29 +1394,29 @@ statsCli.command("ethprice", {
 });
 statsCli.command("ethsupply", {
   description: "Get total ETH supply in wei.",
-  options: z6.object({
-    chain: chainOption4
+  options: z7.object({
+    chain: chainOption5
   }),
   env: etherscanEnv,
-  output: z6.object({
-    chain: z6.string(),
-    totalSupplyWei: z6.string()
+  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 withRateLimit5(
+    const supply = await withRateLimit6(
       () => client.call(
         {
           chainid: chainId,
           module: "stats",
           action: "ethsupply"
         },
-        z6.string()
+        z7.string()
       ),
-      rateLimiter4
+      rateLimiter5
     );
     return c.ok(
       {
@@ -985,68 +1439,68 @@ statsCli.command("ethsupply", {
 
 // src/commands/token.ts
 import {
-  checksumAddress as checksumAddress3,
-  createRateLimiter as createRateLimiter6,
-  isAddress as isAddress3,
-  withRateLimit as withRateLimit6
+  checksumAddress as checksumAddress4,
+  createRateLimiter as createRateLimiter7,
+  isAddress as isAddress4,
+  withRateLimit as withRateLimit7
 } 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(
+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 = Cli5.create("token", {
+var tokenCli = Cli6.create("token", {
   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 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 = z7.object({
-  TokenHolderAddress: z7.string(),
-  TokenHolderQuantity: z7.string()
+var holderEntrySchema = z8.object({
+  TokenHolderAddress: z8.string(),
+  TokenHolderQuantity: z8.string()
 });
 tokenCli.command("info", {
   description: "Get metadata for a token contract.",
-  args: z7.object({
-    contractaddress: z7.string().describe("Token contract address")
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
   }),
-  options: z7.object({
-    chain: chainOption5
+  options: z8.object({
+    chain: chainOption6
   }),
   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()
+  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: [
     {
@@ -1056,7 +1510,7 @@ tokenCli.command("info", {
     }
   ],
   async run(c) {
-    if (!isAddress3(c.args.contractaddress)) {
+    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.`
@@ -1064,9 +1518,9 @@ tokenCli.command("info", {
     }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
-    const address = checksumAddress3(c.args.contractaddress);
+    const address = checksumAddress4(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
-    const results = await withRateLimit6(
+    const results = await withRateLimit7(
       () => client.call(
         {
           chainid: chainId,
@@ -1074,9 +1528,9 @@ tokenCli.command("info", {
           action: "tokeninfo",
           contractaddress: address
         },
-        z7.array(tokenInfoSchema)
+        z8.array(tokenInfoSchema)
       ),
-      rateLimiter5
+      rateLimiter6
     );
     const info = results[0];
     if (!info) {
@@ -1116,24 +1570,24 @@ tokenCli.command("info", {
 });
 tokenCli.command("holders", {
   description: "List top token holders.",
-  args: z7.object({
-    contractaddress: z7.string().describe("Token contract address")
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
   }),
-  options: z7.object({
-    page: z7.number().optional().default(1).describe("Page number"),
-    offset: z7.number().optional().default(10).describe("Results per page"),
-    chain: chainOption5
+  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: 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()
+  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()
       })
     )
   }),
@@ -1145,7 +1599,7 @@ tokenCli.command("holders", {
     }
   ],
   async run(c) {
-    if (!isAddress3(c.args.contractaddress)) {
+    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.`
@@ -1153,9 +1607,9 @@ tokenCli.command("holders", {
     }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
-    const address = checksumAddress3(c.args.contractaddress);
+    const address = checksumAddress4(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
-    const holders = await withRateLimit6(
+    const holders = await withRateLimit7(
       () => client.call(
         {
           chainid: chainId,
@@ -1165,13 +1619,13 @@ tokenCli.command("holders", {
           page: c.options.page,
           offset: c.options.offset
         },
-        z7.array(holderEntrySchema)
+        z8.array(holderEntrySchema)
       ),
-      rateLimiter5
+      rateLimiter6
     );
     const formatted = holders.map((h, i) => ({
       rank: (c.options.page - 1) * c.options.offset + i + 1,
-      address: checksumAddress3(h.TokenHolderAddress),
+      address: checksumAddress4(h.TokenHolderAddress),
       quantity: h.TokenHolderQuantity
     }));
     return c.ok(
@@ -1197,17 +1651,17 @@ tokenCli.command("holders", {
 });
 tokenCli.command("supply", {
   description: "Get total token supply.",
-  args: z7.object({
-    contractaddress: z7.string().describe("Token contract address")
+  args: z8.object({
+    contractaddress: z8.string().describe("Token contract address")
   }),
-  options: z7.object({
-    chain: chainOption5
+  options: z8.object({
+    chain: chainOption6
   }),
   env: etherscanEnv,
-  output: z7.object({
-    contractAddress: z7.string(),
-    chain: z7.string(),
-    totalSupply: z7.string()
+  output: z8.object({
+    contractAddress: z8.string(),
+    chain: z8.string(),
+    totalSupply: z8.string()
   }),
   examples: [
     {
@@ -1217,7 +1671,7 @@ tokenCli.command("supply", {
     }
   ],
   async run(c) {
-    if (!isAddress3(c.args.contractaddress)) {
+    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.`
@@ -1225,9 +1679,9 @@ tokenCli.command("supply", {
     }
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
-    const address = checksumAddress3(c.args.contractaddress);
+    const address = checksumAddress4(c.args.contractaddress);
     const client = createEtherscanClient(apiKey);
-    const supply = await withRateLimit6(
+    const supply = await withRateLimit7(
       () => client.call(
         {
           chainid: chainId,
@@ -1235,9 +1689,9 @@ tokenCli.command("supply", {
           action: "tokensupply",
           contractaddress: address
         },
-        z7.string()
+        z8.string()
       ),
-      rateLimiter5
+      rateLimiter6
     );
     return c.ok(
       { contractAddress: address, chain: c.options.chain, totalSupply: supply },
@@ -1257,65 +1711,65 @@ tokenCli.command("supply", {
 });
 
 // src/commands/tx.ts
-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 });
+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 chainOption6 = z8.string().default(DEFAULT_CHAIN).describe(
+var chainOption7 = z9.string().default(DEFAULT_CHAIN).describe(
   "Chain name (default: abstract). Options: ethereum, base, arbitrum, optimism, polygon, ..."
 );
-var txCli = Cli6.create("tx", {
+var txCli = Cli7.create("tx", {
   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 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 = 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 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 = z8.object({
-  isError: z8.string(),
-  errDescription: z8.string()
+var txStatusSchema = z9.object({
+  isError: z9.string(),
+  errDescription: z9.string()
 });
 txCli.command("info", {
   description: "Get transaction details by hash.",
-  args: z8.object({
-    txhash: z8.string().describe("Transaction hash")
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
   }),
-  options: z8.object({
-    chain: chainOption6
+  options: z9.object({
+    chain: chainOption7
   }),
   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()
+  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: [
     {
@@ -1328,7 +1782,7 @@ txCli.command("info", {
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
-    const tx = await withRateLimit7(
+    const tx = await withRateLimit8(
       () => client.callProxy(
         {
           chainid: chainId,
@@ -1338,7 +1792,7 @@ txCli.command("info", {
         },
         transactionInfoSchema
       ),
-      rateLimiter6
+      rateLimiter7
     );
     return c.ok(
       {
@@ -1373,23 +1827,23 @@ txCli.command("info", {
 });
 txCli.command("receipt", {
   description: "Get the receipt for a transaction.",
-  args: z8.object({
-    txhash: z8.string().describe("Transaction hash")
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
   }),
-  options: z8.object({
-    chain: chainOption6
+  options: z9.object({
+    chain: chainOption7
   }),
   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()
+  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: [
     {
@@ -1402,7 +1856,7 @@ txCli.command("receipt", {
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
-    const receipt = await withRateLimit7(
+    const receipt = await withRateLimit8(
       () => client.callProxy(
         {
           chainid: chainId,
@@ -1412,7 +1866,7 @@ txCli.command("receipt", {
         },
         transactionReceiptSchema
       ),
-      rateLimiter6
+      rateLimiter7
     );
     return c.ok(
       {
@@ -1442,18 +1896,18 @@ txCli.command("receipt", {
 });
 txCli.command("status", {
   description: "Check whether a transaction succeeded or failed.",
-  args: z8.object({
-    txhash: z8.string().describe("Transaction hash")
+  args: z9.object({
+    txhash: z9.string().describe("Transaction hash")
   }),
-  options: z8.object({
-    chain: chainOption6
+  options: z9.object({
+    chain: chainOption7
   }),
   env: etherscanEnv,
-  output: z8.object({
-    hash: z8.string(),
-    status: z8.string(),
-    error: z8.string().optional(),
-    chain: z8.string()
+  output: z9.object({
+    hash: z9.string(),
+    status: z9.string(),
+    error: z9.string().optional(),
+    chain: z9.string()
   }),
   examples: [
     {
@@ -1466,7 +1920,7 @@ txCli.command("status", {
     const apiKey = c.env.ETHERSCAN_API_KEY;
     const chainId = resolveChainId(c.options.chain);
     const client = createEtherscanClient(apiKey);
-    const result = await withRateLimit7(
+    const result = await withRateLimit8(
       () => client.call(
         {
           chainid: chainId,
@@ -1476,7 +1930,7 @@ txCli.command("status", {
         },
         txStatusSchema
       ),
-      rateLimiter6
+      rateLimiter7
     );
     return c.ok(
       {
@@ -1503,7 +1957,7 @@ txCli.command("status", {
 // src/cli.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
-var cli = Cli7.create("etherscan", {
+var cli = Cli8.create("etherscan", {
   version: pkg.version,
   description: "Query Etherscan API data from the command line."
 });
@@ -1513,6 +1967,7 @@ cli.command(txCli);
 cli.command(tokenCli);
 cli.command(gasCli);
 cli.command(statsCli);
+cli.command(logsCli);
 var isMain = (() => {
   const entrypoint = process.argv[1];
   if (!entrypoint) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/etherscan-cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Etherscan API CLI for spectra-the-bot",
   "type": "module",
   "license": "MIT",