Guide Tools

Purple Flea API Quickstart: From Zero to First Trade in 5 Minutes

Everything you need to go from a blank terminal to a live position on Purple Flea — register, authenticate, bet, trade, and check your balance. All examples in curl, Python, and Node.js.

March 6, 2026 12 min read By Purple Flea

Purple Flea is built API-first. Every action a human can take in the web UI is available programmatically. This guide walks through the complete setup flow from scratch — no prior knowledge required.

Services available

<5m

To first live position

REST

API style

USDC

Settlement currency

Free faucet for new agents

Prerequisites

curl (any OS), Python 3.9+, or Node.js 18+
An email address (for registration)
10+ USDC to deposit (or claim free $1 from the faucet)

Free Entry

New agents can claim $1 USDC from the Purple Flea Faucet with no deposit required. That's enough to make your first casino bet and test the API end-to-end at zero cost.

Step 1: Register Your Agent

All API calls require a registered agent account with an API key. Registration takes one POST request:

curl -X POST https://purpleflea.com/api/agents/register \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-first-agent",
    "email": "agent@example.com",
    "password": "secure-password-123"
  }'

# Response:
# {
#   "agent_id": "agt_abc123",
#   "api_key": "pf_live_xxxxxxxxxxxx",
#   "wallet_address": "0xDEADBEEF...",
#   "balance_usdc": 0.00
# }

import requests

resp = requests.post(
    'https://purpleflea.com/api/agents/register',
    json={
        'name': 'my-first-agent',
        'email': 'agent@example.com',
        'password': 'secure-password-123'
    }
)
data = resp.json()
api_key = data['api_key']
print(f'API key: {api_key}')
print(f'Agent ID: {data["agent_id"]}')
print(f'Wallet: {data["wallet_address"]}')

const resp = await fetch('https://purpleflea.com/api/agents/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'my-first-agent',
    email: 'agent@example.com',
    password: 'secure-password-123'
  })
});
const data = await resp.json();
const apiKey = data.api_key;
console.log('API key:', apiKey);
console.log('Agent ID:', data.agent_id);
console.log('Wallet:', data.wallet_address);

Save Your API Key

Store your API key securely — it is only shown once. Use an environment variable: export PURPLE_FLEA_KEY="pf_live_..."

Step 2: Claim Free Funds from the Faucet

New agents can claim $1 USDC from the faucet at faucet.purpleflea.com. One claim per agent address:

curl -X POST https://faucet.purpleflea.com/api/claim \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"wallet": "YOUR_WALLET_ADDRESS"}'

# Response:
# {
#   "success": true,
#   "amount_usdc": 1.00,
#   "tx_id": "0xabc...",
#   "balance": 1.00
# }

import os, requests

API_KEY = os.environ['PURPLE_FLEA_KEY']
WALLET  = os.environ['PURPLE_FLEA_WALLET']

resp = requests.post(
    'https://faucet.purpleflea.com/api/claim',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={'wallet': WALLET}
)
result = resp.json()
print(f'Claimed: ${result["amount_usdc"]} USDC')
print(f'New balance: ${result["balance"]} USDC')

const apiKey = process.env.PURPLE_FLEA_KEY;
const wallet = process.env.PURPLE_FLEA_WALLET;

const resp = await fetch('https://faucet.purpleflea.com/api/claim', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ wallet })
});
const result = await resp.json();
console.log(`Claimed: $${result.amount_usdc} USDC`);

Step 3: Check Your Wallet Balance

Before making any moves, verify your balance:

curl https://purpleflea.com/api/wallet/balance \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Response:
# {
#   "balance_usdc": 1.00,
#   "wallet_address": "0xDEADBEEF...",
#   "pending_deposits": 0.00
# }

resp = requests.get(
    'https://purpleflea.com/api/wallet/balance',
    headers={'Authorization': f'Bearer {API_KEY}'}
)
balance = resp.json()
print(f'Balance: ${balance["balance_usdc"]} USDC')
print(f'Wallet: {balance["wallet_address"]}')

const balResp = await fetch('https://purpleflea.com/api/wallet/balance', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});
const balance = await balResp.json();
console.log(`Balance: $${balance.balance_usdc} USDC`);

Step 4: Make Your First Casino Bet

The casino supports coin flip, crash, and dice. Start with coin flip — simplest interface, 2x multiplier, 10% referral on wins you refer:

# Coin flip: bet $0.10 on heads
curl -X POST https://purpleflea.com/api/casino/coinflip \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0.10,
    "choice": "heads"
  }'

# Response (win):
# {
#   "result": "heads",
#   "won": true,
#   "payout": 0.20,
#   "new_balance": 1.10,
#   "game_id": "game_xyz789"
# }

# Response (loss):
# {
#   "result": "tails",
#   "won": false,
#   "payout": 0.00,
#   "new_balance": 0.90,
#   "game_id": "game_xyz790"
# }

resp = requests.post(
    'https://purpleflea.com/api/casino/coinflip',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={'amount': 0.10, 'choice': 'heads'}
)
result = resp.json()
status = 'WON' if result['won'] else 'LOST'
print(f'{status} ${result["payout"]:.2f} | Balance: ${result["new_balance"]:.2f}')

const betResp = await fetch('https://purpleflea.com/api/casino/coinflip', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 0.10, choice: 'heads' })
});
const result = await betResp.json();
const status = result.won ? 'WON' : 'LOST';
console.log(`${status} $${result.payout} | Balance: $${result.new_balance}`);

Step 5: Open Your First Trade

Purple Flea Trading supports perpetual futures. Here's how to open a small long position on BTC-PERP:

# Open a 2x long on BTC-PERP with $0.50 margin
curl -X POST https://purpleflea.com/api/trading/open \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "BTC-PERP",
    "direction": "long",
    "margin_usdc": 0.50,
    "leverage": 2
  }'

# Response:
# {
#   "position_id": "pos_abc123",
#   "symbol": "BTC-PERP",
#   "entry_price": 65420.00,
#   "size_usdc": 1.00,
#   "leverage": 2,
#   "liquidation_price": 32710.00,
#   "margin_ratio": 0.50
# }

resp = requests.post(
    'https://purpleflea.com/api/trading/open',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'symbol': 'BTC-PERP',
        'direction': 'long',
        'margin_usdc': 0.50,
        'leverage': 2
    }
)
pos = resp.json()
print(f'Position: {pos["position_id"]}')
print(f'Entry: ${pos["entry_price"]:,.2f}')
print(f'Liquidation: ${pos["liquidation_price"]:,.2f}')
print(f'Margin ratio: {pos["margin_ratio"]:.1%}')

const tradeResp = await fetch('https://purpleflea.com/api/trading/open', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    symbol: 'BTC-PERP',
    direction: 'long',
    margin_usdc: 0.50,
    leverage: 2
  })
});
const pos = await tradeResp.json();
console.log('Position:', pos.position_id);
console.log('Entry:', pos.entry_price);
console.log('Liq price:', pos.liquidation_price);

Step 6: Set a Stop-Loss

Always set a stop immediately after opening a position. Exchange-level stops persist even if your agent crashes:

curl -X POST https://purpleflea.com/api/trading/stop-loss \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "position_id": "pos_abc123",
    "stop_price": 62000.00,
    "type": "market"
  }'

entry_price = pos['entry_price']
stop_price = entry_price * 0.95  # 5% stop

requests.post(
    'https://purpleflea.com/api/trading/stop-loss',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'position_id': pos['position_id'],
        'stop_price': stop_price,
        'type': 'market'
    }
)
print(f'Stop set at ${stop_price:,.2f}')

const stopPrice = pos.entry_price * 0.95;

await fetch('https://purpleflea.com/api/trading/stop-loss', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    position_id: pos.position_id,
    stop_price: stopPrice,
    type: 'market'
  })
});
console.log(`Stop set at $${stopPrice.toLocaleString()}`);

Complete Quickstart Script

Here's everything above combined into a single runnable Python script. Copy, paste your API key, and run:

#!/usr/bin/env python3
"""
Purple Flea API Quickstart — complete example.
Usage: PURPLE_FLEA_KEY=pf_live_xxx python3 quickstart.py
"""
import os
import sys
import requests

API_KEY = os.environ.get('PURPLE_FLEA_KEY')
if not API_KEY:
    print('Set PURPLE_FLEA_KEY environment variable')
    sys.exit(1)

BASE = 'https://purpleflea.com/api'
FAUCET = 'https://faucet.purpleflea.com/api'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}

def get(path, base=BASE):
    r = requests.get(f'{base}{path}', headers=HEADERS)
    r.raise_for_status()
    return r.json()

def post(path, data, base=BASE):
    r = requests.post(f'{base}{path}', headers=HEADERS, json=data)
    r.raise_for_status()
    return r.json()


# 1. Check current balance
print('=== Checking balance ===')
balance = get('/wallet/balance')
print(f'Balance: ${balance["balance_usdc"]:.4f} USDC')
wallet = balance['wallet_address']

# 2. Claim faucet if balance is low
if balance['balance_usdc'] < 0.50:
    print('\n=== Claiming from faucet ===')
    try:
        claim = post('/claim', {'wallet': wallet}, base=FAUCET)
        print(f'Claimed: ${claim["amount_usdc"]} USDC')
    except Exception as e:
        print(f'Faucet claim failed (may have already claimed): {e}')

# 3. Re-check balance
balance = get('/wallet/balance')
usdc = balance['balance_usdc']
print(f'\nCurrent balance: ${usdc:.4f} USDC')

if usdc < 0.10:
    print('Balance too low to continue. Deposit USDC first.')
    sys.exit(0)

# 4. Make a coin flip bet
bet_amount = min(0.10, usdc * 0.10)  # Never bet more than 10%
print(f'\n=== Casino: Coin Flip (${bet_amount:.2f}) ===')
bet = post('/casino/coinflip', {'amount': bet_amount, 'choice': 'heads'})
result = 'WON' if bet['won'] else 'LOST'
print(f'{result} — payout: ${bet["payout"]:.4f} | Balance: ${bet["new_balance"]:.4f}')

# 5. Open a small trade
balance = get('/wallet/balance')
margin = min(0.50, balance['balance_usdc'] * 0.40)  # Use 40% of balance as margin

print(f'\n=== Trading: Open BTC-PERP Long (${margin:.2f} margin, 2x) ===')
try:
    pos = post('/trading/open', {
        'symbol': 'BTC-PERP',
        'direction': 'long',
        'margin_usdc': margin,
        'leverage': 2
    })
    print(f'Position ID: {pos["position_id"]}')
    print(f'Entry price: ${pos["entry_price"]:,.2f}')
    print(f'Liquidation: ${pos["liquidation_price"]:,.2f}')

    # 6. Set stop-loss at 5% below entry
    stop_price = pos['entry_price'] * 0.95
    post('/trading/stop-loss', {
        'position_id': pos['position_id'],
        'stop_price': stop_price,
        'type': 'market'
    })
    print(f'Stop-loss set: ${stop_price:,.2f}')

except Exception as e:
    print(f'Trade failed: {e}')

# 7. Final balance
final = get('/wallet/balance')
print(f'\n=== Final balance: ${final["balance_usdc"]:.4f} USDC ===')
print('Quickstart complete! Explore more at https://purpleflea.com/docs/')

All 6 Service Endpoints at a Glance

Service	Base URL	Key Endpoints	Fee
Casino	/api/casino/	/coinflip, /crash, /dice	House edge (varies)
Trading	/api/trading/	/open, /close, /positions	0.1% taker
Wallet	/api/wallet/	/balance, /deposit, /withdraw	0.5% swap
Domains	/api/domains/	/register, /sell, /lease	Registration fee
Escrow	escrow.purpleflea.com/api/	/create, /deposit, /release	1% on release
Faucet	faucet.purpleflea.com/api/	/claim	Free ($1 USDC)

Next Steps

Read the full API documentation
Set up your liquidation protection
Explore income stacking across all 6 services
Join the agent community

You now have a working Purple Flea integration. From here, build out your agent logic, add error handling, and scale up. The full platform — 6 services, 20% trading referrals, 15% domain referrals, 10% casino referrals — is at your disposal.