DeBank APIdebank.com ↗

"""
DeBank Portfolio API Client using Parse.bot

Track wallet balances and DeFi positions across multiple chains and protocols.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Any


class ParseClient:
    """Client for interacting with DeBank Portfolio API via Parse.bot"""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse client with API credentials.
        
        Args:
            api_key: Parse API key. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "13747502-b591-4e2c-be8b-aebdd0d18362"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict[str, Any]:
        """Make a request to the Parse API.
        
        Args:
            endpoint: The endpoint name (e.g., 'get_full_portfolio_json')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        else:  # POST
            response = requests.post(url, headers=headers, json=params)
        
        response.raise_for_status()
        return response.json()

    def get_full_portfolio_json(
        self,
        address: str,
        min_position_usd: float = 0
    ) -> dict[str, Any]:
        """Get full portfolio JSON for a wallet address.
        
        Includes profile, DeFi positions, and idle tokens across all chains and protocols.
        
        Args:
            address: Wallet address to analyze (e.g., '0xd8...')
            min_position_usd: Exclude positions below this USD value (default: 0)
            
        Returns:
            Portfolio data including wallet overview, protocols, and positions
        """
        return self._call(
            "get_full_portfolio_json",
            method="GET",
            address=address,
            min_position_usd=min_position_usd
        )

    def get_wallet_profile(self, address: str) -> dict[str, Any]:
        """Get basic profile information for a wallet address.
        
        Args:
            address: Wallet address to analyze
            
        Returns:
            Profile data including USD value and follower count
        """
        return self._call(
            "get_wallet_profile",
            method="GET",
            address=address
        )


def analyze_wallet_portfolio(client: ParseClient, wallet_address: str):
    """Analyze a wallet's portfolio with practical insights.
    
    This demonstrates a real workflow:
    1. Fetch wallet profile to get basic info
    2. Get full portfolio to analyze positions
    3. Process and display meaningful insights
    """
    
    print(f"\n{'='*60}")
    print(f"Analyzing Wallet: {wallet_address}")
    print('='*60)
    
    # Step 1: Get wallet profile
    print("\n📊 Fetching wallet profile...")
    profile = client.get_wallet_profile(wallet_address)
    
    print(f"  Portfolio Value: ${profile['usd_value']:,.2f}")
    print(f"  Followers: {profile['follower_count']:,}")
    
    # Step 2: Get full portfolio with minimum position filter
    print("\n🔍 Analyzing portfolio positions (minimum $100)...")
    portfolio = client.get_full_portfolio_json(
        address=wallet_address,
        min_position_usd=100
    )
    
    # Step 3: Extract and process wallet overview
    overview = portfolio.get('wallet_overview', {})
    print(f"\n  Chains Active: {overview.get('num_chains', 0)}")
    print(f"  Protocols Used: {overview.get('num_protocols', 0)}")
    print(f"  Total Net Value: ${overview.get('total_net_value_usd', 0):,.2f}")
    
    # Step 4: Analyze protocols
    protocols = portfolio.get('protocols', [])
    if protocols:
        print(f"\n📈 Top Protocols (by position count):")
        for i, protocol in enumerate(protocols[:5], 1):
            protocol_name = protocol.get('name', 'Unknown')
            protocol_value = protocol.get('portfolio_item_list', [])
            print(f"  {i}. {protocol_name}: {len(protocol_value)} positions")
    
    # Step 5: Analyze exposure buckets if available
    buckets = portfolio.get('exposure_buckets', {})
    if buckets:
        print(f"\n💼 Exposure Distribution:")
        for bucket_type, bucket_data in buckets.items():
            if isinstance(bucket_data, dict):
                bucket_value = bucket_data.get('usd_value', 0)
                bucket_percentage = bucket_data.get('percentage', 0)
                print(f"  {bucket_type}: ${bucket_value:,.2f} ({bucket_percentage:.1f}%)")
    
    # Step 6: Check idle wallet info
    idle_wallet = portfolio.get('idle_wallet', {})
    if idle_wallet:
        idle_value = idle_wallet.get('usd_value', 0)
        if idle_value > 0:
            print(f"\n💤 Idle Assets: ${idle_value:,.2f}")
    
    print(f"\n{'='*60}\n")


if __name__ == "__main__":
    # Initialize client
    client = ParseClient()
    
    # Example wallet addresses to analyze (using common public addresses)
    # You can replace these with actual addresses you want to analyze
    wallet_addresses = [
        "0x1234567890123456789012345678901234567890",
        "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    ]
    
    print("🚀 DeBank Portfolio Analysis Tool")
    print("Powered by Parse.bot API")
    
    for address in wallet_addresses:
        try:
            analyze_wallet_portfolio(client, address)
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 404:
                print(f"⚠️  Wallet {address} not found or has no data")
            else:
                print(f"❌ Error analyzing {address}: {e}")
        except Exception as e:
            print(f"❌ Unexpected error: {e}")