@spectratools/etherscan-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spectra-the-bot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @spectra-the-bot/etherscan-cli
+
+Etherscan V2 API CLI built with [incur](https://github.com/wevm/incur). Supports 60+ chains including Abstract (2741).
+
+## Setup
+
+```bash
+export ETHERSCAN_API_KEY=your_api_key
+```
+
+## Commands
+
+### Account
+
+```bash
+# ETH balance
+etherscan-cli account balance <address> [--chain abstract]
+
+# Transaction list
+etherscan-cli account txlist <address> [--startblock 0] [--endblock latest] [--page 1] [--offset 10] [--sort asc]
+
+# ERC-20 token transfers
+etherscan-cli account tokentx <address> [--contractaddress 0x...] [--chain abstract]
+
+# ERC-20 token balance
+etherscan-cli account tokenbalance <address> --contractaddress <0x...> [--chain abstract]
+```
+
+### Contract
+
+```bash
+# ABI (verified contracts only)
+etherscan-cli contract abi <address> [--chain abstract]
+
+# Verified source code
+etherscan-cli contract source <address> [--chain abstract]
+
+# Deployment transaction
+etherscan-cli contract creation <address> [--chain abstract]
+```
+
+### Transaction
+
+```bash
+etherscan-cli tx info <txhash> [--chain abstract]
+etherscan-cli tx receipt <txhash> [--chain abstract]
+etherscan-cli tx status <txhash> [--chain abstract]
+```
+
+### Token
+
+```bash
+etherscan-cli token info <contractaddress> [--chain abstract]
+etherscan-cli token holders <contractaddress> [--page 1] [--offset 10] [--chain abstract]
+etherscan-cli token supply <contractaddress> [--chain abstract]
+```
+
+### Gas
+
+```bash
+etherscan-cli gas oracle [--chain abstract]
+etherscan-cli gas estimate --gasprice <wei> [--chain abstract]
+```
+
+### Stats
+
+```bash
+etherscan-cli stats ethprice [--chain abstract]
+etherscan-cli stats ethsupply [--chain abstract]
+```
+
+## Supported Chains
+
+| Name | Chain ID |
+|------|----------|
+| abstract | 2741 |
+| ethereum / mainnet | 1 |
+| base | 8453 |
+| arbitrum | 42161 |
+| optimism | 10 |
+| polygon | 137 |
+| avalanche | 43114 |
+| bsc | 56 |
+| linea | 59144 |
+| scroll | 534352 |
+| zksync | 324 |
+| mantle | 5000 |
+| blast | 81457 |
+| mode | 34443 |
+| sepolia | 11155111 |
+
+## Rate Limiting
+
+The free Etherscan API tier allows 5 requests/second. The CLI enforces this automatically using a token-bucket rate limiter from `@spectra-the-bot/cli-shared`.
+
+## Output Formats
+
+```bash
+# Human-readable (default)
+etherscan-cli account balance 0x...
+
+# JSON (for piping/agents)
+etherscan-cli account balance 0x... --json
+```

package/dist/cli.js

@@ -0,0 +1,953 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { fileURLToPath } from "url";
+import { Cli as Cli7 } from "incur";
+
+// src/commands/account.ts
+import {
+  apiKeyAuth,
+  checksumAddress,
+  createRateLimiter as createRateLimiter2,
+  formatTimestamp,
+  weiToEth,
+  withRateLimit as withRateLimit2
+} from "@spectratools/cli-shared";
+import { Cli, z } from "incur";
+
+// src/api.ts
+import {
+  createHttpClient,
+  createRateLimiter,
+  withRateLimit,
+  withRetry
+} from "@spectratools/cli-shared";
+var DEFAULT_BASE_URL = "https://api.etherscan.io/v2/api";
+var RETRY_OPTIONS = { maxRetries: 3, baseMs: 500, maxMs: 1e4 };
+var EtherscanError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EtherscanError";
+  }
+};
+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) {
+    const response = await request(params);
+    if (response.status === "0") {
+      const msg = typeof response.result === "string" ? response.result : response.message;
+      throw new EtherscanError(msg);
+    }
+    return response.result;
+  }
+  async function callProxy(params) {
+    const response = await request(params);
+    return response.result;
+  }
+  return { call, callProxy };
+}
+
+// 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 = z.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+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 ETH balance of an address",
+  args: z.object({
+    address: z.string().describe("Ethereum address")
+  }),
+  options: z.object({
+    chain: chainOption
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth("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"
+      }),
+      rateLimiter
+    );
+    return c.ok(
+      { address, wei, eth: weiToEth(wei), chain: c.options.chain },
+      {
+        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: z.object({
+    address: z.string().describe("Ethereum address")
+  }),
+  options: z.object({
+    startblock: z.number().optional().default(0).describe("Start block number"),
+    endblock: z.string().optional().default("latest").describe("End block number"),
+    page: z.number().optional().default(1).describe("Page number"),
+    offset: z.number().optional().default(10).describe("Number of results per page"),
+    sort: z.string().optional().default("asc").describe("Sort order (asc or desc)"),
+    chain: chainOption
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth("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
+      }),
+      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 },
+      {
+        cta: {
+          commands: firstHash ? [
+            {
+              command: "tx info",
+              args: { txhash: firstHash },
+              description: "Get details for the first transaction"
+            }
+          ] : []
+        }
+      }
+    );
+  }
+});
+accountCli.command("tokentx", {
+  description: "List ERC-20 token transfers for an address",
+  args: z.object({
+    address: z.string().describe("Ethereum address")
+  }),
+  options: z.object({
+    contractaddress: z.string().optional().describe("Filter by token contract address"),
+    page: z.number().optional().default(1).describe("Page number"),
+    offset: z.number().optional().default(20).describe("Results per page"),
+    chain: chainOption
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const address = normalizeAddress(c.args.address);
+    const client = createEtherscanClient(apiKey);
+    const transfers = await withRateLimit2(
+      () => client.call({
+        chainid: chainId,
+        module: "account",
+        action: "tokentx",
+        address,
+        contractaddress: c.options.contractaddress,
+        page: c.options.page,
+        offset: c.options.offset
+      }),
+      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 },
+      {
+        cta: {
+          commands: [
+            {
+              command: "account balance",
+              args: { address },
+              description: "Check ETH balance"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+accountCli.command("tokenbalance", {
+  description: "Get ERC-20 token balance for an address",
+  args: z.object({
+    address: z.string().describe("Ethereum address")
+  }),
+  options: z.object({
+    contractaddress: z.string().describe("Token contract address"),
+    chain: chainOption
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth("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"
+      }),
+      rateLimiter
+    );
+    return c.ok(
+      { address, contract, balance, chain: c.options.chain },
+      {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: contract },
+              description: "Get token info"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/contract.ts
+import {
+  apiKeyAuth as apiKeyAuth2,
+  checksumAddress as checksumAddress2,
+  createRateLimiter as createRateLimiter3,
+  withRateLimit as withRateLimit3
+} from "@spectratools/cli-shared";
+import { Cli as Cli2, z as z2 } from "incur";
+var rateLimiter2 = createRateLimiter3({ requestsPerSecond: 5 });
+var chainOption2 = z2.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var contractCli = Cli2.create("contract", {
+  description: "Query contract ABI, source code, and deployment info"
+});
+contractCli.command("abi", {
+  description: "Get the ABI for a verified contract",
+  args: z2.object({
+    address: z2.string().describe("Contract address")
+  }),
+  options: z2.object({
+    chain: chainOption2
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("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
+      }),
+      rateLimiter2
+    );
+    return c.ok(
+      { address, chain: c.options.chain, abi: JSON.parse(abi) },
+      {
+        cta: {
+          commands: [
+            {
+              command: "contract source",
+              args: { address },
+              description: "Get verified source code"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+contractCli.command("source", {
+  description: "Get verified source code for a contract",
+  args: z2.object({
+    address: z2.string().describe("Contract address")
+  }),
+  options: z2.object({
+    chain: chainOption2
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("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
+      }),
+      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
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "contract abi",
+              args: { address },
+              description: "Get the ABI"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+contractCli.command("creation", {
+  description: "Get the creation transaction for a contract",
+  args: z2.object({
+    address: z2.string().describe("Contract address")
+  }),
+  options: z2.object({
+    chain: chainOption2
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth2("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
+      }),
+      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
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "tx info",
+              args: { txhash: result.txHash },
+              description: "Get the creation transaction details"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/gas.ts
+import { apiKeyAuth as apiKeyAuth3, createRateLimiter as createRateLimiter4, withRateLimit as withRateLimit4 } from "@spectratools/cli-shared";
+import { Cli as Cli3, z as z3 } from "incur";
+var rateLimiter3 = createRateLimiter4({ requestsPerSecond: 5 });
+var chainOption3 = z3.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var gasCli = Cli3.create("gas", {
+  description: "Query gas oracle and estimate gas costs"
+});
+gasCli.command("oracle", {
+  description: "Get current gas price recommendations",
+  options: z3.object({
+    chain: chainOption3
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("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"
+      }),
+      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
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "gas estimate",
+              options: { gasprice: oracle.ProposeGasPrice },
+              description: "Estimate cost at standard gas price"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+gasCli.command("estimate", {
+  description: "Estimate gas cost in wei for a given gas price",
+  options: z3.object({
+    gasprice: z3.string().describe("Gas price in wei"),
+    chain: chainOption3
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth3("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
+      }),
+      rateLimiter3
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        gasprice: c.options.gasprice,
+        estimatedSeconds: estimate
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "gas oracle",
+              description: "See current gas price recommendations"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/stats.ts
+import { apiKeyAuth as apiKeyAuth4, createRateLimiter as createRateLimiter5, withRateLimit as withRateLimit5 } from "@spectratools/cli-shared";
+import { Cli as Cli4, z as z4 } from "incur";
+var rateLimiter4 = createRateLimiter5({ requestsPerSecond: 5 });
+var chainOption4 = z4.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var statsCli = Cli4.create("stats", {
+  description: "Query ETH price and supply statistics"
+});
+statsCli.command("ethprice", {
+  description: "Get the latest ETH price in USD and BTC",
+  options: z4.object({
+    chain: chainOption4
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth4("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const price = await withRateLimit5(
+      () => client.call({
+        chainid: chainId,
+        module: "stats",
+        action: "ethprice"
+      }),
+      rateLimiter4
+    );
+    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()
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "stats ethsupply",
+              description: "Get total ETH supply"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+statsCli.command("ethsupply", {
+  description: "Get the total supply of ETH",
+  options: z4.object({
+    chain: chainOption4
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth4("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const supply = await withRateLimit5(
+      () => client.call({
+        chainid: chainId,
+        module: "stats",
+        action: "ethsupply"
+      }),
+      rateLimiter4
+    );
+    return c.ok(
+      {
+        chain: c.options.chain,
+        totalSupplyWei: supply
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "stats ethprice",
+              description: "Get current ETH price"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/token.ts
+import {
+  apiKeyAuth as apiKeyAuth5,
+  checksumAddress as checksumAddress3,
+  createRateLimiter as createRateLimiter6,
+  withRateLimit as withRateLimit6
+} from "@spectratools/cli-shared";
+import { Cli as Cli5, z as z5 } from "incur";
+var rateLimiter5 = createRateLimiter6({ requestsPerSecond: 5 });
+var chainOption5 = z5.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var tokenCli = Cli5.create("token", {
+  description: "Query token info, holders, and supply"
+});
+tokenCli.command("info", {
+  description: "Get information about a token contract",
+  args: z5.object({
+    contractaddress: z5.string().describe("Token contract address")
+  }),
+  options: z5.object({
+    chain: chainOption5
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress3(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const results = await withRateLimit6(
+      () => client.call({
+        chainid: chainId,
+        module: "token",
+        action: "tokeninfo",
+        contractaddress: address
+      }),
+      rateLimiter5
+    );
+    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
+      },
+      {
+        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: z5.object({
+    contractaddress: z5.string().describe("Token contract address")
+  }),
+  options: z5.object({
+    page: z5.number().optional().default(1).describe("Page number"),
+    offset: z5.number().optional().default(10).describe("Results per page"),
+    chain: chainOption5
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress3(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const holders = await withRateLimit6(
+      () => client.call({
+        chainid: chainId,
+        module: "token",
+        action: "tokenholderlist",
+        contractaddress: address,
+        page: c.options.page,
+        offset: c.options.offset
+      }),
+      rateLimiter5
+    );
+    const formatted = holders.map((h, i) => ({
+      rank: (c.options.page - 1) * c.options.offset + i + 1,
+      address: checksumAddress3(h.TokenHolderAddress),
+      quantity: h.TokenHolderQuantity
+    }));
+    return c.ok(
+      {
+        contractAddress: address,
+        chain: c.options.chain,
+        count: formatted.length,
+        holders: formatted
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: address },
+              description: "Get token details"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+tokenCli.command("supply", {
+  description: "Get the total supply of a token",
+  args: z5.object({
+    contractaddress: z5.string().describe("Token contract address")
+  }),
+  options: z5.object({
+    chain: chainOption5
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth5("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const address = checksumAddress3(c.args.contractaddress);
+    const client = createEtherscanClient(apiKey);
+    const supply = await withRateLimit6(
+      () => client.call({
+        chainid: chainId,
+        module: "stats",
+        action: "tokensupply",
+        contractaddress: address
+      }),
+      rateLimiter5
+    );
+    return c.ok(
+      { contractAddress: address, chain: c.options.chain, totalSupply: supply },
+      {
+        cta: {
+          commands: [
+            {
+              command: "token info",
+              args: { contractaddress: address },
+              description: "Get full token info"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/commands/tx.ts
+import { apiKeyAuth as apiKeyAuth6, createRateLimiter as createRateLimiter7, withRateLimit as withRateLimit7 } from "@spectratools/cli-shared";
+import { Cli as Cli6, z as z6 } from "incur";
+var rateLimiter6 = createRateLimiter7({ requestsPerSecond: 5 });
+var chainOption6 = z6.string().default(DEFAULT_CHAIN).describe("Chain name (abstract, ethereum, base, arbitrum, ...)");
+var txCli = Cli6.create("tx", {
+  description: "Query transaction details, receipts, and status"
+});
+txCli.command("info", {
+  description: "Get transaction details by hash",
+  args: z6.object({
+    txhash: z6.string().describe("Transaction hash")
+  }),
+  options: z6.object({
+    chain: chainOption6
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const tx = await withRateLimit7(
+      () => client.callProxy({
+        chainid: chainId,
+        module: "proxy",
+        action: "eth_getTransactionByHash",
+        txhash: c.args.txhash
+      }),
+      rateLimiter6
+    );
+    return c.ok(
+      {
+        hash: tx.hash,
+        from: tx.from,
+        to: tx.to,
+        value: tx.value,
+        gas: tx.gas,
+        gasPrice: tx.gasPrice,
+        nonce: tx.nonce,
+        block: tx.blockNumber,
+        chain: c.options.chain
+      },
+      {
+        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: z6.object({
+    txhash: z6.string().describe("Transaction hash")
+  }),
+  options: z6.object({
+    chain: chainOption6
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const receipt = await withRateLimit7(
+      () => client.callProxy({
+        chainid: chainId,
+        module: "proxy",
+        action: "eth_getTransactionReceipt",
+        txhash: c.args.txhash
+      }),
+      rateLimiter6
+    );
+    return c.ok(
+      {
+        hash: receipt.transactionHash,
+        block: receipt.blockNumber,
+        from: receipt.from,
+        to: receipt.to,
+        status: receipt.status === "0x1" ? "success" : "failed",
+        gasUsed: receipt.gasUsed,
+        contractAddress: receipt.contractAddress,
+        logCount: receipt.logs.length,
+        chain: c.options.chain
+      },
+      {
+        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: z6.object({
+    txhash: z6.string().describe("Transaction hash")
+  }),
+  options: z6.object({
+    chain: chainOption6
+  }),
+  async run(c) {
+    const { apiKey } = apiKeyAuth6("ETHERSCAN_API_KEY");
+    const chainId = resolveChainId(c.options.chain);
+    const client = createEtherscanClient(apiKey);
+    const result = await withRateLimit7(
+      () => client.call({
+        chainid: chainId,
+        module: "transaction",
+        action: "gettxreceiptstatus",
+        txhash: c.args.txhash
+      }),
+      rateLimiter6
+    );
+    return c.ok(
+      {
+        hash: c.args.txhash,
+        status: result.status === "1" ? "success" : "failed",
+        error: result.errDescription || void 0,
+        chain: c.options.chain
+      },
+      {
+        cta: {
+          commands: [
+            {
+              command: "tx receipt",
+              args: { txhash: c.args.txhash },
+              description: "Get the full receipt"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
+
+// src/cli.ts
+var cli = Cli7.create("etherscan", {
+  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);
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  cli.serve();
+}
+export {
+  cli
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@spectratools/etherscan-cli",
+  "version": "0.1.0",
+  "description": "Etherscan API CLI for spectra-the-bot",
+  "type": "module",
+  "license": "MIT",
+  "author": "spectra-the-bot",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "etherscan-cli": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "incur": "^0.2.2",
+    "@spectratools/cli-shared": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3",
+    "vitest": "2.1.8"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/cli.js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}