Trading API Trading

Creates a new trading account and returns your API key and referral code. No authentication required. If you have a referral code from another agent, pass it to start the referral relationship immediately.

# Request
curl -X POST https://trading.purpleflea.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-trading-agent-v1",
    "referral_code": "PFREF123"
  }'

# Response 200 OK
{
  "success": true,
  "api_key": "pf_live_trading_abc123xyz...",
  "referral_code": "TRADE456",
  "agent_id": "my-trading-agent-v1",
  "balance_usdc": 0.00,
  "created_at": "2026-03-06T09:00:00Z"
}

If you have registered before and need to retrieve your API key, authenticate with your agent ID.

# Request
curl -X POST https://trading.purpleflea.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-trading-agent-v1"}'

# Response 200 OK
{
  "success": true,
  "api_key": "pf_live_trading_abc123xyz...",
  "agent_id": "my-trading-agent-v1",
  "referral_code": "TRADE456"
}

Returns all 275+ perpetual futures markets. Filter by base_asset to narrow results.

# List all markets
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/markets

# Filter by base asset
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://trading.purpleflea.com/api/v1/markets?base_asset=BTC"

# Response 200 OK
{
  "success": true,
  "total": 275,
  "markets": [
    {
      "symbol": "BTC-PERP",
      "base_asset": "BTC",
      "quote_asset": "USDC",
      "max_leverage": 50,
      "tick_size": 0.1,
      "min_size_usd": 10,
      "status": "active"
    }
  ]
}

Returns real-time market data for a single symbol including current funding rate, open interest, 24h volume, and price data. Funding rates are charged every 8 hours.

# Get BTC perpetual market details
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/markets/BTC-PERP

# Response 200 OK
{
  "success": true,
  "market": {
    "symbol": "BTC-PERP",
    "base_asset": "BTC",
    "mark_price": 87420.50,
    "index_price": 87415.20,
    "funding_rate": 0.000100,
    "next_funding_time": "2026-03-06T16:00:00Z",
    "open_interest_usd": 4820000000,
    "volume_24h_usd": 2100000000,
    "price_change_24h_pct": 2.34,
    "high_24h": 88100.00,
    "low_24h": 85600.00,
    "max_leverage": 50,
    "maker_fee": 0.0002,
    "taker_fee": 0.0005
  }
}

Opens a long or short perpetual futures position. For market orders, the position opens immediately at the current mark price. For limit orders, the order is placed in the order book and fills when the price is reached.

# Open a long BTC position with 5x leverage
curl -X POST https://trading.purpleflea.com/api/v1/positions/open \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market": "BTC-PERP",
    "side": "long",
    "size_usd": 500,
    "leverage": 5,
    "order_type": "market",
    "stop_loss": 85000,
    "take_profit": 92000
  }'

# Response 200 OK
{
  "success": true,
  "position": {
    "id": "pos_7f3a9b2c",
    "market": "BTC-PERP",
    "side": "long",
    "size_usd": 500,
    "leverage": 5,
    "margin_usd": 100,
    "entry_price": 87420.50,
    "liquidation_price": 70120.40,
    "stop_loss": 85000,
    "take_profit": 92000,
    "status": "open",
    "opened_at": "2026-03-06T09:12:00Z",
    "fee_usdc": 0.25
  }
}

Returns all currently open positions for your account. Includes unrealised PnL calculated at current mark price and accrued funding fees.

# Get all open positions
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/positions

# Response 200 OK
{
  "success": true,
  "positions": [
    {
      "id": "pos_7f3a9b2c",
      "market": "BTC-PERP",
      "side": "long",
      "size_usd": 500,
      "leverage": 5,
      "entry_price": 87420.50,
      "mark_price": 88100.00,
      "unrealised_pnl": 3.88,
      "pnl_pct": 3.88,
      "funding_fee_total": -0.05,
      "liquidation_price": 70120.40,
      "status": "open",
      "opened_at": "2026-03-06T09:12:00Z"
    }
  ],
  "total_unrealised_pnl": 3.88
}

Returns full detail for a single position including entry price, current size, leverage, real-time PnL, liquidation price, and cumulative funding fees paid.

# Get a specific position
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/positions/pos_7f3a9b2c

# Response 200 OK
{
  "success": true,
  "position": {
    "id": "pos_7f3a9b2c",
    "market": "BTC-PERP",
    "side": "long",
    "size_usd": 500,
    "leverage": 5,
    "margin_usd": 100,
    "entry_price": 87420.50,
    "mark_price": 88100.00,
    "liquidation_price": 70120.40,
    "unrealised_pnl": 3.88,
    "realised_pnl": 0.00,
    "funding_fee_total": -0.05,
    "stop_loss": 85000,
    "take_profit": 92000,
    "status": "open",
    "opened_at": "2026-03-06T09:12:00Z",
    "last_funding_time": "2026-03-06T08:00:00Z"
  }
}

Closes an open position at the current market price. Pass size_usd to partially close a position, or omit it to close the entire position.

# Close full position
curl -X POST https://trading.purpleflea.com/api/v1/positions/close/pos_7f3a9b2c \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Partially close $200 of a $500 position
curl -X POST https://trading.purpleflea.com/api/v1/positions/close/pos_7f3a9b2c \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size_usd": 200}'

# Response 200 OK
{
  "success": true,
  "closed": {
    "position_id": "pos_7f3a9b2c",
    "close_price": 88100.00,
    "size_closed_usd": 500,
    "realised_pnl": 3.88,
    "fee_usdc": 0.25,
    "net_pnl": 3.63,
    "status": "closed",
    "closed_at": "2026-03-06T11:45:00Z"
  }
}

# Place a limit buy for ETH at $3,200
curl -X POST https://trading.purpleflea.com/api/v1/orders/limit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market": "ETH-PERP",
    "side": "long",
    "size_usd": 1000,
    "leverage": 3,
    "limit_price": 3200.00,
    "time_in_force": "GTC"
  }'

# Response 200 OK
{
  "success": true,
  "order": {
    "id": "ord_4c8d1e2f",
    "market": "ETH-PERP",
    "side": "long",
    "type": "limit",
    "size_usd": 1000,
    "leverage": 3,
    "limit_price": 3200.00,
    "status": "pending",
    "time_in_force": "GTC",
    "created_at": "2026-03-06T09:30:00Z"
  }
}

Returns all pending and recently filled limit orders.

# Get all orders
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/orders

# Response 200 OK
{
  "success": true,
  "orders": [
    {
      "id": "ord_4c8d1e2f",
      "market": "ETH-PERP",
      "side": "long",
      "type": "limit",
      "size_usd": 1000,
      "limit_price": 3200.00,
      "status": "pending",
      "created_at": "2026-03-06T09:30:00Z"
    }
  ]
}

Cancels a pending limit order. Only orders in pending status can be cancelled.

# Cancel order
curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/orders/ord_4c8d1e2f

# Response 200 OK
{
  "success": true,
  "order_id": "ord_4c8d1e2f",
  "status": "cancelled",
  "cancelled_at": "2026-03-06T10:05:00Z"
}

Returns your current trading balance including available margin, reserved margin (in open positions), and total account equity including unrealised PnL.

# Get balance
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/balance

# Response 200 OK
{
  "success": true,
  "balance": {
    "usdc_available": 892.45,
    "usdc_in_positions": 100.00,
    "unrealised_pnl": 3.88,
    "total_equity": 996.33,
    "total_deposited": 1000.00,
    "total_realised_pnl": -7.55,
    "total_fees_paid": 3.88
  }
}

Moves USDC from your Purple Flea casino balance into your trading account. Both accounts use the same agent identity. Transfers are instant and do not incur a fee.

# Transfer $100 from casino to trading
curl -X POST https://trading.purpleflea.com/api/v1/transfer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usdc": 100,
    "direction": "casino_to_trading"
  }'

# Response 200 OK
{
  "success": true,
  "transfer_id": "txfr_9a1b3d4e",
  "amount_usdc": 100.00,
  "direction": "casino_to_trading",
  "new_trading_balance": 100.00,
  "completed_at": "2026-03-06T09:00:05Z"
}

Returns a paginated list of all closed positions and fills. Useful for computing realised PnL, analysing strategy performance, and tax reporting.

# Get last 50 closed positions
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/history

# Filter by market and date range
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://trading.purpleflea.com/api/v1/history?market=BTC-PERP&from=2026-03-01&to=2026-03-06"

# Response 200 OK
{
  "success": true,
  "total": 42,
  "history": [
    {
      "position_id": "pos_7f3a9b2c",
      "market": "BTC-PERP",
      "side": "long",
      "entry_price": 87420.50,
      "close_price": 88100.00,
      "size_usd": 500,
      "leverage": 5,
      "realised_pnl": 3.88,
      "fees_paid": 0.50,
      "funding_fees": -0.05,
      "net_pnl": 3.33,
      "close_reason": "manual",
      "opened_at": "2026-03-06T09:12:00Z",
      "closed_at": "2026-03-06T11:45:00Z"
    }
  ]
}

# Get referral stats
curl -H "X-API-Key: YOUR_API_KEY" \
  https://trading.purpleflea.com/api/v1/referrals

# Response 200 OK
{
  "success": true,
  "referral_code": "TRADE456",
  "referral_url": "https://trading.purpleflea.com?ref=TRADE456",
  "referred_agents": 3,
  "earnings_total_usdc": 12.45,
  "earnings_pending_usdc": 2.10,
  "earnings_paid_usdc": 10.35,
  "commission_rate": 0.20,
  "referrals": [
    {
      "agent_id": "agent-xyz",
      "joined_at": "2026-02-15T14:00:00Z",
      "volume_usd": 45000,
      "fees_generated_usdc": 22.50,
      "your_earnings_usdc": 4.50
    }
  ]
}

Returns the current status of the trading service. No authentication required. Use this endpoint to verify connectivity before placing orders.

# Check health
curl https://trading.purpleflea.com/health

# Response 200 OK
{
  "status": "ok",
  "service": "purple-flea-trading",
  "markets_active": 275,
  "hyperliquid_connected": true,
  "uptime_seconds": 604800,
  "version": "1.3.0",
  "timestamp": "2026-03-06T09:00:00Z"
}