Add insider trading detection and wallet analysis tools

[guzus]

Summary

Adds comprehensive insider trading detection and wallet analysis capabilities to Dr. Manhattan. This enables users to analyze trading patterns, detect suspicious activity, and compare wallets for coordinated trading behavior.

Key Changes

• New MCP Tools (4 tools added):

  • fetch_wallet_trades - Retrieve all trades for a specific wallet address
  • analyze_wallet_performance - Calculate trading metrics and patterns (win rate, market exposure, timing analysis)
  • detect_insider_signals - Identify suspicious trading patterns (market concentration, large trades, burst trading, one-sided trading)
  • compare_wallets - Compare trading patterns across multiple wallets to detect coordination

• New Module: dr_manhattan/mcp/tools/insider_tools.py

  • Implements wallet analysis with configurable thresholds (market concentration >50%, large trades >3x average, etc.)
  • Risk scoring system (low/medium/high) based on detected signals
  • Comprehensive error handling and data validation

• Example Script: examples/verify_insider.py

  • CLI tool for analyzing wallet trading patterns
  • Supports multiple modes: fetch trades, analyze performance, detect signals, compare wallets
  • Human-readable output with formatted currency and timestamps
  • JSON output option for programmatic use

• Documentation: Updated SKILL.md

  • Added "Insider Verification" section documenting all 4 new tools
  • Added "Verify Insider Trading Activity" workflow example
  • Added example CLI commands

Implementation Details

• Risk Scoring: Signals are weighted (high=3pts, medium=2pts, low=1pt) to determine overall risk level
• Thresholds: All analysis thresholds are defined as module constants for easy configuration
• Data Validation: Wallet addresses must be valid Ethereum addresses (0x prefix), exchanges validated against supported list
• Polymarket Focus: Currently supports Polymarket only; extensible for other exchanges
• Minimal Data: Wallet analysis uses only public trade data; no private/sensitive information required

https://claude.ai/code/session_01FfEDtiNoQgJkCjJyw63Wnm

[netlify]

✅ Deploy Preview for dr-manhattan-oss canceled.

Name	Link
🔨 Latest commit	22e42a7
🔍 Latest deploy log	https://app.netlify.com/projects/dr-manhattan-oss/deploys/6981b13999e5840008d38a25

[claude]

Pull Request Review: Insider Trading Detection Tools

Summary

This PR adds comprehensive insider trading detection and wallet analysis capabilities through 4 new MCP tools and a CLI example script. The implementation is well-structured and follows the repository conventions.

Code Quality & Best Practices

Strengths

• Clean Code Structure: The new insider_tools.py module is well-organized with clear function signatures and comprehensive docstrings
• Follows CLAUDE.md: Configuration constants are properly defined in code per Rule 4
• Good Documentation: All functions have detailed docstrings with Args, Returns, and Example sections
• Consistent Error Handling: Uses translate_error wrapper consistently
• Type Hints: Proper use of type annotations

Areas for Improvement

1. Unused Import (insider_tools.py:4) - timedelta and timezone are imported but never used
2. Unused Constants (insider_tools.py:19-20) - HIGH_WIN_RATE_THRESHOLD and SUSPICIOUS_TIMING_HOURS are defined but never referenced
3. Example Script Code Duplication - The example script duplicates detection logic from insider_tools.py, violating DRY principles

Potential Bugs & Issues

Critical Issues

1. Potential Empty Set Error (insider_tools.py:492-493)
   If all market_sets are empty after filtering, min() will raise ValueError. Add a check for non_empty_sets first.

2. Wallet Address Validation (insider_tools.py:61-62) - Only checks for 0x prefix but not length or hex characters. Should use proper regex validation like HEX_ADDRESS_PATTERN in validation.py

Medium Issues

3. Inconsistent Minimum Trade Threshold - One-sided trading check requires >= 20 trades (line 376) but function only requires 5 trades to proceed
4. Multiple Data Passes (insider_tools.py:163-240) - analyze_wallet_performance makes multiple passes over trades_data. Consider consolidating

Security Concerns

1. Input Validation - Max limit of 5000 trades could be resource-intensive
2. Error Message Information Disclosure (line 478) - Exposing raw error messages could leak sensitive info
3. No Rate Limiting - Public API calls lack explicit rate limiting documentation

Test Coverage - CRITICAL GAP

No tests for the new functionality. The PR adds 926 lines of code but zero test coverage.

Recommended:

• Unit tests for insider_tools.py (valid inputs, error handling, edge cases)
• Integration tests for MCP server tool registration
• Example script tests for CLI parsing and output formatting

Recommendations

Before Merge (Critical)

1. Fix potential empty set bug in compare_wallets
2. Remove unused imports and constants
3. Add basic unit tests
4. Improve wallet address validation

Nice to Have

1. Consolidate data processing for performance
2. Reduce code duplication in example script
3. Add comprehensive test coverage

Conclusion

This is a well-implemented feature that adds valuable functionality. The code is clean, well-documented, and follows repository conventions. However, it needs test coverage before merging.

Recommendation: Request changes to address critical bugs and add tests, then approve.