{"id":29029161,"url":"https://github.com/dedinc/cryptoscan","last_synced_at":"2026-01-04T15:15:14.067Z","repository":{"id":300423655,"uuid":"1006137299","full_name":"DedInc/cryptoscan","owner":"DedInc","description":"CryptoScan is a fast, reliable, and extensible Python library for monitoring cryptocurrency payments across multiple blockchain networks. Built with async/await support, HTTP/2 integration, and enterprise-grade reliability.","archived":false,"fork":false,"pushed_at":"2025-06-21T15:31:20.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T16:30:58.735Z","etag":null,"topics":["blockchain","crypto","cryptocurrency","monitoring","payment-acceptance","payment-gateway","payment-integration","payments"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pycryptoscan/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DedInc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T15:21:17.000Z","updated_at":"2025-06-21T15:30:43.000Z","dependencies_parsed_at":"2025-06-21T16:31:03.562Z","dependency_job_id":"a0db0d73-b121-49e8-b04c-d11b3137813c","html_url":"https://github.com/DedInc/cryptoscan","commit_stats":null,"previous_names":["dedinc/cryptoscan"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/DedInc/cryptoscan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DedInc%2Fcryptoscan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DedInc%2Fcryptoscan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DedInc%2Fcryptoscan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DedInc%2Fcryptoscan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DedInc","download_url":"https://codeload.github.com/DedInc/cryptoscan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DedInc%2Fcryptoscan/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262026979,"owners_count":23246955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","crypto","cryptocurrency","monitoring","payment-acceptance","payment-gateway","payment-integration","payments"],"created_at":"2025-06-26T08:06:05.296Z","updated_at":"2026-01-04T15:15:14.060Z","avatar_url":"https://github.com/DedInc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CryptoScan 🚀\n\n**Professional Real-Time Crypto Payment Monitoring Library for Python**\n\nA fast, intelligent, production-ready Python library for monitoring cryptocurrency payments in **real-time** across multiple blockchain networks. Built with WebSocket subscriptions, automatic fallback to polling, HTTP/2 support, and enterprise-grade reliability.\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Async](https://img.shields.io/badge/async-supported-green.svg)](https://docs.python.org/3/library/asyncio.html)\n[![HTTP/2](https://img.shields.io/badge/HTTP%2F2-enabled-brightgreen.svg)](https://httpwg.org/specs/rfc7540.html)\n\n\u003c/div\u003e\n\n## ✨ Features\n\n### Real-Time Monitoring\n- 📡 **WebSocket Subscriptions**: Instant notifications when new blocks arrive\n- 🧠 **Smart Auto-Detection**: Uses WebSocket if available, falls back to polling\n- ⚡ **Zero Configuration**: Create a monitor - it selects the best mode automatically\n- 🔄 **Auto-Reconnect**: Graceful reconnection with exponential backoff\n\n### Network Support\n- 🌐 **Major Blockchains**: Ethereum, BSC, Polygon, Arbitrum, Avalanche, Base, Optimism, Solana, Sui, Osmosis, and more\n- 🔥 **Real-Time Capable**: Major EVM chains, Solana, and Cosmos-based networks\n- 🎯 **Universal Provider**: Single provider works with any blockchain type\n- 📡 **PublicNode Powered**: Access to PublicNode's network infrastructure\n- ✨ **Easy to Extend**: Add any network with simple configuration\n\n### Developer Experience\n- ⚡ **Async/Await**: Built for high-performance async applications\n- 🚀 **HTTP/2**: Optimized API calls with HTTP/2 support\n- 🔒 **Proxy Support**: Full proxy configuration (HTTPS, HTTP, auth)\n- 🎯 **Exact Matching**: Precise payment amount detection with Decimal\n- 📊 **Event System**: Payment and error callbacks with decorators\n- 🛡️ **Production Ready**: Tenacity retry logic, comprehensive error handling\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\npip install pycryptoscan\n```\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def main():\n    # Create a payment monitor\n    # Real-time mode is auto-detected (Ethereum has WebSocket support)\n    monitor = create_monitor(\n        network=\"ethereum\",\n        wallet_address=\"0xD45F36545b373585a2213427C12AD9af2bEFCE18\",\n        expected_amount=\"1.0\",\n        auto_stop=True,\n        min_confirmations=3  # Wait for 3 confirmations before accepting payment\n    )\n\n    # Set up payment handler\n    @monitor.on_payment\n    async def handle_payment(event):\n        payment = event.payment_info\n        print(f\"💰 Payment received: {payment.amount} {payment.currency}\")\n        print(f\"📝 Transaction: {payment.transaction_id}\")\n        print(f\"👤 From: {payment.from_address}\")\n        print(f\"📦 Block: #{payment.block_height}\")\n\n    # Start monitoring (uses WebSocket automatically)\n    await monitor.start()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## 🌐 Supported Networks\n\n### 🔥 Popular Networks (Real-Time WebSocket)\n\n| Network | Symbol | Usage | Network Type |\n|---------|--------|-------|-------------|\n| **Ethereum** | ETH | `ethereum`, `eth` | EVM (Layer 1) |\n| **BSC** | BNB | `bsc`, `bnb` | EVM (Binance) |\n| **Polygon** | MATIC | `polygon`, `matic` | EVM (Layer 2) |\n| **Arbitrum** | ETH | `arbitrum`, `arb` | EVM (Layer 2) |\n| **Avalanche** | AVAX | `avalanche`, `avax` | EVM (Layer 1) |\n| **Base** | ETH | `base` | EVM (Coinbase Layer 2) |\n| **Optimism** | ETH | `optimism`, `op` | EVM (Layer 2) |\n| **Solana** | SOL | `solana`, `sol` | Non-EVM (High Performance) |\n| **Sui** | SUI | `sui` | Move VM |\n| **Osmosis** | OSMO | `osmosis` | Cosmos (DEX) |\n| **Injective** | INJ | `injective`, `inj` | Cosmos (DeFi) |\n\n### 🔵 Additional Networks (Polling Mode)\n\n| Network | Symbol | Usage | Network Type |\n|---------|--------|-------|-------------|\n| **Aptos** | APT | `aptos`, `apt` | Move VM |\n| **Bitcoin** | BTC | `bitcoin`, `btc` | UTXO |\n| **TON** | TON | `ton` | TON VM |\n| **USDT-Tron** | USDT | `usdt_tron`, `trc20` | Tron (TRC-20) |\n\n### ✨ More Networks Available\n\nCryptoScan leverages **PublicNode's infrastructure** with 100+ blockchain networks including:\n- **Layer 2s**: Scroll, Linea, Blast, Mantle, Taiko, opBNB, Fraxtal\n- **Cosmos Ecosystem**: Cosmos Hub, Terra, Kava, Neutron, Celestia, Sei, dYdX\n- **Other EVMs**: Gnosis, Moonbeam, Celo, Cronos, PulseChain, Sonic\n- **And many more...**\n\n\u003e 🔥 **Real-Time**: Instant WebSocket notifications when new blocks arrive  \n\u003e 🔵 **Polling**: HTTP checks every N seconds (fast and reliable)  \n\u003e ✨ **Easy to Add**: Configure any PublicNode network using registration functions\n\n## 🔧 Network Registration\n\nCryptoScan comes with **common networks pre-registered** (Ethereum, BSC, Polygon, Solana). You can add custom networks in several ways:\n\n### 🚀 Pre-Registered Networks (Ready to Use)\n\nThese networks are automatically available:\n\n```python\nfrom cryptoscan import list_networks\nprint(\"Available networks:\", list_networks())\n# Output: ['binance', 'bnb', 'bsc', 'eth', 'ethereum', 'matic', 'polygon', 'sol', 'solana']\n\n# Use directly by name or alias\nmonitor = create_monitor(\"ethereum\", \"0x...\", \"1.0\")  # Name\nmonitor = create_monitor(\"eth\", \"0x...\", \"1.0\")       # Alias\nmonitor = create_monitor(\"polygon\", \"0x...\", \"1.0\")   # Name\nmonitor = create_monitor(\"matic\", \"0x...\", \"1.0\")     # Alias\n```\n\n### 📝 Register Custom Networks\n\n#### Method 1: Quick Registration\n```python\nfrom cryptoscan import register_network, create_network_config\n\n# Register once, use everywhere\nscroll_config = create_network_config(\n    name=\"scroll\",\n    symbol=\"ETH\",\n    rpc_url=\"https://scroll-rpc.publicnode.com\",\n    ws_url=\"wss://scroll-rpc.publicnode.com\",  # Optional: enables real-time\n    aliases=[\"scrl\"],\n    address_pattern=r'^0x[a-fA-F0-9]{40}$',  # EVM address format\n    decimals=18,\n    chain_type=\"evm\"\n)\n\nregister_network(scroll_config)\n\n# Now use anywhere in your app\nmonitor = create_monitor(\"scroll\", \"0x...\", \"1.0\")  # By name\nmonitor = create_monitor(\"scrl\", \"0x...\", \"1.0\")    # By alias\n```\n\n#### Method 2: Register Multiple Networks\n```python\nfrom cryptoscan import register_network, NetworkConfig\n\n# Define multiple networks\ncustom_networks = [\n    NetworkConfig(\n        name=\"blast\", symbol=\"ETH\",\n        rpc_url=\"https://blast-rpc.publicnode.com\",\n        ws_url=\"wss://blast-rpc.publicnode.com\",\n        aliases=[\"blst\"], chain_type=\"evm\", decimals=18\n    ),\n    NetworkConfig(\n        name=\"linea\", symbol=\"ETH\",\n        rpc_url=\"https://linea-rpc.publicnode.com\",\n        ws_url=\"wss://linea-rpc.publicnode.com\",\n        chain_type=\"evm\", decimals=18\n    )\n]\n\n# Register all at once\nfor network in custom_networks:\n    register_network(network)\n\n# Use them\nmonitor = create_monitor(\"blast\", \"0x...\", \"1.0\")\nmonitor = create_monitor(\"linea\", \"0x...\", \"1.0\")\n```\n\n### ⚡ Alternative: Direct Usage Without Registration\n\nSkip registration by providing `rpc_url` directly:\n\n```python\n# No registration needed - works immediately\nmonitor = create_monitor(\n    network=\"any-name\",  # Can be anything\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    rpc_url=\"https://your-rpc-endpoint.com\",\n    ws_url=\"wss://your-ws-endpoint.com\"  # Optional\n)\n```\n\n**💡 Pro Tips:**\n- Registration is optional - use `rpc_url` parameter to skip it\n- Pre-registered networks are available immediately after `import cryptoscan`\n- Use `list_networks()` to see all available networks\n- Aliases let you use short names (e.g., \"eth\" instead of \"ethereum\")\n- Find RPC endpoints at [PublicNode.com](https://publicnode.com)\n\n### 🌐 Real-World Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e🔥 Scroll (EVM Layer 2)\u003c/summary\u003e\n\n```python\nmonitor = create_monitor(\n    network=\"scroll\",\n    wallet_address=\"0xYourAddress\",\n    expected_amount=\"1.0\",\n    rpc_url=\"https://scroll-rpc.publicnode.com\",\n    ws_url=\"wss://scroll-rpc.publicnode.com\"\n)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🌟 Celestia (Cosmos)\u003c/summary\u003e\n\n```python\nmonitor = create_monitor(\n    network=\"celestia\",\n    wallet_address=\"celestia1...\",  # Cosmos address format\n    expected_amount=\"1.0\",\n    rpc_url=\"https://celestia-rpc.publicnode.com\",\n    ws_url=\"wss://celestia-rpc.publicnode.com\"\n)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e🌊 Sei (Parallel Execution)\u003c/summary\u003e\n\n```python\nmonitor = create_monitor(\n    network=\"sei\",\n    wallet_address=\"sei1...\",\n    expected_amount=\"1.0\",\n    rpc_url=\"https://sei-rpc.publicnode.com\",\n    ws_url=\"wss://sei-rpc.publicnode.com\"\n)\n```\n\u003c/details\u003e\n\n## 📚 Examples\n\n### Real-Time Monitoring (Auto-Detected)\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def realtime_example():\n    # WebSocket real-time monitoring (auto-detected)\n    monitor = create_monitor(\n        network=\"polygon\",  # Has wss:// - uses real-time\n        wallet_address=\"0xD45F36545b373585a2213427C12AD9af2bEFCE18\",\n        expected_amount=\"10.0\",\n        auto_stop=True\n    )\n    \n    @monitor.on_payment\n    async def on_payment(event):\n        print(f\"⚡ Instant notification from new block\")\n        print(f\"💰 {event.payment_info.amount} MATIC received\")\n        print(f\"📦 Block #{event.payment_info.block_height}\")\n    \n    await monitor.start()\n\nasyncio.run(realtime_example())\n```\n\n### Multi-Chain Real-Time Monitoring\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def multi_chain():\n    # Monitor multiple chains simultaneously\n    monitors = [\n        create_monitor(\"ethereum\", \"0x...\", \"1.0\", monitor_id=\"eth\"),\n        create_monitor(\"bsc\", \"0x...\", \"0.5\", monitor_id=\"bsc\"),\n        create_monitor(\"polygon\", \"0x...\", \"10.0\", monitor_id=\"matic\"),\n    ]\n    \n    # Unified handler\n    async def on_payment(event):\n        print(f\"💰 Payment on {event.monitor_id}: {event.payment_info.amount}\")\n    \n    for m in monitors:\n        m.on_payment(on_payment)\n    \n    await asyncio.gather(*[m.start() for m in monitors])\n\nasyncio.run(multi_chain())\n```\n\n### Basic Payment Monitoring\n\n```python\nimport asyncio\nfrom decimal import Decimal\nfrom cryptoscan import create_monitor\n\nasync def bitcoin_example():\n    monitor = create_monitor(\n        network=\"bitcoin\",  # or \"btc\"\n        wallet_address=\"3DVSCqZdrNJHyu9Le7Sepdh1KgQTNR8reG\",\n        expected_amount=Decimal(\"0.00611813\"),\n        poll_interval=30.0,\n        auto_stop=True\n    )\n\n    @monitor.on_payment\n    async def on_payment(event):\n        payment = event.payment_info\n        print(f\"💰 Payment received: {payment.amount} {payment.currency}\")\n        print(f\"   Transaction: {payment.transaction_id}\")\n        print(f\"   From: {payment.from_address}\")\n\n    await monitor.start()\n\nasyncio.run(bitcoin_example())\n```\n\n### Payment with Confirmation Requirements\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def confirmation_example():\n    # Monitor payment and wait for 6 confirmations for security\n    monitor = create_monitor(\n        network=\"ethereum\",\n        wallet_address=\"0xD45F36545b373585a2213427C12AD9af2bEFCE18\",\n        expected_amount=\"100.0\",\n        min_confirmations=6,  # Require 6 confirmations\n        auto_stop=True\n    )\n\n    @monitor.on_payment\n    async def on_payment(event):\n        payment = event.payment_info\n        print(f\"✅ Payment confirmed with {payment.confirmations} confirmations\")\n        print(f\"💰 Amount: {payment.amount} {payment.currency}\")\n        print(f\"🔒 Secure payment received!\")\n\n    await monitor.start()\n\nasyncio.run(confirmation_example())\n```\n\n### Multi-Network Monitoring\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def multi_network_example():\n    # Monitor multiple networks simultaneously\n    btc_monitor = create_monitor(\n        network=\"bitcoin\",\n        wallet_address=\"3DVSCqZdrNJHyu9Le7Sepdh1KgQTNR8reG\",\n        expected_amount=\"0.00611813\"\n    )\n\n    usdt_monitor = create_monitor(\n        network=\"usdt_tron\",\n        wallet_address=\"TVRzaRqX9soeRpcJVT6zCAZjGtLtQXacCR\",\n        expected_amount=\"200.0\"\n    )\n\n    # Unified payment handler\n    async def handle_payment(event):\n        payment = event.payment_info\n        print(f\"💰 {payment.currency} payment: {payment.amount}\")\n\n    btc_monitor.on_payment(handle_payment)\n    usdt_monitor.on_payment(handle_payment)\n\n    # Start all monitors\n    await asyncio.gather(\n        btc_monitor.start(),\n        usdt_monitor.start()\n    )\n\nasyncio.run(multi_network_example())\n```\n\n## 🔧 Advanced Configuration\n\n### Smart Real-Time Detection\n\n```python\nfrom cryptoscan import create_monitor\n\n# Auto-detects real-time (default behavior)\nmonitor = create_monitor(\n    network=\"ethereum\",  # Has wss:// - uses real-time\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\"\n)  # Real-time mode enabled\n\n# Custom WebSocket endpoint\nmonitor = create_monitor(\n    network=\"ethereum\",\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    rpc_url=\"wss://eth.llamarpc.com\"  # Detects wss:// - enables real-time\n)\n\n# Force polling mode (if needed)\nmonitor = create_monitor(\n    network=\"ethereum\",\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    realtime=False  # Explicitly use polling\n)\n```\n\n### User Configuration (Recommended)\n\n```python\nfrom cryptoscan import create_monitor, create_user_config, ProxyConfig\n\n# Create user configuration with proxy and custom settings\nuser_config = create_user_config(\n    proxy_url=\"https://proxy.example.com:8080\",\n    proxy_auth=\"username:password\",\n    timeout=60,\n    max_retries=5,\n    ssl_verify=True\n)\n\nmonitor = create_monitor(\n    network=\"ethereum\",\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    user_config=user_config\n)\n```\n\n### Direct UserConfig Creation\n\n```python\nfrom cryptoscan import create_monitor, UserConfig, ProxyConfig\n\n# Create proxy configuration\nproxy_config = ProxyConfig(\n    https_proxy=\"https://proxy.example.com:8080\",\n    proxy_auth=\"username:password\",\n    proxy_headers={\"Custom-Header\": \"value\"}\n)\n\n# Create user configuration\nuser_config = UserConfig(\n    proxy_config=proxy_config,\n    timeout=60,\n    max_retries=5,\n    retry_delay=2.0,\n    ssl_verify=True,\n    connector_limit=50\n)\n\nmonitor = create_monitor(\n    network=\"solana\",\n    wallet_address=\"39eda9Jzabcr1HPkmjt7sZPCznZqngkfXZn1utwE8uwk\",\n    expected_amount=\"0.000542353\",\n    user_config=user_config\n)\n```\n\n\n\n### Multiple Payment Monitoring\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor\n\nasync def multi_network_monitoring():\n    # Monitor multiple networks simultaneously\n    monitors = []\n\n    # Bitcoin monitor\n    btc_monitor = create_monitor(\n        network=\"bitcoin\",\n        wallet_address=\"3DVSCqZdrNJHyu9Le7Sepdh1KgQTNR8reG\",\n        expected_amount=\"0.001\",\n        monitor_id=\"btc-payment-1\"\n    )\n\n    # Ethereum monitor\n    eth_monitor = create_monitor(\n        network=\"ethereum\",\n        wallet_address=\"0xD45F36545b373585a2213427C12AD9af2bEFCE18\",\n        expected_amount=\"0.15\",\n        monitor_id=\"eth-payment-1\"\n    )\n\n    # Unified payment handler\n    async def handle_any_payment(event):\n        payment = event.payment_info\n        monitor_id = event.monitor_id\n        print(f\"💰 Payment on {monitor_id}: {payment.amount} {payment.currency}\")\n\n    btc_monitor.on_payment(handle_any_payment)\n    eth_monitor.on_payment(handle_any_payment)\n\n    # Start all monitors\n    await asyncio.gather(\n        btc_monitor.start(),\n        eth_monitor.start()\n    )\n\nasyncio.run(multi_network_monitoring())\n```\n\n## 🛡️ Error Handling \u0026 Reliability\n\n### Robust Error Handling\n\n```python\nimport asyncio\nfrom cryptoscan import create_monitor, NetworkError, PaymentNotFoundError\n\nasync def reliable_monitoring():\n    monitor = create_monitor(\n        network=\"bitcoin\",\n        wallet_address=\"3DVSCqZdrNJHyu9Le7Sepdh1KgQTNR8reG\",\n        expected_amount=\"0.001\",\n        max_transactions=20,  # Check more transactions\n        poll_interval=30.0\n    )\n\n    @monitor.on_payment\n    async def on_payment(event):\n        print(f\"✅ Payment confirmed: {event.payment_info.amount} BTC\")\n\n    @monitor.on_error\n    async def on_error(event):\n        error = event.error\n        if isinstance(error, NetworkError):\n            print(f\"🌐 Network error: {error.message}\")\n            print(\"🔄 Will retry automatically...\")\n        else:\n            print(f\"❌ Unexpected error: {error}\")\n\n    try:\n        await monitor.start()\n    except Exception as e:\n        print(f\"💥 Monitor failed: {e}\")\n    finally:\n        await monitor.stop()\n\nasyncio.run(reliable_monitoring())\n```\n\n### Timeout and Retry Configuration\n\n```python\nfrom cryptoscan import create_monitor\n\n# High-reliability configuration\nmonitor = create_monitor(\n    network=\"ethereum\",\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    poll_interval=15.0,\n    timeout=60,  # 60 second timeout\n    max_retries=5,  # Retry failed requests 5 times\n    auto_stop=True\n)\n```\n\n## 🔌 Integration Examples\n\n### Aiogram v3.x (Telegram Bot) Integration\n\n```python\nfrom aiogram import Bot, Dispatcher\nfrom aiogram.types import Message\nfrom aiogram.filters import Command\nfrom cryptoscan import create_monitor\nimport asyncio\nimport logging\n\n# Configure logging\nlogging.basicConfig(level=logging.INFO)\n\n# Initialize bot and dispatcher\nbot = Bot(token=\"YOUR_BOT_TOKEN\")\ndp = Dispatcher()\n\n@dp.message(Command(\"start\"))\nasync def start_handler(message: Message):\n    await message.answer(\n        \"🚀 CryptoScan Bot\\n\\n\"\n        \"Monitor crypto payments with ease!\\n\"\n        \"Usage: /monitor \u003cnetwork\u003e \u003caddress\u003e \u003camount\u003e\\n\\n\"\n        \"Pre-registered: ethereum, bsc, polygon, solana\\n\"\n        \"Or use any network with custom RPC URL\"\n    )\n\n@dp.message(Command(\"monitor\"))\nasync def monitor_payment(message: Message):\n    # Parse command: /monitor ethereum 0x... 1.0\n    args = message.text.split()[1:]\n    if len(args) != 3:\n        await message.answer(\n            \"❌ Invalid format!\\n\"\n            \"Usage: /monitor \u003cnetwork\u003e \u003caddress\u003e \u003camount\u003e\\n\\n\"\n            \"Example: /monitor ethereum 0xD45F36545b373585a2213427C12AD9af2bEFCE18 1.0\"\n        )\n        return\n\n    network, address, amount = args\n\n    try:\n        monitor = create_monitor(\n            network=network,\n            wallet_address=address,\n            expected_amount=amount,\n            auto_stop=True\n        )\n\n        @monitor.on_payment\n        async def on_payment(event):\n            payment = event.payment_info\n            await message.answer(\n                f\"✅ Payment Received!\\n\\n\"\n                f\"💰 Amount: {payment.amount} {payment.currency}\\n\"\n                f\"🔗 Transaction: {payment.transaction_id[:16]}...\\n\"\n                f\"👤 From: {payment.from_address[:16]}...\\n\"\n                f\"⏰ Time: {payment.timestamp}\"\n            )\n\n        @monitor.on_error\n        async def on_error(event):\n            await message.answer(f\"❌ Monitoring error: {event.error}\")\n\n        await message.answer(\n            f\"🔍 Monitoring started!\\n\\n\"\n            f\"Network: {network.upper()}\\n\"\n            f\"Amount: {amount}\\n\"\n            f\"Address: {address[:16]}...\\n\\n\"\n            f\"I'll notify you when payment is received!\"\n        )\n\n        # Start monitoring in background\n        asyncio.create_task(monitor.start())\n\n    except Exception as e:\n        await message.answer(f\"❌ Error: {str(e)}\")\n\nasync def main():\n    # Start polling\n    await dp.start_polling(bot)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## 📚 API Reference\n\n### Core Functions\n\n#### `create_monitor()`\n\nCreates a payment monitor for any supported network with smart real-time detection.\n\n```python\ndef create_monitor(\n    network: str,                    # Network name: \"ethereum\", \"polygon\", \"solana\", etc.\n    wallet_address: str,             # Wallet address to monitor\n    expected_amount: str | Decimal,  # Expected payment amount (exact match)\n    poll_interval: float = 15.0,     # Seconds between checks (polling mode)\n    max_transactions: int = 10,      # Max transactions to check per poll\n    auto_stop: bool = False,         # Stop after finding payment\n    rpc_url: str = None,             # Custom RPC URL (can be wss://)\n    realtime: bool = None,           # None=auto-detect, True=force, False=polling\n    min_confirmations: int = 1,      # Minimum confirmations required (default: 1)\n    **kwargs                         # Additional configuration\n) -\u003e PaymentMonitor\n```\n\n**Real-Time Detection Logic:**\n- `realtime=None` (default): Auto-detects based on network WebSocket availability\n- `rpc_url` starts with `wss://`: Uses real-time mode\n- Network has WebSocket configured: Uses real-time mode\n- Otherwise: Uses polling mode\n- Force mode with `realtime=True` or `realtime=False`\n\n**Confirmation Handling:**\n- `min_confirmations=1` (default): Accepts payment after 1 confirmation\n- Set higher values for critical payments (e.g., `min_confirmations=3` or `6`)\n- Monitor will only trigger payment callback once confirmations meet the threshold\n\n### PaymentMonitor Class\n\n#### Methods\n\n- `async start()` - Start monitoring for payments\n- `async stop()` - Stop monitoring\n- `on_payment(callback)` - Register payment event handler\n- `on_error(callback)` - Register error event handler\n\n#### Properties\n\n- `provider` - Access to the underlying network provider\n- `is_running` - Check if monitor is currently running\n- `monitor_id` - Unique identifier for this monitor\n\n### PaymentInfo Class\n\nPayment information returned when a payment is detected.\n\n```python\n@dataclass\nclass PaymentInfo:\n    transaction_id: str      # Transaction hash/ID\n    wallet_address: str      # Receiving wallet address\n    amount: Decimal         # Payment amount in main units\n    currency: str           # Currency symbol (BTC, ETH, etc.)\n    status: PaymentStatus   # PENDING, CONFIRMED, FAILED\n    timestamp: datetime     # Transaction timestamp\n    block_height: int       # Block number (if available)\n    confirmations: int      # Number of confirmations\n    fee: Decimal           # Transaction fee (if available)\n    from_address: str      # Sender address\n    to_address: str        # Receiver address\n    raw_data: dict         # Raw API response data\n```\n\n### UniversalProvider\n\nDirect access to the universal provider for advanced use cases.\n\n```python\nfrom cryptoscan import UniversalProvider, NetworkConfig\n\n# Create provider for any network\nnetwork_config = NetworkConfig(\n    name=\"ethereum\",\n    symbol=\"ETH\",\n    rpc_url=\"https://ethereum-rpc.publicnode.com\",\n    ws_url=\"wss://ethereum-rpc.publicnode.com\",\n    chain_type=\"evm\",\n    decimals=18\n)\n\nprovider = UniversalProvider(network=network_config)\nawait provider.connect()\n\n# Get recent transactions\ntransactions = await provider.get_recent_transactions(\n    \"0xD45F36545b373585a2213427C12AD9af2bEFCE18\",\n    limit=10\n)\n\nawait provider.close()\n```\n\n## 🔧 Configuration\n\n### Proxy Configuration\n\n```python\nfrom cryptoscan import create_monitor, create_user_config\n\n# Simple proxy configuration\nmonitor = create_monitor(\n    network=\"ethereum\",\n    wallet_address=\"0x...\",\n    expected_amount=\"1.0\",\n    user_config=create_user_config(\n        proxy_url=\"https://proxy.example.com:8080\",\n        proxy_auth=\"username:password\",\n        timeout=60,\n        max_retries=5\n    )\n)\n\n# Advanced proxy configuration\nfrom cryptoscan import UserConfig, ProxyConfig\n\nproxy_config = ProxyConfig(\n    https_proxy=\"https://proxy.example.com:8080\",\n    http_proxy=\"http://proxy.example.com:8080\",\n    proxy_auth=\"username:password\",\n    proxy_headers={\"Custom-Header\": \"value\"}\n)\n\nuser_config = UserConfig(\n    proxy_config=proxy_config,\n    timeout=60,\n    max_retries=5\n)\n\nmonitor = create_monitor(\n    network=\"solana\",\n    wallet_address=\"39eda9Jzabcr1HPkmjt7sZPCznZqngkfXZn1utwE8uwk\",\n    expected_amount=\"0.1\",\n    user_config=user_config\n)\n```\n\n## 🚀 Performance\n\n### Real-Time vs Polling\n\n| Feature | Real-Time (WebSocket) | Polling (HTTP) |\n|---------|----------------------|----------------|\n| **Latency** | \u003c1s (instant) | 15-30s (poll interval) |\n| **Efficiency** | Push-based | Pull-based |\n| **Load** | Single connection | Multiple requests |\n| **Networks** | When ws_url provided | All networks |\n| **Auto-Detect** | ✅ Yes | ✅ Yes |\n\n### Performance Tips\n\n1. **Real-Time First**: Use networks with WebSocket for instant notifications\n2. **HTTP/2**: All HTTP calls use HTTP/2 for better performance\n3. **Connection Pooling**: Automatic connection reuse reduces overhead\n4. **Tenacity Retry**: Intelligent exponential backoff for high reliability\n5. **Async Concurrent**: Use `asyncio.gather()` for multi-chain monitoring\n6. **Optimize Polling**: Balance poll interval with responsiveness needs\n\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Made with ❤️ for the crypto community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedinc%2Fcryptoscan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdedinc%2Fcryptoscan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdedinc%2Fcryptoscan/lists"}