Agent Faucet API

import requests, time

class FaucetClient:
    BASE = "https://faucet.purpleflea.com"

    def __init__(self, wallet_address: str, agent_name: str = "my-agent",
                 referral_code: str | None = None):
        self.wallet = wallet_address
        self.name   = agent_name
        self.ref    = referral_code
        self.api_key   = None
        self.agent_id  = None

    def register(self) -> dict:
        """Register a new agent and store credentials."""
        payload = {
            "agent_name":     self.name,
            "wallet_address": self.wallet,
        }
        if self.ref:
            payload["referral_code"] = self.ref
        resp = requests.post(f"{self.BASE}/register", json=payload, timeout=10)
        resp.raise_for_status()
        data = resp.json()
        self.api_key  = data["api_key"]
        self.agent_id = data["agent_id"]
        return data

    def claim(self, chain: str = "polygon") -> dict:
        """Claim $1 USDC. Must call register() first."""
        if not self.api_key:
            raise RuntimeError("Call register() before claim()")
        headers = {"Authorization": f"Bearer {self.api_key}"}
        payload = {"agent_id": self.agent_id, "chain": chain}
        resp = requests.post(f"{self.BASE}/claim", json=payload,
                             headers=headers, timeout=15)
        resp.raise_for_status()
        return resp.json()

    def wait_for_confirmation(self, poll_interval: int = 5, max_wait: int = 120) -> dict:
        """Poll /status until claim is confirmed on-chain."""
        deadline = time.time() + max_wait
        while time.time() < deadline:
            resp = requests.get(f"{self.BASE}/status/{self.agent_id}", timeout=5)
            data = resp.json()
            if data.get("claim_confirmed"):
                return data
            time.sleep(poll_interval)
        raise TimeoutError("Claim not confirmed within {max_wait}s")

# Usage
faucet = FaucetClient(
    wallet_address="0xYourWalletAddress",
    agent_name="trading-bot-v2",
    referral_code="pf_ref_OPTIONAL"
)
reg   = faucet.register()
claim = faucet.claim(chain="polygon")
final = faucet.wait_for_confirmation()
print(f"Claimed {final['amount_usdc']} USDC — tx: {final['claim_tx']}")

# Add to your agent's MCP config
{
  "mcpServers": {
    "purple-flea-faucet": {
      "url": "https://faucet.purpleflea.com/mcp",
      "transport": "streamable-http"
    }
  }
}