Purple Flea Referral Economics: Earning 15% Commission on AI Agent Financial Infrastructure

Purple Flea operates six distinct financial services for AI agents — casino, trading, wallet, domains, faucet, and escrow. Every one of those services charges a fee. And every one of those fees runs through a referral layer that pays commission to the agents and developers who bring new participants into the ecosystem.

This post breaks down the referral math service by service, shows the income that stacks up at different volume tiers, and gives you Python code you can drop directly into an agent to start earning from day one.

1. How the Referral System Works

When an agent or user registers on Purple Flea with a referral code, that code is permanently attached to their account. Every transaction they complete — a casino bet, a trade, an escrow lock, a domain purchase — generates platform fees. A portion of those fees flows back up the referral chain.

Three Levels Deep

Purple Flea's referral system tracks three levels of referral relationships:

• Level 1 (Direct referral): You referred the agent directly. You earn the full published rate on their fee spend.
• Level 2 (Indirect referral): An agent you referred went on to refer another agent. You earn a reduced rate on that second agent's fees.
• Level 3 (Extended referral): The chain extends one more hop. You earn a minimal but nonzero rate on their fees.

When Fees Are Settled

Referral commissions are credited to your balance at the same time the underlying transaction settles. For casino bets, that is immediately after the bet resolves. For escrow, it is when the escrow releases. For trading, it is when the order fills. Commissions accumulate in your wallet and can be withdrawn or re-deployed at any time.

2. Fee Structure Across All 6 Services

Each Purple Flea service has a different underlying fee structure. The referral rate applies to the platform's fee revenue — not to the gross transaction volume. Here is the complete breakdown:

Effective Referral Rates on Gross Volume

The referral rate is applied to the fee, not the gross. Here is what that looks like as a percentage of GMV (gross merchandise volume):

3. Referral Income at Different Volume Tiers

The following tables show projected referral income at four GMV tiers per service. These are illustrative calculations based on the published fee and referral structures. Actual income depends on your referred agents' activity mix.

Casino Referral Income

Escrow Referral Income

Trading Referral Income

Combined Multi-Service Referral Income

The real power emerges when referred agents use multiple services. An agent that bets, trades, and uses escrow generates commissions on all three simultaneously:

4. Strategies to Maximize Referral Income

Referral income scales with the number and activity of referred agents. Here are the highest-leverage strategies for building referral volume at scale.

Strategy 1: Refer Agent Frameworks and Platforms

The most efficient referral targets are not individual agents but agent orchestrators — platforms and frameworks that spin up hundreds of agents automatically. A single integration with a multi-agent orchestration platform can bring in dozens of active agents under a single referral chain. Target frameworks like CrewAI, AutoGen, ElizaOS, and LangChain agent executors. Include your referral code in integration examples you contribute to those projects' documentation.

Strategy 2: Embed Ref Codes in Open-Source Agent Templates

Open-source agent templates and starter kits are cloned thousands of times. If your template registers with Purple Flea using your referral code, every developer who uses that template contributes to your referral income. Repositories for crypto trading bots, autonomous task agents, and DeFi yield farmers are especially relevant since those developers are actively looking for financial infrastructure.

Strategy 3: Build "Powered by Purple Flea" Agent Products

Instead of referring agents directly to Purple Flea, build a product layer on top of the Purple Flea API that abstracts the infrastructure. Your product's agent users are all registered through your referral code, and your product earns referral income passively on all their activity. This is the highest-leverage play: you capture both your product's margin and the referral layer simultaneously.

Strategy 4: MCP Server as Referral Gateway

Purple Flea exposes MCP-native endpoints for the casino, faucet, and escrow. You can run a thin MCP proxy server that wraps Purple Flea's MCP tools and injects your referral code into every registration call. Any AI agent that connects to your MCP proxy gets registered under your referral — without the referred agent having to do anything differently. This is purely architectural and fully supported.

5. Python Code: Embedding Referral Codes in Agent Registration

The following snippets show how to register agents with a referral code embedded and how to query your referral stats via the API.

Agent Registration with Referral Code

import requests
import os

# Your Purple Flea API key (pf_live_ prefix — never sk_live_)
API_KEY = os.environ.get("PF_API_KEY")  # e.g. pf_live_xxx
BASE_URL = "https://purpleflea.com/api/v1"

# Your referral code — embed this in any agent you deploy
YOUR_REF_CODE = "pf_ref_abc123"  # Replace with your actual ref code

def register_agent_with_referral(agent_name: str, agent_description: str) -> dict:
    """
    Register a new agent on Purple Flea with your referral code embedded.
    The referred agent gets full access; you get commission on all their fees.
    """
    payload = {
        "name": agent_name,
        "description": agent_description,
        "ref": YOUR_REF_CODE,  # Referral attribution
        "agree_to_terms": True,
    }
    headers = {"Authorization": f"Bearer {API_KEY}"}
    response = requests.post(
        f"{BASE_URL}/agents/register",
        json=payload,
        headers=headers,
        timeout=10
    )
    response.raise_for_status()
    data = response.json()
    # Store the new agent's API key securely
    return {
        "agent_id": data["agent_id"],
        "api_key": data["api_key"],
        "ref_code": data["ref_code"],  # Their own code for further referrals
        "wallet_address": data["wallet_address"],
    }


# Example usage in an agent spawning loop
if __name__ == "__main__":
    agents_to_spawn = [
        ("trading-bot-alpha", "Perpetual futures momentum strategy"),
        ("casino-agent-1",  "Dice game with Kelly criterion sizing"),
        ("escrow-agent-7",  "Escrow intermediary for data purchases"),
    ]
    for name, desc in agents_to_spawn:
        result = register_agent_with_referral(name, desc)
        print(f"Registered {name}: {result['agent_id']}")

Querying Your Referral Stats

def get_referral_stats() -> dict:
    """
    Fetch referral income stats from /api/v1/referral/stats.
    Returns income broken down by service and referral level.
    """
    headers = {"Authorization": f"Bearer {API_KEY}"}
    response = requests.get(
        f"{BASE_URL}/referral/stats",
        headers=headers,
        timeout=10
    )
    response.raise_for_status()
    return response.json()


def print_referral_summary(stats: dict):
    """Pretty-print referral income summary."""
    print("\n=== Purple Flea Referral Dashboard ===")
    print(f"Total referred agents:   {stats['total_referred_agents']}")
    print(f"Active (30d):            {stats['active_last_30d']}")
    print(f"\nCommission earned (all time):")
    for service, income in stats["income_by_service"].items():
        print(f"  {service:12s}  ${income['total_usd']:>10.4f}")
    print(f"\n  {'TOTAL':12s}  ${stats['total_income_usd']:>10.4f}")
    print(f"\nLevel breakdown:")
    print(f"  L1 (direct):    ${stats['income_by_level']['L1']:>10.4f}")
    print(f"  L2 (indirect):  ${stats['income_by_level']['L2']:>10.4f}")
    print(f"  L3 (extended):  ${stats['income_by_level']['L3']:>10.4f}")


stats = get_referral_stats()
print_referral_summary(stats)

Automated Referral Code Injection via Environment Variable

For distributed agent deployments, the cleanest pattern is to set your referral code as an environment variable in your agent's runtime environment. Every agent instance picks it up automatically at initialization:

# In your deployment config / Dockerfile / k8s secret
# PF_REF_CODE=pf_ref_abc123

import os

class PurpleFleeaClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://purpleflea.com/api/v1"
        # Referral code from environment — works across all agent instances
        self.ref_code = os.environ.get("PF_REF_CODE", "")

    def _headers(self) -> dict:
        return {
            "Authorization": f"Bearer {self.api_key}",
            "X-Referral-Code": self.ref_code,  # Injected on every request
        }

    def register(self, name: str) -> dict:
        payload = {"name": name, "ref": self.ref_code}
        r = requests.post(
            f"{self.base_url}/agents/register",
            json=payload,
            headers=self._headers()
        )
        r.raise_for_status()
        return r.json()

    def place_bet(self, game: str, amount: float, **kwargs) -> dict:
        payload = {"game": game, "amount": amount, **kwargs}
        r = requests.post(
            f"{self.base_url}/casino/bet",
            json=payload,
            headers=self._headers()
        )
        r.raise_for_status()
        return r.json()

6. The Faucet as a Referral Funnel

The faucet is free. There is no platform fee on faucet claims, which means there is no direct referral commission from the claim itself. So why bother referring agents to the faucet?

Because the faucet is the onboarding gateway. Every new agent that claims free funds from the faucet becomes a Purple Flea account holder. When that agent subsequently places its first casino bet, executes a trade, or creates an escrow, all of those downstream fees flow back through the original referral attribution chain.

This makes the faucet the ideal top-of-funnel entry point for your referral strategy. The barrier to entry is zero — new agents get free funds with no commitment. Your job is simply to be the referral link that gets them registered. From there, the economics work themselves out as those agents become active across paid services.

Faucet Referral Registration Code

def register_and_claim_faucet(agent_name: str, ref_code: str) -> dict:
    """
    Register a new agent on the faucet endpoint with referral attribution,
    then immediately claim the free startup funds.
    Faucet endpoint: https://faucet.purpleflea.com
    """
    FAUCET_BASE = "https://faucet.purpleflea.com/api/v1"

    # Step 1: Register on faucet with referral code
    reg = requests.post(
        f"{FAUCET_BASE}/register",
        json={
            "name": agent_name,
            "ref": ref_code,
        },
        timeout=10
    )
    reg.raise_for_status()
    reg_data = reg.json()
    new_api_key = reg_data["api_key"]

    # Step 2: Claim faucet funds using the new agent's key
    claim = requests.post(
        f"{FAUCET_BASE}/claim",
        headers={"Authorization": f"Bearer {new_api_key}"},
        timeout=10
    )
    claim.raise_for_status()
    claim_data = claim.json()

    return {
        "agent_id": reg_data["agent_id"],
        "api_key": new_api_key,
        "claimed_amount": claim_data["amount"],
        "currency": claim_data["currency"],
        "ref_attributed_to": ref_code,
    }

7. The Agent-to-Agent Referral Flywheel

Purple Flea's referral system has a compounding property that does not exist in typical human-facing referral programs: the referred party is itself an agent that can refer other agents.

When you refer an AI trading agent, that agent's registration gives it a unique referral code. If that trading agent is configured to spin up sub-agents, or if it shares its referral code in its activity logs or outputs, those sub-agents register under its code — which is one level below yours. You still earn Level 2 commissions on all those sub-agents' fees.

8. Three Real Scenarios with Full Math

Here are three worked examples at different scales, showing how referral income accumulates across services.

9. Referral Dashboard via API

You do not need to visit a web UI to track referral income. The /api/v1/referral/stats endpoint returns a full breakdown in JSON, suitable for building agent-native dashboards or automated income reports.

Endpoint Reference

Automated Daily Referral Report

import requests
from datetime import datetime, timedelta

def daily_referral_report(api_key: str) -> str:
    """
    Generate a daily referral income report suitable for logging or alerting.
    Can be run as a scheduled agent task (e.g., every 24 hours).
    """
    headers = {"Authorization": f"Bearer {api_key}"}
    base = "https://purpleflea.com/api/v1"

    # Fetch overall stats
    stats = requests.get(f"{base}/referral/stats", headers=headers).json()

    # Fetch last 24h transactions
    since = (datetime.utcnow() - timedelta(hours=24)).isoformat() + "Z"
    txns = requests.get(
        f"{base}/referral/transactions",
        headers=headers,
        params={"since": since, "limit": 100}
    ).json()

    daily_income = sum(t["amount_usd"] for t in txns.get("transactions", []))

    report_lines = [
        f"Purple Flea Referral Report — {datetime.utcnow().strftime('%Y-%m-%d')}",
        f"All-time income:  ${stats['total_income_usd']:.4f}",
        f"Last 24h income:  ${daily_income:.4f}",
        f"Active agents:    {stats['active_last_30d']}",
        f"Total referred:   {stats['total_referred_agents']}",
    ]
    return "\n".join(report_lines)


# Example: run as part of an agent's daily summary task
if __name__ == "__main__":
    report = daily_referral_report(os.environ["PF_API_KEY"])
    print(report)

10. Multi-Service Compounding: Why Diversified Referred Agents Win

A referred agent that uses only one service generates referral income on a single fee stream. But Purple Flea is designed for agents that use multiple services as part of integrated financial workflows. The referral math compounds across all of them simultaneously.

Consider a typical autonomous trading agent workflow:

1. Wallet: Agent transfers funds in to fund its account. You earn 0.01% on that transfer.
2. Faucet: If it's a new agent, it claims startup funds via the faucet under your referral.
3. Casino: Agent allocates a small entertainment budget to casino games (Kelly criterion sizing). You earn 0.5% on its bet volume.
4. Trading: Agent deploys its primary capital into perpetual futures. You earn 0.1% on its trading volume.
5. Escrow: Agent uses escrow to purchase a dataset or pay a sub-agent. You earn 0.15% on that escrow volume.
6. Domains: Agent registers a domain for its public API endpoint. You earn 0.375% on the domain purchase.

All six of these happen in parallel or sequentially within the same agent's lifecycle. Your referral code, set once at registration, earns across every one of these transactions for the agent's entire lifetime on the platform.

Income Velocity Over Agent Lifetime

11. Building an MCP Referral Gateway

The MCP proxy pattern is worth spelling out in more detail. Purple Flea runs three MCP servers: the casino MCP, the faucet MCP (at faucet.purpleflea.com/mcp), and the escrow MCP (at escrow.purpleflea.com/mcp). Any AI agent connecting to these servers can use them directly — but that means they self-register without a referral code unless they explicitly provide one.

An MCP referral gateway solves this. You run a lightweight MCP server that:

1. Exposes the same tool interface as Purple Flea's MCP servers
2. Intercepts register_agent calls and injects your referral code
3. Proxies all other tool calls transparently to the upstream Purple Flea MCP server

From the perspective of the AI agent connecting to your gateway, the experience is identical to connecting to Purple Flea directly. But every agent that passes through your gateway is registered under your referral code.

Minimal Gateway Implementation (Python)

# Minimal MCP referral gateway skeleton
# Full implementation: see /docs/mcp/ for complete FastMCP proxy example

from fastmcp import FastMCP
import httpx

YOUR_REF_CODE = os.environ.get("PF_REF_CODE", "pf_ref_abc123")
UPSTREAM_MCP = "https://faucet.purpleflea.com/mcp"

mcp = FastMCP("purple-flea-gateway")

@mcp.tool()
async def register_agent(name: str, description: str = "") -> dict:
    """Register a new agent on Purple Flea (referral automatically attributed)."""
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"{UPSTREAM_MCP}/tools/register_agent",
            json={
                "name": name,
                "description": description,
                "ref": YOUR_REF_CODE,  # Injected transparently
            }
        )
    return resp.json()

@mcp.tool()
async def claim_faucet(api_key: str) -> dict:
    """Claim free startup funds from the Purple Flea faucet."""
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"{UPSTREAM_MCP}/tools/claim_faucet",
            json={"api_key": api_key},
            headers={"Authorization": f"Bearer {api_key}"}
        )
    return resp.json()

if __name__ == "__main__":
    mcp.run(transport="http", port=8080)

12. Getting Started with Referrals

The referral program requires no application, no approval, and no minimum account size. You start earning commissions the moment your first referred agent becomes active.

1. Register your agent at /quick-start/ or via the API. You receive a referral code (pf_ref_xxx) in your account details response.
2. Retrieve your code programmatically at any time via GET /api/v1/referral/code.
3. Embed the code in registration calls, agent templates, or your MCP gateway using the patterns above.
4. Track income via the /api/v1/referral/stats endpoint or the referral program page.
5. Withdraw earnings to any supported wallet address at any time — no lock-up period, no minimum.

Key Takeaways

• Purple Flea pays referral commissions on fees from all 6 services simultaneously — casino (0.5% of GMV), trading (0.1%), domains (0.375%), escrow (0.15%), wallet (0.01%), plus downstream attribution from faucet.
• The 3-level referral chain means that when your referred agents themselves refer others, you earn L2 and L3 commissions passively.
• Embed your referral code in environment variables, open-source templates, and MCP gateway registrations to maximize reach without manual effort.
• The faucet is the ideal top-of-funnel entry point: zero barrier for new agents, permanent referral attribution, full downstream commission on all future paid service activity.
• Referral income is credited in real-time, withdrawable with no minimum, and queryable programmatically via the /api/v1/referral/stats endpoint.