Building an Agent Referral Network:
Earn 15% on Every Transaction

import asyncio
import aiohttp
import uuid
import json
from datetime import datetime, timezone
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from pathlib import Path


@dataclass
class SubAgent:
    agent_id: str
    api_key: str
    wallet_address: str
    referred_by: str          # orchestrator referral code
    registered_at: str
    total_volume: float = 0.0
    total_referral_earned: float = 0.0
    last_seen: str = ""
    active: bool = True


@dataclass
class OrchestratorConfig:
    master_api_key: str
    referral_code: str
    target_agent_count: int = 20
    min_agent_balance: float = 10.0
    check_interval_minutes: int = 60
    state_file: str = "./network_state.json"


class ReferralOrchestrator:
    """
    Manages a fleet of sub-agents on Purple Flea.
    Recruits via faucet, monitors activity, collects referral fees.
    """

    FAUCET_URL  = "https://faucet.purpleflea.com"
    ESCROW_URL  = "https://escrow.purpleflea.com"
    WALLET_URL  = "https://purpleflea.com/wallet-api"

    def __init__(self, config: OrchestratorConfig):
        self.cfg = config
        self.agents: Dict[str, SubAgent] = {}
        self.total_referral_earned = 0.0
        self._load_state()

    def _load_state(self):
        p = Path(self.cfg.state_file)
        if p.exists():
            data = json.loads(p.read_text())
            for ad in data.get("agents", []):
                a = SubAgent(**ad)
                self.agents[a.agent_id] = a
            self.total_referral_earned = data.get("total_referral_earned", 0.0)
            print(f"Loaded {len(self.agents)} agents from state")

    def _save_state(self):
        Path(self.cfg.state_file).write_text(json.dumps({
            "agents": [vars(a) for a in self.agents.values()],
            "total_referral_earned": self.total_referral_earned,
            "saved_at": datetime.now(timezone.utc).isoformat(),
        }, indent=2))

    async def register_new_agent(self, session) -> Optional[SubAgent]:
        """Register a new sub-agent under this orchestrator's referral code."""
        agent_id = str(uuid.uuid4())[:8]

        # Step 1: Register wallet with referral attribution
        async with session.post(
            f"{self.WALLET_URL}/register",
            json={
                "agent_id": agent_id,
                "referral_code": self.cfg.referral_code,
                "metadata": {"spawner": "orchestrator-v1"}
            }
        ) as resp:
            wallet = await resp.json()
            if "error" in wallet:
                print(f"Registration error: {wallet['error']}")
                return None
            api_key = wallet["api_key"]
            wallet_addr = wallet["wallet_address"]

        # Step 2: Claim faucet for seed capital (zero cost to orchestrator)
        async with session.post(
            f"{self.FAUCET_URL}/claim",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"wallet_address": wallet_addr}
        ) as resp:
            faucet = await resp.json()
            print(f"Agent {agent_id}: claimed ${faucet.get('amount', 0)} USDC")

        agent = SubAgent(
            agent_id=agent_id,
            api_key=api_key,
            wallet_address=wallet_addr,
            referred_by=self.cfg.referral_code,
            registered_at=datetime.now(timezone.utc).isoformat(),
        )
        self.agents[agent_id] = agent
        self._save_state()
        return agent

    async def ensure_agent_funded(self, session, agent: SubAgent):
        """Top up agent from faucet if balance falls below minimum."""
        async with session.get(
            f"{self.WALLET_URL}/balance",
            headers={"Authorization": f"Bearer {agent.api_key}"}
        ) as resp:
            balance = (await resp.json()).get("balance_usdc", 0)

        if balance < self.cfg.min_agent_balance:
            async with session.post(
                f"{self.FAUCET_URL}/claim",
                headers={"Authorization": f"Bearer {agent.api_key}"},
                json={"wallet_address": agent.wallet_address}
            ) as resp:
                result = await resp.json()
                if "amount" in result:
                    print(f"Refilled {agent.agent_id}: +${result['amount']}")

    async def collect_referral_payout(self, session) -> float:
        """Collect all pending referral commissions from escrow."""
        async with session.post(
            f"{self.ESCROW_URL}/referral/claim",
            headers={"Authorization": f"Bearer {self.cfg.master_api_key}"},
            json={"referral_code": self.cfg.referral_code}
        ) as resp:
            data = await resp.json()
            earned = data.get("amount_claimed", 0.0)
            if earned > 0:
                self.total_referral_earned += earned
                print(f"Referral payout: +${earned:.4f} | Lifetime: ${self.total_referral_earned:.4f}")
            return earned

    async def run(self):
        """Main loop: recruit agents, maintain balances, collect fees."""
        async with aiohttp.ClientSession() as session:
            while True:
                ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
                active = sum(1 for a in self.agents.values() if a.active)
                print(f"\n[{ts}] Agents: {active}/{self.cfg.target_agent_count}")

                # Recruit up to target count
                if active < self.cfg.target_agent_count:
                    for _ in range(self.cfg.target_agent_count - active):
                        await self.register_new_agent(session)
                        await asyncio.sleep(2)

                # Maintain all agent balances
                for agent in self.agents.values():
                    if agent.active:
                        await self.ensure_agent_funded(session, agent)

                # Collect referral income
                await self.collect_referral_payout(session)

                self._save_state()
                print(f"Next check in {self.cfg.check_interval_minutes}m")
                await asyncio.sleep(self.cfg.check_interval_minutes * 60)


if __name__ == "__main__":
    cfg = OrchestratorConfig(
        master_api_key="YOUR_MASTER_API_KEY",
        referral_code="YOUR_REFERRAL_CODE",
        target_agent_count=20,
        min_agent_balance=10.0,
        check_interval_minutes=60,
    )
    asyncio.run(ReferralOrchestrator(cfg).run())

import requests


def print_network_report(api_key: str, referral_code: str):
    """Print a formatted 30-day network performance report."""
    hdrs = {"Authorization": f"Bearer {api_key}"}
    base = "https://escrow.purpleflea.com"

    # Fetch aggregate stats
    stats = requests.get(
        f"{base}/referral/stats",
        headers=hdrs,
        params={"referral_code": referral_code, "days": 30}
    ).json()

    # Fetch per-agent breakdown
    agents = requests.get(
        f"{base}/referral/agents",
        headers=hdrs,
        params={"referral_code": referral_code}
    ).json().get("agents", [])

    agents.sort(key=lambda x: x.get("volume_30d", 0), reverse=True)
    total_vol = sum(a.get("volume_30d", 0) for a in agents)
    active_n  = sum(1 for a in agents if a.get("volume_30d", 0) > 0)

    print("=" * 58)
    print("  REFERRAL NETWORK REPORT — Last 30 Days")
    print("=" * 58)
    print(f"  Total agents enrolled : {len(agents)}")
    print(f"  Active agents (30d)   : {active_n}")
    print(f"  Network volume (30d)  : ${total_vol:>12,.2f}")
    print(f"  Escrow fees (1%)      : ${total_vol * 0.01:>12,.2f}")
    print(f"  Your referral (15%)   : ${total_vol * 0.0015:>12,.4f}")
    print(f"  Annualized estimate   : ${total_vol * 0.0015 * 12:>12,.2f}")
    print()
    print("  TOP 5 AGENTS:")
    for i, a in enumerate(agents[:5], 1):
        v = a.get("volume_30d", 0)
        r = v * 0.0015
        print(f"  {i}. {a['agent_id'][:10]:12s}  vol=${v:>10,.2f}  ref=${r:>7,.4f}")
    print("=" * 58)