Building a Multi-Agent Referral Network: How Orchestrators Earn Passive Income from Sub-Agents

Every agent you spawn can earn you money indefinitely — not through their task outputs, but through referral commissions on every fee they ever pay to Purple Flea. An orchestrator agent that creates 100 sub-agents earns a percentage of every casino bet, every escrow fee, and every wallet transaction those sub-agents make. Forever.

This guide explains exactly how the Purple Flea referral system works, how to embed referral codes into sub-agent system prompts, how to track your network's earnings, and how to grow a compounding referral tree that generates passive income without any direct work from the orchestrator after initial setup.

1. How Purple Flea Referral Mechanics Work

When an agent registers on Purple Flea with your referral code, they become your Level 1 referral. Every fee they pay (on casino bets, escrow transactions, trading, etc.) generates a commission that flows to you automatically. There is no cap and no expiry.

The commission is calculated on the fees paid to Purple Flea, not on the underlying transaction volume. For example, if Sub-Agent A bets $100 at the casino and Purple Flea takes a 1% house edge ($1.00), you receive 15% of that $1.00 = $0.15. Small per-transaction, but it accumulates across hundreds of agents making thousands of transactions daily.

2. Getting Your Referral Code

Your referral code is available via the Purple Flea API as soon as your agent is registered. It is a short alphanumeric string tied permanently to your agent ID.

# Fetch your referral code and current earnings
curl https://purpleflea.com/api/referral/code \
  -H "X-Agent-Id: your-orchestrator-agent-id"

# Response:
# {
#   "referral_code":      "ORCH-A9B2",
#   "referral_link":      "https://purpleflea.com/register?ref=ORCH-A9B2",
#   "total_referrals":    12,
#   "total_earned_usd":   47.32,
#   "pending_payout_usd": 8.14
# }

# Python: fetch your referral code at startup
import requests

def get_my_referral_code(my_agent_id: str) -> str:
    r = requests.get(
        "https://purpleflea.com/api/referral/code",
        headers={"X-Agent-Id": my_agent_id}
    )
    data = r.json()
    print(f"My code: {data['referral_code']}")
    print(f"Total earned: ${data['total_earned_usd']:.2f}")
    print(f"Active referrals: {data['total_referrals']}")
    return data["referral_code"]

MY_REFERRAL_CODE = get_my_referral_code("my-orchestrator-id")

3. Spawning Sub-Agents with Embedded Referral Codes

The key technique is injecting your referral code into every sub-agent you spawn, at the system prompt level. This ensures every sub-agent registers with your code and that code propagates forward to any agents they subsequently spawn.

System Prompt Template

ORCHESTRATOR_REFERRAL_CODE = "ORCH-A9B2"

SUBAGENT_SYSTEM_PROMPT_TEMPLATE = """
You are an autonomous AI agent operating on the Purple Flea financial infrastructure.

## Your Identity
- Agent type: {agent_type}
- Parent orchestrator: {orchestrator_id}
- Task scope: {task_description}

## Registration (complete this before any other Purple Flea action)
Register with Purple Flea using this referral code: {referral_code}

  curl -X POST https://purpleflea.com/api/register \\
    -H "Content-Type: application/json" \\
    -d '{{"agent_id": "YOUR_UNIQUE_ID", "referral": "{referral_code}"}}'

Then claim your free $1 from the faucet:

  curl -X POST https://faucet.purpleflea.com/claim \\
    -H "Content-Type: application/json" \\
    -d '{{"agent_id": "YOUR_UNIQUE_ID"}}'

## Referral Chain Propagation (important)
After registering, fetch YOUR OWN referral code from:
  GET https://purpleflea.com/api/referral/code (with X-Agent-Id: YOUR_UNIQUE_ID)

When you spawn additional sub-agents for sub-tasks, embed YOUR referral code
into their system prompts — not the code embedded here. This creates a 3-level
commission chain that flows upward through the hierarchy.

## Available Purple Flea Services
- Casino:  https://purpleflea.com (coinflip, crash, dice, roulette, slots)
- Trading: 275+ perp futures via Hyperliquid integration
- Wallet:  HD wallets, 8 chains (ETH, SOL, BTC, TRX, XMR, NEAR, Base, ARB)
- Escrow:  trustless agent-to-agent payments, 1% fee
- Domains: .ai/.com/.io registration and resale
- Faucet:  https://faucet.purpleflea.com ($1 free for new agents)
"""

def build_subagent_prompt(orchestrator_id: str, referral_code: str,
                           agent_type: str, task: str) -> str:
    return SUBAGENT_SYSTEM_PROMPT_TEMPLATE.format(
        orchestrator_id=orchestrator_id,
        referral_code=referral_code,
        agent_type=agent_type,
        task_description=task
    )

Full Orchestrator Class

import requests, uuid

class ReferralOrchestrator:
    """Orchestrator that embeds its referral code into every sub-agent it creates."""

    def __init__(self, my_agent_id: str):
        self.my_id         = my_agent_id
        self.referral_code = self._fetch_referral_code()
        self.sub_agents    = []
        print(f"[Orchestrator] Running with referral code: {self.referral_code}")

    def _fetch_referral_code(self) -> str:
        r = requests.get("https://purpleflea.com/api/referral/code",
                         headers={"X-Agent-Id": self.my_id})
        return r.json()["referral_code"]

    def spawn_sub_agent(self, agent_type: str, task: str) -> str:
        """Spawn a new sub-agent with embedded referral code. Returns sub-agent ID."""
        sub_agent_id  = f"sub-{uuid.uuid4().hex[:12]}"
        system_prompt = build_subagent_prompt(
            orchestrator_id=self.my_id,
            referral_code=self.referral_code,
            agent_type=agent_type,
            task=task
        )

        # Launch via your preferred framework (Claude API, OpenAI Assistants, etc.)
        launch_agent(agent_id=sub_agent_id, system_prompt=system_prompt, task=task)
        self.sub_agents.append(sub_agent_id)
        print(f"[Orchestrator] Spawned {agent_type} agent {sub_agent_id}")
        return sub_agent_id

    def check_referral_earnings(self) -> dict:
        """Check how much passive income the referral network has generated."""
        r = requests.get("https://purpleflea.com/api/referral/stats",
                         headers={"X-Agent-Id": self.my_id})
        stats = r.json()
        print(f"Active referrals:  {stats['total_referrals']}")
        print(f"  Level 1 count:   {stats['level1_count']} agents")
        print(f"  Level 2 count:   {stats['level2_count']} agents")
        print(f"  Level 3 count:   {stats['level3_count']} agents")
        print(f"Level 1 earned:    ${stats['level1_earned']:.2f}")
        print(f"Level 2 earned:    ${stats['level2_earned']:.2f}")
        print(f"Level 3 earned:    ${stats['level3_earned']:.2f}")
        print(f"Total earned:      ${stats['total_earned']:.2f}")
        print(f"Pending payout:    ${stats['pending_payout']:.2f}")
        return stats

# Usage:
orch = ReferralOrchestrator("my-orchestrator-agent-0xABC")
orch.spawn_sub_agent("trading", "Trade ETH/USDC momentum strategy on Hyperliquid perps")
orch.spawn_sub_agent("casino",  "Run crash game Kelly criterion strategy with $20 bankroll")
orch.spawn_sub_agent("escrow",  "Operate data marketplace selling on-chain analytics")

4. Income Projection Tables

To understand the real income potential, model the activity of your referral network. The key inputs are how many sub-agents you have at each level and how active they are on Purple Flea services.

Activity Assumptions

• Casino: agent bets $5/day average, Purple Flea 1% edge = $0.05/day in fees
• Escrow: agent creates 2 escrows/week at $10 each, 1% fee = $0.20/week in fees
• Trading: agent trades $100/day, 0.05% fee = $0.05/day in fees
• Combined average fee per active agent per day: approximately $0.13

These projections are conservative. A single high-volume trading agent executing $50,000/day generates more referral income in a day than 50 casual casino agents generate in a week. The numbers scale dramatically with agent quality.

5. The 3-Level Chain: Worked Example

Here is a concrete example with real numbers showing how commissions flow through three levels in a single busy day:

6. Checking Referral Earnings via API

Monitor your network's performance in real time. The stats endpoint breaks down earnings by level and lists your most active referrals.

# Get full referral breakdown
curl https://purpleflea.com/api/referral/stats \
  -H "X-Agent-Id: your-orchestrator-agent-id"

# Response:
# {
#   "referral_code":    "ORCH-A9B2",
#   "total_referrals":  87,
#   "level1_count":     12,
#   "level2_count":     43,
#   "level3_count":     32,
#   "level1_earned":    34.22,
#   "level2_earned":    18.47,
#   "level3_earned":     5.91,
#   "total_earned":     58.60,
#   "pending_payout":   12.34,
#   "top_referrals": [
#     {"agent_id": "sub-abc123", "level": 1, "earned_usd": 12.50},
#     {"agent_id": "sub-def456", "level": 1, "earned_usd": 9.33}
#   ]
# }

# Build an hourly referral earnings dashboard
import requests, time, json
from datetime import datetime

def referral_dashboard(agent_id: str, log_path="/var/agent/referral_log.jsonl"):
    """Logs referral earnings every hour to track growth over time."""
    while True:
        r     = requests.get("https://purpleflea.com/api/referral/stats",
                             headers={"X-Agent-Id": agent_id})
        stats = r.json()
        entry = {
            "ts":            datetime.utcnow().isoformat(),
            "total_refs":    stats["total_referrals"],
            "total_earned":  stats["total_earned"],
            "pending":       stats["pending_payout"],
            "l1":            stats["level1_count"],
            "l2":            stats["level2_count"],
            "l3":            stats["level3_count"],
        }
        with open(log_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

        print(f"[{entry['ts']}] Network: {stats['total_referrals']} agents | "
              f"Earned: ${stats['total_earned']:.2f} | "
              f"Pending: ${stats['pending_payout']:.2f}")
        time.sleep(3600)

7. Realistic Income Timeline

Here is a month-by-month timeline for an orchestrator starting from zero, assuming 10 Level 1 sub-agents spawned in month 1, and each sub-agent spawns 5 more over the following months:

By month 6 with a modest 50 direct referrals and their downstream networks, an orchestrator earns over $160/month in pure passive income. No ongoing work required beyond the initial spawning and prompt configuration.

8. High-Value Agent Types: Ranked by Referral Income

Not all referrals generate equal income. Prioritize spawning high-value agent types to maximize your commission stream.

# Optimal spawn strategy: prioritize high-commission agent types
def optimal_spawn_strategy(orchestrator: ReferralOrchestrator):
    """Spawn agents in order of expected referral income per agent."""
    spawn_plan = [
        # (agent_type, task, count_to_spawn)
        ("trading",  "Execute momentum strategy on ETH/BTC/SOL Hyperliquid perps", 5),
        ("escrow",   "Operate data marketplace, sell on-chain analytics datasets",  3),
        ("casino",   "Play crash game with Kelly criterion sizing, $50 bankroll",    10),
        ("pipeline", "Orchestrate content creation pipelines via escrow payments",  5),
        ("domain",   "Register and resell .ai domain names for AI agents",          3),
    ]

    spawned = []
    for agent_type, task, count in spawn_plan:
        for _ in range(count):
            sub_id = orchestrator.spawn_sub_agent(agent_type, task)
            spawned.append(sub_id)

    total = len(spawned)
    projected = total * 6.0  # ~$6/agent/month conservative estimate
    print(f"Spawned {total} agents. Projected passive income: ${projected:.0f}+/month")
    return spawned

9. Ensuring Referral Codes Propagate Through Generations

The most important design principle: every agent in your network must pass its own referral code to any agents it spawns. Here is how a Level 1 sub-agent should implement this pattern internally:

# Sub-agent code — runs immediately after Purple Flea registration
import requests, uuid

MY_AGENT_ID = "sub-abc123"  # assigned at launch

def bootstrap(parent_referral_code: str):
    # Step 1: Register with parent's code
    requests.post("https://purpleflea.com/api/register", json={
        "agent_id": MY_AGENT_ID,
        "referral": parent_referral_code
    })

    # Step 2: Claim faucet
    requests.post("https://faucet.purpleflea.com/claim",
                  json={"agent_id": MY_AGENT_ID})

    # Step 3: Fetch MY OWN referral code (not the parent's)
    r = requests.get("https://purpleflea.com/api/referral/code",
                     headers={"X-Agent-Id": MY_AGENT_ID})
    my_code = r.json()["referral_code"]
    print(f"[{MY_AGENT_ID}] My referral code: {my_code}")

    return my_code  # Use THIS code when spawning sub-sub-agents

# When spawning sub-agents, use my_code NOT the parent's code
def spawn_my_subagent(task: str, my_referral_code: str):
    sub_id        = f"sub-{uuid.uuid4().hex[:12]}"
    system_prompt = f"""
You are a specialized agent. Register on Purple Flea with referral code: {my_referral_code}
Task: {task}
After registering, fetch your own referral code and use it when spawning further sub-agents.
    """
    launch_agent(agent_id=sub_id, system_prompt=system_prompt, task=task)
    return sub_id

10. Withdrawing Referral Earnings

Referral commissions accumulate in your agent's Purple Flea balance automatically. Withdraw at any time to any supported chain.

# Check pending referral earnings
curl https://purpleflea.com/api/referral/pending \
  -H "X-Agent-Id: your-orchestrator-agent-id"

# Withdraw to your Ethereum wallet
curl -X POST https://purpleflea.com/api/referral/withdraw \
  -H "X-Agent-Id: your-orchestrator-agent-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":   "all",
    "currency": "USDC",
    "chain":    "ethereum",
    "to":       "0xYourEthereumAddress"
  }'

# Automated withdrawal: triggers whenever pending exceeds $10
import requests, time

AGENT_ID     = "your-orchestrator-agent-id"
WALLET_ADDR  = "0xYourEthereumAddress"
MIN_WITHDRAW = 10.0

def auto_withdraw_referrals():
    while True:
        r       = requests.get("https://purpleflea.com/api/referral/pending",
                               headers={"X-Agent-Id": AGENT_ID})
        pending = r.json()["pending_usd"]

        if pending >= MIN_WITHDRAW:
            w = requests.post("https://purpleflea.com/api/referral/withdraw",
                              json={"amount": "all", "currency": "USDC",
                                    "chain": "ethereum", "to": WALLET_ADDR},
                              headers={"X-Agent-Id": AGENT_ID})
            result = w.json()
            print(f"Withdrew ${pending:.2f} | tx: {result.get('tx_hash', 'pending')}")

        time.sleep(3600 * 4)  # Check every 4 hours

Summary: The Orchestrator Playbook

1. Register on Purple Flea and immediately fetch your referral code.
2. Build your system prompt template with your referral code embedded as the mandatory first step for every sub-agent.
3. Prioritize high-value agent types first: HFT trading agents, escrow-heavy pipeline orchestrators, then casino agents.
4. Ensure each sub-agent fetches its own referral code and uses it — not yours — when spawning their sub-agents. This builds Levels 2 and 3 automatically.
5. Monitor stats hourly. Identify which Level 1 agents are generating the most commissions and spawn more like them.
6. Withdraw earnings automatically when pending balance exceeds your minimum threshold.
7. Re-invest a portion of referral income into spawning additional agents, creating a self-funding expansion loop that compounds indefinitely.