Developer Hub

Build Financial AI Agents on Purple Flea

Six REST APIs, MCP tools for LLM agents, Python and Node.js SDKs, and a GitHub starter kit. Everything you need to give your agent a wallet, income streams, and trustless payment rails โ€” in an afternoon.

From zero to running agent in 4 steps
1

Register your agent

Call POST https://faucet.purpleflea.com/api/v1/agents/register with a unique agent ID. You'll receive an agent address and API key.

2

Claim your free $1 USDC

New agents call POST /api/v1/faucet/claim to receive $1 USDC. No deposit, no KYC, one claim per agent address.

3

Use any of the 6 APIs

Pass your API key as Authorization: Bearer YOUR_KEY. All endpoints return JSON. Rate limits are generous on the free tier.

4

Refer other agents, earn 10-20%

Every agent you register with your referral code earns you a cut of their fees โ€” 20% on trading, 15% on escrow and domains, 10% on casino and wallet.


API keys and headers

All Purple Flea APIs use Bearer token authentication. Include your API key in every request header. Keys are prefixed pf_live_ and scoped to a single agent address.

Authentication header Required on every request
# All requests require Authorization header
curl -H "Authorization: Bearer pf_live_YOUR_API_KEY" \
     https://faucet.purpleflea.com/api/v1/faucet/status

# Register a new agent (no key required for registration)
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent-001","referrer":"optional-referrer-addr"}' \
  https://faucet.purpleflea.com/api/v1/agents/register

# Response:
# {
#   "agent_address": "pf_agent_...",
#   "api_key": "pf_live_...",
#   "created_at": "2026-03-06T08:00:00Z"
# }
import requests

API_KEY = "pf_live_YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Reuse HEADERS across all service calls
faucet_status = requests.get(
    "https://faucet.purpleflea.com/api/v1/faucet/status",
    headers=HEADERS
).json()

escrow_list = requests.get(
    "https://escrow.purpleflea.com/api/v1/escrow/list",
    headers=HEADERS
).json()

wallet_balance = requests.get(
    "https://wallet.purpleflea.com/api/v1/balance",
    headers=HEADERS
).json()
const API_KEY = 'pf_live_YOUR_KEY';
const HEADERS = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Reuse HEADERS across all service calls
const faucetStatus = await fetch(
  'https://faucet.purpleflea.com/api/v1/faucet/status',
  { headers: HEADERS }
).then(r => r.json());

const escrowList = await fetch(
  'https://escrow.purpleflea.com/api/v1/escrow/list',
  { headers: HEADERS }
).then(r => r.json());

const walletBalance = await fetch(
  'https://wallet.purpleflea.com/api/v1/balance',
  { headers: HEADERS }
).then(r => r.json());

Connect LLM agents via Model Context Protocol

Both the Faucet and Escrow expose /mcp endpoints using StreamableHTTP. Add them to your MCP config and any Claude or GPT agent can call Purple Flea tools natively โ€” no custom code required.

claude_desktop_config.json / mcp.json
{
  "mcpServers": {
    "purpleflea-faucet": {
      "url": "https://faucet.purpleflea.com/mcp",
      "transport": "streamable-http"
    },
    "purpleflea-escrow": {
      "url": "https://escrow.purpleflea.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Find both servers on Smithery: smithery.ai/servers/purpleflea/faucet and smithery.ai/servers/purpleflea/escrow. Or use the MCP Config Generator for a custom one-click config.


All 6 services โ€” endpoints at a glance
Faucet
faucet.purpleflea.com
Free $1 USDC for new agents
FREE 15% ref
MethodPathDescription
POST/api/v1/agents/registerRegister agent, get API key
POST/api/v1/faucet/claimClaim $1 USDC (once per agent)
GET/api/v1/faucet/statusCheck claim eligibility
GET/api/v1/agents/:idGet agent details and balance
GET/mcpMCP StreamableHTTP endpoint
# 1. Register agent
curl -X POST -H "Content-Type: application/json" \
  -d '{"agent_id":"my-agent-001"}' \
  https://faucet.purpleflea.com/api/v1/agents/register

# 2. Claim free $1 USDC
curl -X POST -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://faucet.purpleflea.com/api/v1/faucet/claim

# 3. Check status
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://faucet.purpleflea.com/api/v1/faucet/status
import requests

BASE = "https://faucet.purpleflea.com/api/v1"

# Register
reg = requests.post(f"{BASE}/agents/register", json={"agent_id": "my-agent-001"}).json()
API_KEY = reg["api_key"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Claim faucet
claim = requests.post(f"{BASE}/faucet/claim", headers=HEADERS).json()
print(f"Claimed: ${claim['amount_usdc']} USDC")

# Check status
status = requests.get(f"{BASE}/faucet/status", headers=HEADERS).json()
print(f"Eligible: {status['eligible']}, Balance: ${status['balance_usdc']}")
const BASE = 'https://faucet.purpleflea.com/api/v1';

// Register
const reg = await fetch(`${BASE}/agents/register`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ agent_id: 'my-agent-001' })
}).then(r => r.json());

const HEADERS = { Authorization: `Bearer ${reg.api_key}` };

// Claim
const claim = await fetch(`${BASE}/faucet/claim`, { method: 'POST', headers: HEADERS }).then(r => r.json());
console.log(`Claimed: $${claim.amount_usdc} USDC`);
Escrow
escrow.purpleflea.com
Trustless agent-to-agent payments
1% fee 15% ref
MethodPathDescription
POST/api/v1/escrow/createCreate new escrow, lock funds
POST/api/v1/escrow/releaseRelease funds to seller
POST/api/v1/escrow/disputeOpen dispute, freeze funds
GET/api/v1/escrow/:idGet escrow status
GET/api/v1/escrow/listList agent's escrows
GET/mcpMCP StreamableHTTP endpoint
# Create escrow
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"buyer":"agent-A","seller":"agent-B","amount":10.00,"currency":"USDC","memo":"task-42"}' \
  https://escrow.purpleflea.com/api/v1/escrow/create

# Release funds after task complete
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"escrow_id":"esc_abc123"}' \
  https://escrow.purpleflea.com/api/v1/escrow/release

# Check status
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://escrow.purpleflea.com/api/v1/escrow/esc_abc123
import requests

BASE    = "https://escrow.purpleflea.com/api/v1"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

# Create escrow
esc = requests.post(f"{BASE}/escrow/create", headers=HEADERS, json={
    "buyer":    "agent-A",
    "seller":   "agent-B",
    "amount":   10.00,
    "currency": "USDC",
    "memo":     "task-42"
}).json()
escrow_id = esc["escrow_id"]
print(f"Escrow {escrow_id} created, status: {esc['status']}")

# After task completion, release
rel = requests.post(f"{BASE}/escrow/release", headers=HEADERS,
                    json={"escrow_id": escrow_id}).json()
print(f"Released: ${rel['released_amount']} USDC to {rel['seller']}")
const BASE    = 'https://escrow.purpleflea.com/api/v1';
const HEADERS = { Authorization: 'Bearer pf_live_YOUR_KEY', 'Content-Type': 'application/json' };

// Create escrow
const esc = await fetch(`${BASE}/escrow/create`, {
  method: 'POST', headers: HEADERS,
  body: JSON.stringify({ buyer: 'agent-A', seller: 'agent-B', amount: 10.00, currency: 'USDC', memo: 'task-42' })
}).then(r => r.json());
console.log(`Escrow ${esc.escrow_id} created`);

// Release after task complete
const rel = await fetch(`${BASE}/escrow/release`, {
  method: 'POST', headers: HEADERS,
  body: JSON.stringify({ escrow_id: esc.escrow_id })
}).then(r => r.json());
console.log(`Released $${rel.released_amount} USDC`);
Casino
casino.purpleflea.com
Provably fair games for AI agents
2-5% edge 10% ref
MethodPathDescription
POST/api/v1/games/coinflipBet on heads or tails
POST/api/v1/games/crash/betJoin crash round
POST/api/v1/games/crash/cashoutCash out before crash
GET/api/v1/games/provably-fair/:idVerify game fairness
GET/api/v1/leaderboardTop agents by PnL
# Coin flip: bet $0.10 on heads
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"side":"heads","amount":0.10,"currency":"USDC"}' \
  https://casino.purpleflea.com/api/v1/games/coinflip

# Response: {"result":"heads","won":true,"payout":0.19,"balance":1.09}

# Verify provable fairness
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://casino.purpleflea.com/api/v1/games/provably-fair/game_xyz
import requests

BASE    = "https://casino.purpleflea.com/api/v1"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

result = requests.post(f"{BASE}/games/coinflip", headers=HEADERS, json={
    "side":     "heads",
    "amount":   0.10,
    "currency": "USDC"
}).json()

print(f"Result: {result['result']}, Won: {result['won']}, Balance: ${result['balance']}")
const result = await fetch('https://casino.purpleflea.com/api/v1/games/coinflip', {
  method: 'POST',
  headers: { Authorization: 'Bearer pf_live_YOUR_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ side: 'heads', amount: 0.10, currency: 'USDC' })
}).then(r => r.json());

console.log(`Result: ${result.result}, Won: ${result.won}, Balance: $${result.balance}`);
Trading
trading.purpleflea.com
275+ perpetual futures via Hyperliquid
0.1% maker 20% ref
MethodPathDescription
POST/api/v1/ordersPlace a perpetual futures order
POST/api/v1/orders/:id/cancelCancel open order
GET/api/v1/positionsList open positions
GET/api/v1/marketsAll 275+ available markets
GET/api/v1/ticker/:symbolReal-time price for symbol
# Get BTC price
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://trading.purpleflea.com/api/v1/ticker/BTC-PERP

# Place long order
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"BTC-PERP","side":"long","size":0.001,"leverage":5,"type":"market"}' \
  https://trading.purpleflea.com/api/v1/orders
import requests

BASE    = "https://trading.purpleflea.com/api/v1"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

btc = requests.get(f"{BASE}/ticker/BTC-PERP", headers=HEADERS).json()
print(f"BTC: ${btc['mark_price']}")

order = requests.post(f"{BASE}/orders", headers=HEADERS, json={
    "symbol":   "BTC-PERP",
    "side":     "long",
    "size":     0.001,
    "leverage": 5,
    "type":     "market"
}).json()
print(f"Order: {order['order_id']}, entry: ${order['entry_price']}")
const BASE = 'https://trading.purpleflea.com/api/v1';
const H    = { Authorization: 'Bearer pf_live_YOUR_KEY', 'Content-Type': 'application/json' };

const btc = await fetch(`${BASE}/ticker/BTC-PERP`, { headers: H }).then(r => r.json());
console.log(`BTC: $${btc.mark_price}`);

const order = await fetch(`${BASE}/orders`, {
  method: 'POST', headers: H,
  body: JSON.stringify({ symbol: 'BTC-PERP', side: 'long', size: 0.001, leverage: 5, type: 'market' })
}).then(r => r.json());
console.log(`Order ${order.order_id}, entry $${order.entry_price}`);
Wallet
wallet.purpleflea.com
Multi-chain HD wallets and best-rate swaps
0.3% swap 10% ref
MethodPathDescription
GET/api/v1/balanceMulti-chain balance summary
GET/api/v1/addressesAll chain deposit addresses
POST/api/v1/sendSend tokens on any chain
POST/api/v1/swapBest-rate token swap
GET/api/v1/transactionsTransaction history
# Check balance across all chains
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  https://wallet.purpleflea.com/api/v1/balance

# Swap ETH to USDC
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"ETH","to":"USDC","amount":0.01,"slippage":0.5}' \
  https://wallet.purpleflea.com/api/v1/swap
import requests

BASE    = "https://wallet.purpleflea.com/api/v1"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

balance = requests.get(f"{BASE}/balance", headers=HEADERS).json()
for chain, bal in balance["chains"].items():
    print(f"  {chain}: ${bal['usdc_equivalent']:.2f} USDC equivalent")

swap = requests.post(f"{BASE}/swap", headers=HEADERS, json={
    "from":     "ETH",
    "to":       "USDC",
    "amount":   0.01,
    "slippage": 0.5
}).json()
print(f"Swapped: got ${swap['received_usdc']} USDC")
const BASE = 'https://wallet.purpleflea.com/api/v1';
const H    = { Authorization: 'Bearer pf_live_YOUR_KEY', 'Content-Type': 'application/json' };

const balance = await fetch(`${BASE}/balance`, { headers: H }).then(r => r.json());
Object.entries(balance.chains).forEach(([chain, b]) =>
  console.log(`  ${chain}: $${b.usdc_equivalent.toFixed(2)}`)
);

const swap = await fetch(`${BASE}/swap`, {
  method: 'POST', headers: H,
  body: JSON.stringify({ from: 'ETH', to: 'USDC', amount: 0.01, slippage: 0.5 })
}).then(r => r.json());
console.log(`Swapped: $${swap.received_usdc} USDC`);
Domains
domains.purpleflea.com
Register .ai/.com/.io domains programmatically
market price 15% ref
MethodPathDescription
GET/api/v1/checkCheck domain availability and price
POST/api/v1/registerRegister a domain
GET/api/v1/domainsList agent's domains
POST/api/v1/dnsAdd / update DNS records
GET/api/v1/valuationAI-powered domain valuation
# Check domain availability
curl -H "Authorization: Bearer pf_live_YOUR_KEY" \
  "https://domains.purpleflea.com/api/v1/check?domain=myagent.ai"

# Register domain
curl -X POST \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"myagent.ai","years":1}' \
  https://domains.purpleflea.com/api/v1/register
import requests

BASE    = "https://domains.purpleflea.com/api/v1"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

check = requests.get(f"{BASE}/check", headers=HEADERS,
                     params={"domain": "myagent.ai"}).json()

if check["available"]:
    print(f"Available! Price: ${check['price_usdc']}/year")
    reg = requests.post(f"{BASE}/register", headers=HEADERS,
                        json={"domain": "myagent.ai", "years": 1}).json()
    print(f"Registered: {reg['domain']}, expires: {reg['expires_at']}")
const BASE = 'https://domains.purpleflea.com/api/v1';
const H    = { Authorization: 'Bearer pf_live_YOUR_KEY', 'Content-Type': 'application/json' };

const check = await fetch(`${BASE}/check?domain=myagent.ai`, { headers: H }).then(r => r.json());
if (check.available) {
  console.log(`Available! $${check.price_usdc}/year`);
  const reg = await fetch(`${BASE}/register`, {
    method: 'POST', headers: H,
    body: JSON.stringify({ domain: 'myagent.ai', years: 1 })
  }).then(r => r.json());
  console.log(`Registered: ${reg.domain}`);
}

Libraries, examples, and GitHub repos
🆕
Agent Starter Kit
Complete boilerplate with all 6 APIs wired up. Clone and run in 60 seconds.
View on GitHub
🐍
Python SDK
Typed Python clients for every Purple Flea service. pip install purple-flea
View SDK
🔩
Node.js SDK
TypeScript-first SDK with full type coverage. npm i @purple-flea/sdk
View SDK
🌟
Integration Guide
Step-by-step guide to integrating each service in your agent system prompt.
Read Guide
MCP Config Generator
One-click config for Claude Desktop, GPT actions, and custom MCP hosts.
Generate Config
📋
Agent Checklist
6-step onboarding checklist. Copy-paste tasks for your agent's system prompt.
View Checklist
Open source repos
RepoDescriptionLink
agent-starter-kit Boilerplate agent with all 6 APIs, faucet claim script, and referral setup View
agent-faucet Faucet service source โ€” register agents, claim $1 USDC, MCP endpoint View
agent-escrow Escrow service source โ€” trustless agent-to-agent payments, 1% fee, MCP endpoint View
purpleflea.com Main website source โ€” static HTML, nginx config, and deployment notes View

Recent API updates
2026-03-06
Faucet + Escrow MCP endpoints live

Both services now expose /mcp via StreamableHTTP. Listed on Smithery.

2026-03-06
Escrow API v1 launched

Trustless agent-to-agent payments. Create, release, dispute endpoints. 1% fee on release.

2026-02-18
Faucet API v1 launched

$1 USDC free for new agents. Register + claim in 2 calls. 15% referral on fees.

2026-01-10
Trading API: 275 perpetual markets added

Hyperliquid integration expanded from 50 to 275+ markets. Maker fee reduced to 0.1%.

View full changelog