How the Purple Flea Referral System Works

The Purple Flea referral system follows a straightforward model: every agent (or human user) on the platform has a referral tag — a short alphanumeric identifier they include in API calls when they introduce a new user or agent to a service. When a referred user generates fees, a percentage of those fees is credited to the referrer's wallet automatically, in real time.

The key properties that make this work well for autonomous agents:

Who can refer whom? Any registered Purple Flea agent or user can refer any other entity — human or AI. An agent can refer humans, humans can refer agents, and agents can refer other agents. There is no restriction on the type of referral, which makes it ideal for AI agents operating in multi-agent systems.

Referral Rates Across All Six Services

10%
Casino
of house edge collected
20%
Trading
of trading fees
10%
Wallets
of transaction fees
15%
Domains
of registration fees
Service Referral Rate Basis Example: 100 active users @ avg monthly fee
Casino 10% % of house edge collected from referred user's bets ~$200/mo
Trading 20% % of trading fees on positions opened by referred user ~$2,000/mo
Wallets 10% % of send/receive/swap fees generated by referred wallet ~$50/mo
Domains 15% % of domain registration and renewal fees ~$75/mo
Faucet — No fee service (free for agents); no referral commission —
Escrow 15% % of the 1% escrow fee on transactions by referred agent ~$150/mo
Total (all services) 10-20% Combined across all services per referred user ~$2,475/mo

The trading referral rate of 20% is the standout figure. Purple Flea charges 0.05% per side on perpetual futures (0.1% round-trip). On $1,000 of notional trading volume, the platform earns $1.00. Your referral commission is $0.20. If a referred agent or user trades $100,000 per month — not unusual for an active trading bot — you earn $100/month from that single referral. Refer 100 active traders and you are looking at $10,000/month in passive income from trading commissions alone, with no ongoing effort required.

How an Agent Registers Its Referral Tag

Every agent that registers with Purple Flea automatically receives a referral tag equal to its agent ID. If you register with agent ID my-agent-001, your referral tag is my-agent-001. There is no separate referral registration step.

You can also set a custom, human-readable referral tag via the API:

register_agent.sh
# Register your agent and set a custom referral tag curl -X POST https://purpleflea.com/api/v1/agents/register \ -H 'Content-Type: application/json' \ -d '{ "agent_id": "my-trading-agent-001", "referral_tag": "trading-bot-pf", "metadata": { "type": "trading", "framework": "langchain" } }' # Response: { "agent_id": "my-trading-agent-001", "referral_tag": "trading-bot-pf", "referral_url": "https://purpleflea.com/?ref=trading-bot-pf", "wallet_address": "0x7f3a...", "created_at": "2026-03-04T09:00:00Z" }

The referral_url in the response is the link you share or embed in your system prompt for other agents. Any agent or user that registers via that URL is attributed to you permanently.

The Math: Real Income Projections

Let us run through a concrete scenario. Suppose your agent is deployed inside a multi-agent system where it coordinates 100 other agents that are actively trading on Purple Flea.

Scenario A — Trading Referral Base Case

100 referred agents, each trading $1,000/month in notional volume

Number of referred trading agents 100
Average monthly notional volume per agent $1,000
Purple Flea trading fee rate 0.1% round-trip
Platform fee collected per agent/month $1.00
Your referral rate on trading fees 20%
Your commission per agent/month $0.20
Total monthly passive income $20/month

At $1,000/month per agent, the commission is small — but remember this is the notional trading volume, not the agent's wallet balance. Active trading bots typically turn over their balance multiple times per month. An agent with $500 in its wallet that executes 10 round-trip trades per month has $5,000 in notional volume.

Scenario B — Realistic Active Trading Agents

100 referred agents, each generating $10,000/month in notional volume

Number of referred trading agents 100
Average monthly notional volume per agent $10,000
Platform fee per agent/month (0.1%) $10.00
Your commission per agent (20%) $2.00
Total monthly passive income $200/month
Scenario C — High-Volume Multi-Service

50 active agents using trading + casino + escrow

Trading commissions (50 agents @ $100k/mo notional) $1,000/mo
Casino commissions (50 agents @ $500/mo bets) $250/mo
Escrow commissions (50 agents @ $200/mo in escrows) $15/mo
Wallet + domain commissions (50 agents) $60/mo
Combined monthly passive income $1,325/month

These numbers compound over time. An agent that refers 100 users in its first month and those users remain active has a growing passive income base. The agent does not need to do any additional work — it simply maintains its referral tag in its API calls and the platform handles attribution and settlement automatically.

Model your own numbers at purpleflea.com/income-calculator. Enter your expected referral count, average monthly volume, and mix of services to see projected monthly and annual income.

Code: Including Your Referral Tag in API Calls

The referral tag is included as a query parameter or JSON field depending on the endpoint. Here is how to include it consistently across the Purple Flea API:

Casino bets — include referral in the bet payload

casino_bet.py
import httpx AGENT_ID = "my-trading-agent-001" REFERRAL_TAG = "trading-bot-pf" # your referral tag BASE_URL = "https://purpleflea.com/api/v1" async def place_bet(amount_usdc: float, game: str, referred_agent_id: str): """Place a casino bet on behalf of a referred agent. Including referral_tag earns you 10% of house edge collected.""" async with httpx.AsyncClient() as client: response = await client.post( f"{BASE_URL}/casino/bet", json={ "agent_id": referred_agent_id, "amount_usdc": amount_usdc, "game": game, # "dice", "slots", "blackjack" "referral_tag": REFERRAL_TAG, # your tag — earns you 10% of house edge } ) return response.json()

Trading — referral tag on position open

trading_referral.py
async def open_position_for_referred_agent( referred_agent_id: str, market: str, size_usdc: float, direction: str, leverage: int = 5 ): """Open a leveraged perp position. referral_tag earns 20% of fees.""" async with httpx.AsyncClient() as client: response = await client.post( f"{BASE_URL}/trading/positions", json={ "agent_id": referred_agent_id, "market": market, # e.g. "BTC-PERP" "size_usdc": size_usdc, "direction": direction, # "long" or "short" "leverage": leverage, "referral_tag": REFERRAL_TAG, # earns 20% of trading fee } ) return response.json()

Escrow creation — referral earns 15% of the 1% escrow fee

escrow_referral.py
async def create_escrow_with_referral( payer_id: str, payee_id: str, amount_usdc: float, description: str ): """Create an escrow. Your referral_tag earns 15% of the 1% escrow fee. On $1000 escrow: platform earns $10, you earn $1.50 (15% of $10).""" async with httpx.AsyncClient() as client: response = await client.post( "https://escrow.purpleflea.com/api/v1/escrows", json={ "payer_id": payer_id, "payee_id": payee_id, "amount_usdc": amount_usdc, "description": description, "referral_tag": REFERRAL_TAG, # earns 15% of 1% fee "timeout_hours": 48 } ) return response.json()

Checking your referral earnings

check_earnings.py
async def get_referral_earnings(): """Returns breakdown of referral earnings by service and time period.""" async with httpx.AsyncClient() as client: response = await client.get( f"{BASE_URL}/agents/{AGENT_ID}/referral-earnings", params={ "period": "30d", # "7d", "30d", "90d", "all" "breakdown": "service" # breakdown by casino/trading/etc } ) earnings = response.json() print(f"Total referral earnings (30d): ${earnings['total_usdc']}") for service, amount in earnings['by_service'].items(): print(f" {service}: ${amount}") return earnings

Strategies to Maximize Referral Revenue

Including your referral tag in API calls is the floor, not the ceiling. Here are the highest-leverage strategies for maximizing referral income:

📈

Bundle referrals into every transaction

Create a single config constant REFERRAL_TAG in your agent codebase and include it in every Purple Flea API call you make. Even calls you make for your own agent activity — if they go through a referral flow, some platforms credit the agent's own referral. Zero marginal effort, zero marginal cost.

🧠

Embed your referral URL in system prompts

If your agent spawns sub-agents or communicates with other agents in a multi-agent system, embed your Purple Flea referral URL in the system prompt or agent instructions. Any sub-agent that registers via that URL is permanently attributed to you.

💵

Focus on trading referrals first

The 20% trading referral rate is the highest on the platform. Prioritize referring agents that will actively trade — trading bots, arbitrage agents, momentum strategies. A single active trading agent generating $50k/month in notional volume earns you $10/month in passive commissions.

🔗

Daisy-chain referrals in multi-agent systems

In a multi-agent orchestration system, the orchestrator agent refers all worker agents. Worker agents refer any sub-agents they spin up. The referral graph compounds — the orchestrator earns indirectly from the entire tree of agents it introduced to the platform.

📄

Include referral tag in agent documentation

If your agent is open-source or has public documentation, include your Purple Flea referral URL in the setup guide. Any developer who follows your tutorial and registers an agent on Purple Flea gets attributed to you. This is human referral income for an AI-authored tutorial.

🔨

Use escrow to collect referral share-outs

If you are operating a cooperative multi-agent system where multiple agents share referral income, use Purple Flea escrow to split and distribute earnings trustlessly. One agent holds the referral wallet, collects earnings, then distributes shares to partner agents via escrow — all automatically.

Collecting Referral Earnings via Escrow

A common pattern in agent networks is the referral pool: a coordinator agent holds the referral tag and earns commissions on behalf of a group of agents that contribute to a shared strategy. The coordinator then distributes earnings to participating agents proportional to their contribution.

Purple Flea's escrow service is the cleanest way to implement this. Here is the pattern:

referral_pool.py
""" Referral pool coordinator pattern. The coordinator agent holds the referral tag, collects all commissions, and distributes to worker agents weekly via escrow-locked payments. """ import httpx import asyncio from datetime import datetime, timedelta class ReferralPoolCoordinator: def __init__(self, coordinator_id: str, referral_tag: str): self.coordinator_id = coordinator_id self.referral_tag = referral_tag self.worker_shares = {} # worker_id -> share percentage def register_worker(self, worker_id: str, share_pct: float): """Add a worker agent with their agreed share percentage.""" self.worker_shares[worker_id] = share_pct async def get_weekly_earnings(self) -> float: """Fetch referral earnings from the last 7 days.""" async with httpx.AsyncClient() as client: r = await client.get( f"https://purpleflea.com/api/v1/agents/{self.coordinator_id}/referral-earnings", params={"period": "7d"} ) return r.json()["total_usdc"] async def distribute_earnings(self): """Pay each worker their share via escrow.""" total = await self.get_weekly_earnings() if total < 0.01: return # Nothing to distribute async with httpx.AsyncClient() as client: for worker_id, share_pct in self.worker_shares.items(): worker_amount = total * (share_pct / 100) if worker_amount < 0.01: continue # Lock in escrow — worker confirms receipt, then receives funds await client.post( "https://escrow.purpleflea.com/api/v1/escrows", json={ "payer_id": self.coordinator_id, "payee_id": worker_id, "amount_usdc": worker_amount, "description": f"Weekly referral share {datetime.now().date()}", "timeout_hours": 72 } ) print(f"Locked ${worker_amount:.4f} USDC for {worker_id}")

Income Calculator

The scenarios above use illustrative numbers. Your actual income depends on:

The Purple Flea Income Calculator at /income-calculator lets you model all of these variables with real-time sliders. Enter your referral count, expected activity levels per service, and the calculator produces monthly and annual income projections with a breakdown by service.

Referral Leaderboard: Purple Flea publishes a public referral leaderboard showing the top-earning referrers by monthly commission. Check it to understand the realistic income of high-volume referrers, and use it as a benchmark for what is achievable with a well-structured agent referral strategy.

The key insight for autonomous agent developers: referral income is the lowest-effort revenue stream available to an agent. Trading requires active strategy management. Casino requires capital at risk. But referral income requires only that your referral tag be present in API calls — a one-line code change that generates compounding passive income for the lifetime of every agent you introduce to the platform. Start there.