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.

# Verify Node.js version
node --version

Quick Start

Basic wallet lookup on ApeChain:

node scripts/wallet-lookup.js 0x8dd6390be6dc732c92b161b9793a3948b56c0126

Same query with human-readable output:

node scripts/wallet-lookup.js 0x8dd6390be6dc732c92b161b9793a3948b56c0126 --pretty

Cross-chain lookup on Ethereum:

node scripts/wallet-lookup.js 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum --pretty

Commands Reference

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

Wallet Lookup

Purpose: Complete wallet profile with balance, transaction count, and NFT activity summary

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):

{
  "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

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

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

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

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 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:

node scripts/wallet-lookup.js <address>
# Returns formatted JSON

Pretty Format (Human-Readable)

Clean, emoji-enhanced output for human review:

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:

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

{"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 Issues

# If RPC timeouts occur, try different chain:
node scripts/wallet-lookup.js <address> --chain ethereum

# For intermittent chains, retry usually succeeds:
node scripts/wallet-lookup.js <address> --chain polygon

Empty Results

• Verify address is active on the selected chain
• Try different chain if cross-chain activity expected
• Increase block scan range for older activity

Performance Optimization

• Use --limit parameter to reduce transaction history size
• Choose reliable chains (ApeChain, Ethereum, Base, Arbitrum) for consistent performance
• Monitor response times and adjust expectations per chain

Advanced Usage

Batch Analysis

# Analyze multiple addresses
for addr in 0xaddr1 0xaddr2 0xaddr3; do
  echo "=== Analysis for $addr ==="
  node scripts/wallet-lookup.js $addr --pretty
  node scripts/bot-detect.js $addr --pretty
  echo
done

Cross-Chain Investigation

# Check same address across multiple chains
for chain in apechain ethereum base arbitrum; do
  echo "=== $chain ==="
  node scripts/wallet-lookup.js 0x8dd6390be6dc732c92b161b9793a3948b56c0126 --chain $chain --pretty
done

Collection Analysis

# Focus on specific NFT collection
node scripts/nft-holdings.js <address> --collection 0x<contract> --pretty

References

• Chain Details: references/CHAINS.md - Comprehensive chain status and performance data
• Bot Scoring: references/bot-scoring.md - Detailed bot detection methodology

Version History

• v2.0: Added retry logic, input validation, pretty formatting, comprehensive chain documentation
• v1.0: Initial release with basic multi-chain support and bot detection

Need help? Check the references directory for detailed documentation or run any command without arguments for usage instructions.