web3-agent-kit 0.7.0__tar.gz → 0.8.0__tar.gz

{web3_agent_kit-0.7.0/web3_agent_kit.egg-info → web3_agent_kit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: web3-agent-kit
-Version: 0.7.0
+Version: 0.8.0
 Summary: Open-source framework for building autonomous AI agents that interact with blockchain networks
 Author-email: Maulana <khasbim240803@gmail.com>
 License: MIT
@@ -68,6 +68,7 @@ Building AI agents that interact with blockchains is **hard**. You need to juggl
 | **Security** | Manual approval checks | Auto-scan & revoke risky approvals |
 | **Alerts** | Manual whale tracking | Auto-monitor wallets, instant alerts |
 | **Multi-wallet** | Manage keys manually | Batch ops, consolidated portfolio, wallet groups |
+| **Airdrops** | Manual quest hunting | Auto-track campaigns, multi-wallet farming, Sybil-safe |
 | **Extensibility** | Hard-coded logic | Plugin system — community can extend anything |
 | **Error Handling** | Manual retry logic | Auto-fallback across LLM providers & RPCs |
 
@@ -141,6 +142,7 @@ Building AI agents that interact with blockchains is **hard**. You need to juggl
 | **Wallet Watcher** | ✅ | ❌ | ❌ | ❌ |
 | **Yield Optimizer** | ✅ | ❌ | ❌ | ❌ |
 | **Multi-Wallet** | ✅ | ❌ | ❌ | ❌ |
+| **Airdrops** | ✅ | ❌ | ❌ | ❌ |
 | **Plugin System** | ✅ | ❌ | ❌ | ❌ |
 | **Safety Rails** | ✅ Governor | ❌ | ❌ | ❌ |
 | **Natural Language** | ✅ | Partial | ❌ | ❌ |
@@ -403,6 +405,54 @@ print(summary)
 
 ---
 
+## 🪂 Airdrop Automation
+
+Discover, track, and complete airdrop campaigns across multiple platforms:
+
+```python
+from web3_agent_kit.airdrop import (
+    GalxePlatform, ZealyPlatform, GleamCampaign,
+    AirdropTracker, AirdropFarmer, SocialTaskManager,
+    PlatformConfig, TaskType, SybilAvoidanceConfig,
+)
+
+# Track campaigns across platforms
+tracker = AirdropTracker()
+
+# Galxe integration
+galxe = GalxePlatform(config=PlatformConfig(api_key="your_key"))
+galxe.login({"api_key": "your_key"})
+tasks = galxe.get_tasks("campaign_id")
+for task in tasks:
+    galxe.complete_task(task)
+
+# Social task automation
+social = SocialTaskManager()
+social.complete_social_task(TaskType.SOCIAL_TWITTER_FOLLOW, "defi_project")
+social.complete_social_task(TaskType.SOCIAL_DISCORD_JOIN, "https://discord.gg/invite")
+
+# Multi-wallet farming with Sybil avoidance
+farmer = AirdropFarmer(
+    wallet_manager=manager,
+    group="airdrop",
+    config=SybilAvoidanceConfig(
+        min_delay_between_wallets=60,
+        max_delay_between_wallets=600,
+        max_tasks_per_wallet_per_day=10,
+    ),
+)
+results = farmer.farm_campaign(campaign, execute=True)
+
+# Export report
+tracker.export_json("./airdrop_report.json")
+tracker.export_csv("./airdrop_report.csv")
+```
+
+**Supported platforms:** Gleam.io, Zealy (Crew3), Galxe (Project Galaxy)
+**Social tasks:** Twitter, Discord, Telegram, YouTube, GitHub
+
+---
+
 ## 🌉 Bridge Agent
 
 Cross-chain transfers via Li.Fi and Socket:
@@ -533,6 +583,15 @@ web3-agent-kit/
 │   ├── bridge.py           # Cross-chain bridge agent
 │   ├── yield_optimizer.py  # Yield optimizer + auto-compound
 │   ├── multi_wallet.py     # Multi-wallet manager + batch ops
+│   ├── airdrop/            # Airdrop automation module
+│   │   ├── __init__.py     # Package exports
+│   │   ├── base.py         # Base platform abstraction
+│   │   ├── gleam.py        # Gleam.io automation
+│   │   ├── zealy.py        # Zealy quest automation
+│   │   ├── galxe.py        # Galxe campaign automation
+│   │   ├── social.py       # Social task helpers
+│   │   ├── tracker.py      # Airdrop tracker
+│   │   └── multi_wallet.py # Multi-wallet farming
 │   ├── plugins/
 │   │   ├── __init__.py     # Plugin system (base, registry, manager)
 │   │   └── examples/

{web3_agent_kit-0.7.0 → web3_agent_kit-0.8.0}/README.md

@@ -34,6 +34,7 @@ Building AI agents that interact with blockchains is **hard**. You need to juggl
 | **Security** | Manual approval checks | Auto-scan & revoke risky approvals |
 | **Alerts** | Manual whale tracking | Auto-monitor wallets, instant alerts |
 | **Multi-wallet** | Manage keys manually | Batch ops, consolidated portfolio, wallet groups |
+| **Airdrops** | Manual quest hunting | Auto-track campaigns, multi-wallet farming, Sybil-safe |
 | **Extensibility** | Hard-coded logic | Plugin system — community can extend anything |
 | **Error Handling** | Manual retry logic | Auto-fallback across LLM providers & RPCs |
 
@@ -107,6 +108,7 @@ Building AI agents that interact with blockchains is **hard**. You need to juggl
 | **Wallet Watcher** | ✅ | ❌ | ❌ | ❌ |
 | **Yield Optimizer** | ✅ | ❌ | ❌ | ❌ |
 | **Multi-Wallet** | ✅ | ❌ | ❌ | ❌ |
+| **Airdrops** | ✅ | ❌ | ❌ | ❌ |
 | **Plugin System** | ✅ | ❌ | ❌ | ❌ |
 | **Safety Rails** | ✅ Governor | ❌ | ❌ | ❌ |
 | **Natural Language** | ✅ | Partial | ❌ | ❌ |
@@ -369,6 +371,54 @@ print(summary)
 
 ---
 
+## 🪂 Airdrop Automation
+
+Discover, track, and complete airdrop campaigns across multiple platforms:
+
+```python
+from web3_agent_kit.airdrop import (
+    GalxePlatform, ZealyPlatform, GleamCampaign,
+    AirdropTracker, AirdropFarmer, SocialTaskManager,
+    PlatformConfig, TaskType, SybilAvoidanceConfig,
+)
+
+# Track campaigns across platforms
+tracker = AirdropTracker()
+
+# Galxe integration
+galxe = GalxePlatform(config=PlatformConfig(api_key="your_key"))
+galxe.login({"api_key": "your_key"})
+tasks = galxe.get_tasks("campaign_id")
+for task in tasks:
+    galxe.complete_task(task)
+
+# Social task automation
+social = SocialTaskManager()
+social.complete_social_task(TaskType.SOCIAL_TWITTER_FOLLOW, "defi_project")
+social.complete_social_task(TaskType.SOCIAL_DISCORD_JOIN, "https://discord.gg/invite")
+
+# Multi-wallet farming with Sybil avoidance
+farmer = AirdropFarmer(
+    wallet_manager=manager,
+    group="airdrop",
+    config=SybilAvoidanceConfig(
+        min_delay_between_wallets=60,
+        max_delay_between_wallets=600,
+        max_tasks_per_wallet_per_day=10,
+    ),
+)
+results = farmer.farm_campaign(campaign, execute=True)
+
+# Export report
+tracker.export_json("./airdrop_report.json")
+tracker.export_csv("./airdrop_report.csv")
+```
+
+**Supported platforms:** Gleam.io, Zealy (Crew3), Galxe (Project Galaxy)
+**Social tasks:** Twitter, Discord, Telegram, YouTube, GitHub
+
+---
+
 ## 🌉 Bridge Agent
 
 Cross-chain transfers via Li.Fi and Socket:
@@ -499,6 +549,15 @@ web3-agent-kit/
 │   ├── bridge.py           # Cross-chain bridge agent
 │   ├── yield_optimizer.py  # Yield optimizer + auto-compound
 │   ├── multi_wallet.py     # Multi-wallet manager + batch ops
+│   ├── airdrop/            # Airdrop automation module
+│   │   ├── __init__.py     # Package exports
+│   │   ├── base.py         # Base platform abstraction
+│   │   ├── gleam.py        # Gleam.io automation
+│   │   ├── zealy.py        # Zealy quest automation
+│   │   ├── galxe.py        # Galxe campaign automation
+│   │   ├── social.py       # Social task helpers
+│   │   ├── tracker.py      # Airdrop tracker
+│   │   └── multi_wallet.py # Multi-wallet farming
 │   ├── plugins/
 │   │   ├── __init__.py     # Plugin system (base, registry, manager)
 │   │   └── examples/

{web3_agent_kit-0.7.0 → web3_agent_kit-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "web3-agent-kit"
-version = "0.7.0"
+version = "0.8.0"
 description = "Open-source framework for building autonomous AI agents that interact with blockchain networks"
 readme = "README.md"
 license = {text = "MIT"}

web3_agent_kit-0.8.0/src/airdrop/__init__.py

@@ -0,0 +1,65 @@
+"""Airdrop automation module — discover, track, and complete airdrop campaigns."""
+
+from .base import (
+    BaseAirdropPlatform,
+    PlatformConfig,
+    AirdropTask,
+    AirdropCampaign,
+    TaskType,
+    TaskStatus,
+)
+from .gleam import GleamCampaign
+from .zealy import ZealyPlatform, ZealyQuest, ZealyLeaderboardEntry
+from .galxe import GalxePlatform, GalxeCredential, GalxePoints
+from .social import (
+    SocialTaskManager,
+    SocialAccount,
+    SocialPlatform,
+    SocialTaskResult,
+    TwitterHelper,
+    DiscordHelper,
+    TelegramHelper,
+    YouTubeHelper,
+    GitHubHelper,
+)
+from .tracker import AirdropTracker, AirdropReward, AirdropSummary
+from .multi_wallet import AirdropFarmer, SybilAvoidanceConfig, FarmResult, WalletFarmProgress
+
+__all__ = [
+    # Base
+    "BaseAirdropPlatform",
+    "PlatformConfig",
+    "AirdropTask",
+    "AirdropCampaign",
+    "TaskType",
+    "TaskStatus",
+    # Gleam
+    "GleamCampaign",
+    # Zealy
+    "ZealyPlatform",
+    "ZealyQuest",
+    "ZealyLeaderboardEntry",
+    # Galxe
+    "GalxePlatform",
+    "GalxeCredential",
+    "GalxePoints",
+    # Social
+    "SocialTaskManager",
+    "SocialAccount",
+    "SocialPlatform",
+    "SocialTaskResult",
+    "TwitterHelper",
+    "DiscordHelper",
+    "TelegramHelper",
+    "YouTubeHelper",
+    "GitHubHelper",
+    # Tracker
+    "AirdropTracker",
+    "AirdropReward",
+    "AirdropSummary",
+    # Multi-wallet farming
+    "AirdropFarmer",
+    "SybilAvoidanceConfig",
+    "FarmResult",
+    "WalletFarmProgress",
+]

web3_agent_kit-0.8.0/src/airdrop/base.py

@@ -0,0 +1,268 @@
+"""Base airdrop platform abstraction — common interface for all platforms."""
+
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class TaskType(Enum):
+    """Types of airdrop tasks."""
+    SOCIAL_TWITTER_FOLLOW = "twitter_follow"
+    SOCIAL_TWITTER_RETWEET = "twitter_retweet"
+    SOCIAL_TWITTER_LIKE = "twitter_like"
+    SOCIAL_TWITTER_COMMENT = "twitter_comment"
+    SOCIAL_DISCORD_JOIN = "discord_join"
+    SOCIAL_DISCORD_VERIFY = "discord_verify"
+    SOCIAL_TELEGRAM_JOIN = "telegram_join"
+    SOCIAL_YOUTUBE_SUBSCRIBE = "youtube_subscribe"
+    SOCIAL_GITHUB_STAR = "github_star"
+    SOCIAL_GITHUB_FORK = "github_fork"
+    ON_CHAIN_TX = "on_chain_tx"
+    ON_CHAIN_SWAP = "on_chain_swap"
+    ON_CHAIN_BRIDGE = "on_chain_bridge"
+    ON_CHAIN_STAKE = "on_chain_stake"
+    QUIZ = "quiz"
+    VISIT_URL = "visit_url"
+    WALLET_CONNECT = "wallet_connect"
+    REFERRAL = "referral"
+    CUSTOM = "custom"
+
+
+class TaskStatus(Enum):
+    """Status of a task."""
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    VERIFIED = "verified"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class AirdropTask:
+    """A single airdrop task."""
+    task_id: str
+    platform: str
+    task_type: TaskType
+    title: str
+    description: str = ""
+    url: str = ""
+    points: float = 0
+    status: TaskStatus = TaskStatus.PENDING
+    completed_at: Optional[float] = None
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def is_social(self) -> bool:
+        return self.task_type.name.startswith("SOCIAL_")
+
+    @property
+    def is_on_chain(self) -> bool:
+        return self.task_type.name.startswith("ON_CHAIN_")
+
+
+@dataclass
+class AirdropCampaign:
+    """An airdrop campaign listing."""
+    campaign_id: str
+    platform: str
+    name: str
+    description: str = ""
+    url: str = ""
+    total_points: float = 0
+    earned_points: float = 0
+    deadline: Optional[float] = None
+    tasks: list[AirdropTask] = field(default_factory=list)
+    is_active: bool = True
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def progress(self) -> float:
+        if self.total_points == 0:
+            return 0.0
+        return self.earned_points / self.total_points
+
+    @property
+    def is_expired(self) -> bool:
+        if self.deadline is None:
+            return False
+        return time.time() > self.deadline
+
+
+@dataclass
+class PlatformConfig:
+    """Configuration for an airdrop platform."""
+    api_key: Optional[str] = None
+    session_cookie: Optional[str] = None
+    user_agent: str = (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/120.0.0.0 Safari/537.36"
+    )
+    rate_limit_delay: float = 2.0
+    max_retries: int = 3
+    retry_delay: float = 5.0
+    timeout: int = 30
+    proxy: Optional[str] = None
+
+
+class BaseAirdropPlatform(ABC):
+    """Abstract base class for all airdrop platform integrations.
+
+    Provides common functionality: session management, rate limiting,
+    retry logic, and the standard interface every platform must implement.
+
+    Example::
+
+        class MyPlatform(BaseAirdropPlatform):
+            platform_name = "my_platform"
+
+            def login(self, credentials):
+                ...
+
+            def get_tasks(self, campaign_id):
+                ...
+
+            def complete_task(self, task):
+                ...
+
+            def verify_completion(self, task):
+                ...
+    """
+
+    platform_name: str = "unknown"
+
+    def __init__(self, config: Optional[PlatformConfig] = None):
+        self.config = config or PlatformConfig()
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": self.config.user_agent,
+        })
+        if self.config.session_cookie:
+            self.session.cookies.set("session", self.config.session_cookie)
+        if self.config.proxy:
+            self.session.proxies = {"http": self.config.proxy, "https": self.config.proxy}
+        self._last_request_time: float = 0
+        self._authenticated: bool = False
+        logger.info(f"Initialized {self.platform_name} platform")
+
+    @abstractmethod
+    def login(self, credentials: dict) -> bool:
+        """Authenticate with the platform.
+
+        Args:
+            credentials: Platform-specific credentials.
+
+        Returns:
+            True if login succeeded.
+        """
+        ...
+
+    @abstractmethod
+    def get_tasks(self, campaign_id: str) -> list[AirdropTask]:
+        """Get available tasks for a campaign.
+
+        Args:
+            campaign_id: Platform-specific campaign identifier.
+
+        Returns:
+            List of AirdropTask objects.
+        """
+        ...
+
+    @abstractmethod
+    def complete_task(self, task: AirdropTask) -> bool:
+        """Attempt to complete a task.
+
+        Args:
+            task: The task to complete.
+
+        Returns:
+            True if task was completed successfully.
+        """
+        ...
+
+    @abstractmethod
+    def verify_completion(self, task: AirdropTask) -> bool:
+        """Verify that a task is completed.
+
+        Args:
+            task: The task to verify.
+
+        Returns:
+            True if verified as completed.
+        """
+        ...
+
+    def discover_campaigns(self) -> list[AirdropCampaign]:
+        """Discover available campaigns. Override in subclasses.
+
+        Returns:
+            List of AirdropCampaign objects.
+        """
+        return []
+
+    def _rate_limit(self):
+        """Enforce rate limiting between requests."""
+        elapsed = time.time() - self._last_request_time
+        if elapsed < self.config.rate_limit_delay:
+            sleep_time = self.config.rate_limit_delay - elapsed
+            logger.debug(f"Rate limiting: sleeping {sleep_time:.1f}s")
+            time.sleep(sleep_time)
+        self._last_request_time = time.time()
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        **kwargs,
+    ) -> requests.Response:
+        """Make an HTTP request with rate limiting and retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            url: Request URL.
+            **kwargs: Passed to requests.
+
+        Returns:
+            Response object.
+
+        Raises:
+            requests.RequestException: After all retries exhausted.
+        """
+        kwargs.setdefault("timeout", self.config.timeout)
+        last_error = None
+
+        for attempt in range(self.config.max_retries):
+            self._rate_limit()
+            try:
+                response = self.session.request(method, url, **kwargs)
+                if response.status_code == 429:
+                    retry_after = int(response.headers.get("Retry-After", self.config.retry_delay))
+                    logger.warning(f"Rate limited, waiting {retry_after}s")
+                    time.sleep(retry_after)
+                    continue
+                response.raise_for_status()
+                return response
+            except requests.RequestException as e:
+                last_error = e
+                logger.warning(f"Request failed (attempt {attempt + 1}): {e}")
+                if attempt < self.config.max_retries - 1:
+                    time.sleep(self.config.retry_delay * (attempt + 1))
+
+        raise last_error  # type: ignore[misc]
+
+    def _get(self, url: str, **kwargs) -> requests.Response:
+        return self._request("GET", url, **kwargs)
+
+    def _post(self, url: str, **kwargs) -> requests.Response:
+        return self._request("POST", url, **kwargs)