walletlens

先进的多链钱包分析器，具有美元定价、集合名称、ENS 支持以及跨 8 个 EVM 网络的复杂机器人检测。当您需要：(1) 使用美元估值和自然语言摘要分析钱包配置文件，(2) 检查智能合约详细信息和代币信息，(3) 通过解析的集合名称跟踪 NFT 投资组合，(4) 检查交易历史和转移模式，(5) 通过高级行为分析检测潜在的机器人帐户，(6) 通过全面的见解对地址进行尽职调查，(7) 通过 ENS 域支持调查跨链活动。支持 ApeChain（主）、以太坊、Base、Arbitrum、Polygon、Optimism、Avalanche 和 BNB 链，具有自动重试逻辑和人类可读的输出。

## 概述（中文）

先进的多链钱包分析器，具有美元定价、集合名称、ENS 支持以及跨 8 个 EVM 网络的复杂机器人检测。当您需要：(1) 使用美元估值和自然语言摘要分析钱包配置文件，(2) 检查智能合约详细信息和代币信息，(3) 通过解析的集合名称跟踪 NFT 投资组合，(4) 检查交易历史和转移模式，(5) 通过高级行为分析检测潜在的机器人帐户，(6) 通过全面的见解对地址进行尽职调查，(7) 通过 ENS 域支持调查跨链活动。支持 ApeChain（主）、以太坊、Base、Arbitrum、Polygon、Optimism、Avalanche 和 BNB 链，具有自动重试逻辑和人类可读的输出。

## 原文

# WalletLens

An advanced multi-chain wallet analyzer that provides detailed wallet profiles with USD pricing, human-readable NFT collection names, ENS domain support, and sophisticated bot detection across 8 major EVM networks.

## Key Features

- **Multi-Chain Support**: 8 EVM networks with ApeChain as primary focus
- **USD Price Integration**: Real-time token prices via CoinGecko with graceful degradation
- **ENS Domain Support**: Resolve .eth names across all commands automatically
- **Collection Name Resolution**: Human-readable NFT collection names via Alchemy API + RPC fallback
- **Natural Language Summaries**: Pretty mode includes intelligent wallet insights
- **Advanced Bot Detection**: Sophisticated scoring algorithm to identify automated accounts
- **Reliable Performance**: Automatic retry logic with exponential backoff for network resilience
- **Dual Output Formats**: JSON (default) for agents, `--pretty` flag for human-readable output
- **Minimal Dependencies**: Uses public RPC endpoints, optional Alchemy API key for enhanced features

## Installation

This skill requires Node.js (v16+). No additional dependencies needed - uses built-in `fetch` API.

```bash
# Verify Node.js version
node --version
```

## Quick Start

Basic wallet lookup on ApeChain:
```bash
node scripts/wallet-lookup.js 0x8dd6390be6dc732c92b161b9793a3948b56c0126
```

Same query with human-readable output:
```bash
node scripts/wallet-lookup.js 0x8dd6390be6dc732c92b161b9793a3948b56c0126 --pretty
```

Cross-chain lookup on Ethereum:
```bash
node scripts/wallet-lookup.js 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --pretty
```

## Commands Reference

All commands support `--chain <name>` (defaults to `apechain`) and `--pretty` flag for human-readable output.

### Wallet Lookup
**Purpose**: Complete wallet profile with balance, transaction count, and NFT activity summary

```bash
node scripts/wallet-lookup.js <address> [--chain <name>] [--pretty]
```

**Returns**: Native token balance, transaction count, NFT activity (received/sent), collection count, top holdings

**Example Output (JSON)**:
```json
{
  "address": "0x8dd6390be6dc732c92b161b9793a3948b56c0126",
  "chain": "ApeChain",
  "chainId": 33139,
  "isContract": false,
  "balance": { "APE": 10.1398 },
  "transactionCount": 6352,
  "nftActivity": { "received": 2, "sent": 1 },
  "nftCollectionsHeld": 1,
  "topHoldings": [
    { "contract": "0x6f2a21a8b9cf699d7d3a713a9d7cfbb9e9760f97", "count": 2 }
  ],
  "explorer": "https://apescan.io/address/0x8dd6390be6dc732c92b161b9793a3948b56c0126"
}
```

**Example Output (Pretty)**:
```
🔍 Wallet: 0x8dd6390be6dc732c92b161b9793a3948b56c0126
⛓️  Chain: ApeChain (33139)
💰 Balance: 10.1398 APE
📊 Transactions: 6,352
🎨 NFT Activity: 2 received, 1 sent
📦 Collections: 1
🔗 Explorer: https://apescan.io/address/0x8dd6390be6dc732c92b161b9793a3948b56c0126
```

### Contract Information
**Purpose**: Detailed smart contract analysis including type detection and metadata

```bash
node scripts/contract-info.js <address> [--chain <name>] [--pretty]
```

**Returns**: Contract type (ERC-20/721/1155), name, symbol, total supply, decimals, owner

**Use Cases**: Token research, contract verification, due diligence

### Transaction History
**Purpose**: Recent transfer activity with timestamps and transaction details

```bash
node scripts/tx-history.js <address> [--chain <name>] [--limit <number>] [--pretty]
```

**Returns**: Recent ERC-20 and NFT transfers with direction (IN/OUT), timestamps, contract addresses

**Use Cases**: Activity analysis, transaction tracking, wallet monitoring

### NFT Holdings
**Purpose**: Current NFT collection with detailed token information

```bash
node scripts/nft-holdings.js <address> [--chain <name>] [--collection <contract>] [--pretty]
```

**Returns**: NFTs currently held, grouped by collection, token IDs, transfer statistics

**Use Cases**: NFT portfolio analysis, collection tracking, investment research

### Bot Detection
**Purpose**: Advanced behavioral analysis to identify potential automated accounts

```bash
node scripts/bot-detect.js <address> [--chain <name>] [--pretty]
```

**Returns**: Bot score (0-100), verdict classification, detailed breakdown of scoring factors

**Scoring Factors**:
- **Wrapped Token Usage** (30pts): Frequency of using wrapped native tokens
- **Fast Flipping** (25pts): Quick buy-sell cycles within 24 hours  
- **Fast Listing** (20pts): Immediate listing after purchase (within 30 minutes)
- **Aggressive Pricing** (15pts): Price manipulation patterns
- **Cross-Collection Activity** (10pts): Activity spread across many collections

**Score Interpretation**:
- 75-100: Definite bot
- 60-74: Likely bot  
- 40-59: Suspicious
- 20-39: Probably human
- 0-19: Human

**Use Cases**: Due diligence, airdrop filtering, community verification

## Supported Networks

See [references/CHAINS.md](references/CHAINS.md) for comprehensive chain information including reliability status and performance characteristics.

### Reliable Chains ✅
- **ApeChain** (primary) - Fastest, most reliable
- **Ethereum** - Stable, high-value addresses
- **Base** - Fast L2 performance
- **Arbitrum** - Reliable L2 with official RPC

### Intermittent Chains 🟡
- **Polygon** - May timeout, use with retry logic
- **Optimism** - Occasional performance issues
- **BNB Chain** - Variable reliability
- **Avalanche** - Limited testing, use with caution

## Output Formats

All scripts support two output modes:

### JSON Format (Default)
Structured data ideal for programmatic consumption and agent workflows:
```bash
node scripts/wallet-lookup.js <address>
# Returns formatted JSON
```

### Pretty Format (Human-Readable)
Clean, emoji-enhanced output for human review:
```bash
node scripts/wallet-lookup.js <address> --pretty
# Returns formatted text with emojis and clear sections
```

## Environment Variables

No environment variables required. The skill uses public RPC endpoints configured in `scripts/lib/rpc.js`.

### Custom RPC Endpoints (Advanced)
To use custom RPC endpoints, modify the `CHAINS` object in `scripts/lib/rpc.js`:

```javascript
const CHAINS = {
  apechain: { 
    id: 33139, 
    rpc: "your-custom-rpc-url", 
    name: "ApeChain", 
    symbol: "APE", 
    explorer: "https://apescan.io" 
  },
  // ... other chains
};
```

## Error Handling & Reliability

### Automatic Retry Logic
- 3 retry attempts with exponential backoff (500ms, 1s, 2s)
- 10-second timeout per request
- Graceful failure with clean error messages

### Input Validation
- Address format validation (0x + 40 hex characters)
- Chain name validation against supported list
- Clean error messages without stack traces

### Common Error Messages
```json
{"error": "Invalid address format. Address must be 0x followed by 40 hexadecimal characters"}
{"error": "Unsupported chain \"invalidchain\". Supported chains: apechain, ethereum, base, arbitrum, polygon, optimism, avalanche, bsc"}
{"error": "RPC request timed out after 10000ms"}
```

## Performance & Limitations

### Response Times
- **Fast (< 1s)**: ApeChain, Arbitrum
- **Good (1-2s)**: Ethereum, Base  
- **Variable (1-5s)**: Polygon, Optimism, BSC, Avalanche

### Data Coverage
- **Recent Activity**: 500K-2M blocks depending on chain performance
- **Historical Limitations**: Very old transactions may not appear
- **NFT Detection**: ERC-721 and ERC-1155 support via Transfer events
- **Bot Analysis**: Requires minimum 3 NFT purchases for scoring

### Resource Usage
- **Memory**: Minimal - processes data in streams
- **Network**: Burst usage during queries, then idle
- **CPU**: Low - mostly I/O bound operations

## Troubleshooting

### Network Issue