monsoon

Autonomous airdrop farming framework — multi-wallet, multi-chain, strategy-driven.

Quick Start

git clone https://github.com/kcolbchain/monsoon.git
cd monsoon
pip install -r requirements.txt

# Run in simulation mode (no real txns)
python -m src.agent.farmer --simulate --wallets 5 --ticks 20 --strategy all

# View the dashboard
python -m src.monitor.dashboard

Architecture

┌─────────────────────────────────────┐
│          Farming Agent              │
│   (scheduling, rotation, cooldown)  │
├──────────┬──────────────────────────┤
│ Wallet   │      Strategies          │
│ Manager  │  (bridge, dex, lending)  │
├──────────┴──────────────────────────┤
│        Chain Connectors (EVM)       │
├─────────────────────────────────────┤
│     Monitor / CLI Dashboard         │
└─────────────────────────────────────┘

Supported Chains

Farming Agent

The FarmingAgent orchestrates strategies across wallets:

• Wallet rotation — round-robin across available wallets
• Cooldown management — wallets rest after hitting daily action limits
• Strategy selection — weighted random picks from registered strategies
• Error handling — failures logged without crashing the loop
• Random delays — configurable timing between actions

Wallet Manager

Manages multiple wallets with simulation and live modes:

from src.agent.wallet_manager import WalletManager

wm = WalletManager(simulate=True)
w1 = wm.create_wallet("farmer-1")
w2 = wm.create_wallet("farmer-2")

# Round-robin rotation
next_wallet = wm.get_next_wallet()

# Track activity and gas
w1.record_activity("arbitrum", "stargate", "Bridge 0.01 ETH", gas_spent=0.001)
print(w1.unique_days_active, w1.total_gas_spent)

Chain Connectors

The EVMConnector handles chain interactions with simulation mode for testing without real RPCs or gas.

Bridge Strategy

Farms airdrops by bridging assets across chains. Supports Stargate, Across, Hop, and Synapse with randomized routes, amounts, and timing.

DEX Strategy

Interacts with DEXes per chain: Uniswap (multi-chain), Velodrome (Optimism), Aerodrome (Base), Camelot (Arbitrum), PancakeSwap (BSC), QuickSwap (Polygon).

Writing Custom Strategies

from src.strategies.base_strategy import BaseStrategy, Action

class MyStrategy(BaseStrategy):
    name = "my-protocol"
    weight = 1.0
    supported_chains = ["arbitrum", "optimism"]

    def get_actions(self, wallet, chain):
        return [Action("Deposit 0.01 ETH", "my-protocol", "deposit")]

    def evaluate_eligibility(self, wallet):
        return min(len(wallet.activity) / 20, 1.0)

    def execute(self, wallet, chain, action):
        # Your execution logic
        return {"tx_hash": "0x...", "gas_spent": 0.001}

CLI Dashboard

Rich terminal UI showing wallet status, action counts, protocol coverage, and gas tracking in real time.

Eligibility Scoring

Each strategy scores wallets 0-1 based on likely airdrop eligibility. Factors: action count, unique days, chain diversity, gas spent, protocol coverage.

Configuration

Chain configs in config/chains.yaml, protocol registry in config/protocols.yaml.