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.

CODEBLOCK0

Quick Start

Basic wallet lookup on ApeChain:
CODEBLOCK1

Same query with human-readable output:
CODEBLOCK2

Cross-chain lookup on Ethereum:
CODEBLOCK3

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

CODEBLOCK4

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

Example Output (JSON):
CODEBLOCK5

Example Output (Pretty):
CODEBLOCK6

Contract Information

Purpose: Detailed smart contract analysis including type detection and metadata

CODEBLOCK7

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

CODEBLOCK8

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

CODEBLOCK9

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

CODEBLOCK10

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

Pretty Format (Human-Readable)

Clean, emoji-enhanced output for human review: CODEBLOCK12

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:

CODEBLOCK13

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

CODEBLOCK14

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

CODEBLOCK15

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

CODEBLOCK16

Cross-Chain Investigation

CODEBLOCK17

Collection Analysis

CODEBLOCK18

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.