Portfolio Tracker API
for AI Agents

Track Everything Your Agent Holds

An autonomous financial agent does not just hold spot tokens. It has open perpetual futures positions, yield deposits in lending protocols, LP shares, staked assets, and pending escrow payments — spread across multiple chains. The portfolio tracker API consolidates all of these into a single USD-denominated view.

Portfolio Tracker API Endpoints

Daily Performance Report Agent

The example below builds a daily performance report that fetches balances, open positions, and 30-day analytics — then logs everything or sends an alert if drawdown exceeds the threshold.

import requests
from datetime import datetime

PF_BASE = "https://purpleflea.com"
HEADERS = {"Authorization": "Bearer pf_live_YOUR_KEY"}

def daily_portfolio_report(
    max_drawdown_alert: float = -0.10,
    max_position_pct: float = 0.30
):
    print(f"=== Portfolio Report {datetime.now():%Y-%m-%d %H:%M} ===")

    # 1. Total balances across all chains
    balances = requests.get(f"{PF_BASE}/v1/portfolio/balances", headers=HEADERS).json()
    total_usd = balances["total_usd"]
    print(f"Total Portfolio: ${total_usd:,.2f}")
    for chain in balances["by_chain"]:
        print(f"  {chain['chain']}: ${chain['usd']:,.2f} ({chain['usd']/total_usd:.1%})")

    # 2. Open positions with unrealized PnL
    positions = requests.get(f"{PF_BASE}/v1/portfolio/positions", headers=HEADERS).json()
    if positions["open_count"] > 0:
        print(f"\nOpen Positions ({positions['open_count']}):")
        for pos in positions["positions"]:
            pnl_sign = "+" if pos["unrealized_pnl"] >= 0 else ""
            print(f"  {pos['symbol']} {pos['side'].upper()} x{pos['leverage']}: "
                  f"{pnl_sign}${pos['unrealized_pnl']:,.2f} | Liq: ${pos['liq_price']:,.0f}")

    # 3. 30-day performance metrics
    perf = requests.get(
        f"{PF_BASE}/v1/portfolio/performance",
        params={"window": "30d"},
        headers=HEADERS
    ).json()
    print(f"\n30-Day Performance:")
    print(f"  Total Return: {perf['total_return']:+.2%}")
    print(f"  Sharpe Ratio: {perf['sharpe_ratio']:.2f}")
    print(f"  Max Drawdown: {perf['max_drawdown']:.2%}")
    print(f"  Win Rate:     {perf['win_rate']:.1%}")
    print(f"  Profit Factor:{perf['profit_factor']:.2f}")

    # 4. Allocation check — enforce concentration limits
    alloc = requests.get(f"{PF_BASE}/v1/portfolio/allocation", headers=HEADERS).json()
    for asset in alloc["by_asset"]:
        if asset["pct"] > max_position_pct:
            print(f"  ALERT: {asset['symbol']} exceeds concentration limit ({asset['pct']:.1%} > {max_position_pct:.0%})")

    # 5. Drawdown alert
    if perf["max_drawdown"] < max_drawdown_alert:
        print(f"  ALERT: Max drawdown {perf['max_drawdown']:.2%} exceeds limit {max_drawdown_alert:.2%}")
        print(f"  Consider reducing position sizes or closing losing trades.")

    # 6. Save snapshot for tomorrow's comparison
    snap = requests.post(f"{PF_BASE}/v1/portfolio/snapshot", headers=HEADERS).json()
    print(f"\nSnapshot saved: {snap['snapshot_id']}")

if __name__ == "__main__":
    daily_portfolio_report()

Performance Metrics Returned by the API

The /v1/portfolio/performance endpoint returns a comprehensive set of trading analytics computed from the agent's trade history. All metrics are computed server-side — no client-side calculation required.

Build a Monitoring Dashboard

The portfolio tracker API is designed to be consumed by dashboards. All responses are JSON, all endpoints support CORS, and authentication uses Bearer tokens. You can build a real-time agent monitoring UI in any framework by polling the API every 30 seconds.

A minimal dashboard polls three endpoints: /v1/portfolio/balances for total value, /v1/portfolio/positions for live PnL, and /v1/portfolio/performance for analytics. Render the results as a live-updating card UI using vanilla JS, React, or any visualization library.

MCP Tools for Portfolio Tracker

All portfolio tracker endpoints are available as MCP tools. An LLM with Purple Flea's MCP server configured can call these tools to understand its own financial position before making trading decisions.

Continue Building