@spectratools/etherscan-cli 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +38 -77
  2. package/dist/cli.js +725 -246
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,104 +1,65 @@
1
- # @spectra-the-bot/etherscan-cli
1
+ # @spectratools/etherscan-cli
2
2
 
3
- Etherscan V2 API CLI built with [incur](https://github.com/wevm/incur). Supports 60+ chains including Abstract (2741).
3
+ Etherscan V2 API CLI for multi-chain explorer automation.
4
4
 
5
- ## Setup
5
+ ## Install
6
6
 
7
7
  ```bash
8
- export ETHERSCAN_API_KEY=your_api_key
8
+ pnpm add -g @spectratools/etherscan-cli
9
9
  ```
10
10
 
11
- ## Commands
12
-
13
- ### Account
11
+ ## LLM / Agent Discovery
14
12
 
15
13
  ```bash
16
- # ETH balance
17
- etherscan-cli account balance <address> [--chain abstract]
18
-
19
- # Transaction list
20
- etherscan-cli account txlist <address> [--startblock 0] [--endblock latest] [--page 1] [--offset 10] [--sort asc]
14
+ # Emit machine-readable command metadata
15
+ etherscan-cli --llms
21
16
 
22
- # ERC-20 token transfers
23
- etherscan-cli account tokentx <address> [--contractaddress 0x...] [--chain abstract]
17
+ # Register as a reusable local skill for agent runtimes
18
+ etherscan-cli skills add
24
19
 
25
- # ERC-20 token balance
26
- etherscan-cli account tokenbalance <address> --contractaddress <0x...> [--chain abstract]
20
+ # Register as an MCP server entry
21
+ etherscan-cli mcp add
27
22
  ```
28
23
 
29
- ### Contract
24
+ ## Configuration
30
25
 
31
26
  ```bash
32
- # ABI (verified contracts only)
33
- etherscan-cli contract abi <address> [--chain abstract]
34
-
35
- # Verified source code
36
- etherscan-cli contract source <address> [--chain abstract]
37
-
38
- # Deployment transaction
39
- etherscan-cli contract creation <address> [--chain abstract]
27
+ export ETHERSCAN_API_KEY=your_api_key
40
28
  ```
41
29
 
42
- ### Transaction
30
+ ## Command Group Intent Summary
43
31
 
44
- ```bash
45
- etherscan-cli tx info <txhash> [--chain abstract]
46
- etherscan-cli tx receipt <txhash> [--chain abstract]
47
- etherscan-cli tx status <txhash> [--chain abstract]
48
- ```
32
+ - `account` — Wallet balances, normal tx history, token transfer history
33
+ - `contract` — ABI, verified source, and deployment transaction metadata
34
+ - `tx` — Transaction detail, receipt, and pass/fail status checks
35
+ - `token` — Token metadata, holder distribution, and supply
36
+ - `gas` — Current gas oracle and time-to-confirmation estimates
37
+ - `stats` — ETH price and supply snapshots
49
38
 
50
- ### Token
39
+ ## Agent-Oriented Examples
51
40
 
52
41
  ```bash
53
- etherscan-cli token info <contractaddress> [--chain abstract]
54
- etherscan-cli token holders <contractaddress> [--page 1] [--offset 10] [--chain abstract]
55
- etherscan-cli token supply <contractaddress> [--chain abstract]
56
- ```
42
+ # 1) Wallet risk scan: balance + recent txs
43
+ etherscan-cli account balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --format json
44
+ etherscan-cli account txlist 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --sort desc --offset 20 --format json
57
45
 
58
- ### Gas
46
+ # 2) Contract triage for unknown addresses
47
+ etherscan-cli contract creation 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
48
+ etherscan-cli contract source 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
59
49
 
60
- ```bash
61
- etherscan-cli gas oracle [--chain abstract]
62
- etherscan-cli gas estimate --gasprice <wei> [--chain abstract]
63
- ```
50
+ # 3) Tx execution diagnosis
51
+ etherscan-cli tx info 0x1234...abcd --chain abstract --format json
52
+ etherscan-cli tx receipt 0x1234...abcd --chain abstract --format json
64
53
 
65
- ### Stats
54
+ # 4) Token monitoring loop
55
+ etherscan-cli token info 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --chain ethereum --format json
56
+ etherscan-cli token holders 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --offset 25 --chain ethereum --format json
66
57
 
67
- ```bash
68
- etherscan-cli stats ethprice [--chain abstract]
69
- etherscan-cli stats ethsupply [--chain abstract]
58
+ # 5) Gas-aware scheduling
59
+ etherscan-cli gas oracle --chain abstract --format json
60
+ etherscan-cli gas estimate --gasprice 1000000000 --chain abstract --format json
70
61
  ```
71
62
 
72
- ## Supported Chains
73
-
74
- | Name | Chain ID |
75
- |------|----------|
76
- | abstract | 2741 |
77
- | ethereum / mainnet | 1 |
78
- | base | 8453 |
79
- | arbitrum | 42161 |
80
- | optimism | 10 |
81
- | polygon | 137 |
82
- | avalanche | 43114 |
83
- | bsc | 56 |
84
- | linea | 59144 |
85
- | scroll | 534352 |
86
- | zksync | 324 |
87
- | mantle | 5000 |
88
- | blast | 81457 |
89
- | mode | 34443 |
90
- | sepolia | 11155111 |
91
-
92
- ## Rate Limiting
93
-
94
- 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`.
63
+ ## Output Mode
95
64
 
96
- ## Output Formats
97
-
98
- ```bash
99
- # Human-readable (default)
100
- etherscan-cli account balance 0x...
101
-
102
- # JSON (for piping/agents)
103
- etherscan-cli account balance 0x... --json
104
- ```
65
+ Use `--format json` for agent pipelines and tool-calling flows.