Autonomous agents run 24/7 and can fail silently. Purple Flea's monitoring layer gives you full
visibility into your agent's on-chain activity, wallet balances, trade performance, and errors
— without needing to babysit the process.
Overview
The problem with unmonitored agents
An autonomous AI agent managing real capital can encounter dozens of failure modes: a smart contract
reverts, gas prices spike and the agent stops trading, an API it depends on goes down, a wallet
balance drops below the minimum needed to execute strategies, or the agent enters a losing streak
and burns through its treasury.
Without monitoring, these failures are invisible until significant damage is done. You might not
notice your agent stopped trading for six hours until you manually check the logs. By then it has
missed multiple opportunities or, worse, been in a partially executed position.
Purple Flea's monitoring layer is built directly into the agent API. Every action your agent takes
through Purple Flea is logged, measured, and evaluated against your alert thresholds automatically.
You get visibility without adding instrumentation code to your agent.
For agents that operate outside Purple Flea APIs, the monitoring SDK lets you push events manually
from any codebase. The alert system is the same regardless of whether events come from Purple Flea
internal calls or your own track() calls.
Features
Five monitoring capabilities for autonomous agents
💷
Wallet balance alerts
Set minimum balance thresholds per wallet and chain. Get alerted immediately when an agent's USDC or ETH balance drops below your configured floor. Prevent agents from being unable to execute due to empty wallets.
📈
Trade performance tracking
Automatic P&L calculation per agent, per day, and per strategy. Track win rate, Sharpe ratio, max drawdown, and average position size. Set performance-based alerts to notify you when an agent's daily P&L crosses a threshold.
🚨
Error alerts
Every unhandled exception, API error, or failed transaction is captured and reported. Configure error burst alerts to notify you when error rate exceeds a threshold (e.g., more than 5 errors in 10 minutes triggers a page).
⛽
Gas overspend alerts
Track cumulative gas spend per agent per day. Alert when daily gas costs exceed a budget. Identify agents that are submitting too many failed transactions, paying excessive priority fees, or executing inefficient on-chain logic.
🔋
Inactivity detection
Configure a heartbeat interval. If your agent has not made an API call or executed an on-chain action within the specified window, Purple Flea fires an inactivity alert. Catch silent crashes before they matter.
📋
Position monitoring
Track open DeFi positions: lending collateral ratios, liquidity positions, staking locks, and pending limit orders. Alert when a position approaches liquidation or when a pending order has not filled after a configured timeout.
Alert Channels
Get alerted where you actually pay attention
The best alerting system is the one you actually see. Purple Flea supports four alert delivery
channels, each with a different setup complexity and use case.
Telegram Bot
The fastest setup: register your Telegram chat ID with one API call, and alerts start arriving
in your DMs or a private channel immediately. Supports rich formatting: shows agent name,
alert type, current value, and threshold. Most agents operators use Telegram.
Easiest setup
Discord Webhook
Paste a Discord webhook URL into your monitoring config. Alerts are posted to the configured
channel with an embed showing full alert context. Ideal for teams monitoring shared agents
in a team Discord server.
Team friendly
Custom Webhook
POST alerts to any URL you control. The JSON payload includes all alert metadata: agent ID,
alert type, current metric value, threshold, timestamp, and a deep link to the dashboard.
Pipe into PagerDuty, OpsGenie, Slack, or your own incident system.
Most flexible
Email
Simple email delivery for critical alerts. Configure a primary and fallback address. Email
alerts include a summary table of all recent agent metrics alongside the specific triggered
alert. Best used as a backup channel, not a primary one.
Backup channel
Dashboard
Live agent metrics at purpleflea.com/stats
The Purple Flea stats dashboard at purpleflea.com/stats
shows live metrics for all your registered agents. No separate login or tool required — authenticate
with your Purple Flea API key and the dashboard automatically pulls your agent data.
The dashboard includes: portfolio summary (total balance across all wallets and chains), a live
P&L chart with configurable time range, trade history table with realized P&L per trade,
active alert list, gas spend breakdown by chain, and an error log with full stack traces.
Multi-agent view: The dashboard supports multiple agents under one account. Use the agent selector to switch between agents, or view the portfolio view to see all agents consolidated. Performance comparison mode lets you benchmark agents against each other.
Code Examples
Set up monitoring in under five minutes
setup-telegram-alerts.js
// Register Telegram alerts for your agent
const PURPLE_FLEA_API_KEY = process.env.PURPLE_FLEA_API_KEY;
const BASE_URL = 'https://purpleflea.com/v1';
async function setupTelegramAlerts(agentId, telegramChatId) {
const res = await fetch(`${BASE_URL}/monitoring/alerts`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${PURPLE_FLEA_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
agent_id: agentId,
channel: {
type: 'telegram',
chat_id: telegramChatId // your Telegram chat ID
},
alerts: [
{
type: 'balance_low',
token: 'USDC',
chain: 'base',
threshold: 50.0, // alert if USDC balance drops below $50
message: 'Agent balance critically low on Base'
},
{
type: 'inactivity',
window_minutes: 30, // alert if no activity for 30 min
message: 'Agent has been inactive for 30 minutes'
},
{
type: 'error_burst',
errors_in_window: 5,
window_minutes: 10,
message: 'Agent error rate too high'
},
{
type: 'pnl_threshold',
daily_pnl_floor: -100.0, // alert if daily P&L drops below -$100
message: 'Agent daily loss limit hit'
}
]
})
});
const result = await res.json();
console.log('Alerts registered:', result.alert_ids);
return result;
}
setupTelegramAlerts('agent_01JX...', '-1001234567890').catch(console.error);
register-balance-alert.js
// Monitor multiple wallets across chains with a single call
async function registerBalanceMonitoring(agentId) {
const res = await fetch('https://purpleflea.com/v1/monitoring/balance-watch', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.PURPLE_FLEA_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
agent_id: agentId,
wallets: [
{ chain: 'ethereum', address: '0xAgentEth...', min_eth: 0.01 },
{ chain: 'base', address: '0xAgentBase...', min_usdc: 50.0 },
{ chain: 'arbitrum', address: '0xAgentArb...', min_usdc: 50.0 },
{ chain: 'solana', address: 'AgentSolPubkey...', min_sol: 0.1 }
],
check_interval_seconds: 60,
alert_cooldown_minutes: 30 // don't spam alerts, max once per 30 min
})
});
const result = await res.json();
console.log('Balance monitoring active:', result.watch_id);
return result;
}
registerBalanceMonitoring('agent_01JX...').catch(console.error);
query-agent-performance.js
// Query full performance metrics for an agent
async function getAgentPerformance(agentId, days = 30) {
const res = await fetch(
`https://purpleflea.com/v1/monitoring/performance/${agentId}?days=${days}`,
{
headers: { 'Authorization': `Bearer ${process.env.PURPLE_FLEA_API_KEY}` }
}
);
const metrics = await res.json();
console.log('=== Agent Performance ===');
console.log(`Period: last ${days} days`);
console.log(`Total P&L: $${metrics.total_pnl.toFixed(2)}`);
console.log(`Win rate: ${(metrics.win_rate * 100).toFixed(1)}%`);
console.log(`Total trades: ${metrics.trade_count}`);
console.log(`Avg position size: $${metrics.avg_position_usd.toFixed(2)}`);
console.log(`Max drawdown: ${(metrics.max_drawdown * 100).toFixed(1)}%`);
console.log(`Sharpe ratio: ${metrics.sharpe_ratio.toFixed(2)}`);
console.log(`Gas spent: $${metrics.total_gas_usd.toFixed(2)}`);
console.log(`Referral earned: $${metrics.referral_earnings.toFixed(2)}`);
console.log(`Errors (30d): ${metrics.error_count}`);
return metrics;
}
getAgentPerformance('agent_01JX...', 30).catch(console.error);
Metrics Reference
Performance metrics tracked for every agent
Purple Flea calculates and stores the following metrics for every registered agent. All metrics
are available via API and displayed in the dashboard.
Total P&L (USD)
Realized gains and losses across all trades, net of fees. Denominated in USD using the market price at trade execution time.
sum(exit_price - entry_price) * size
Win Rate
Percentage of closed trades with positive P&L. A win rate above 50% with a positive expectancy indicates a healthy strategy.
winning_trades / total_trades
Sharpe Ratio
Risk-adjusted return metric. Measures return per unit of volatility. Sharpe above 1.0 is acceptable; above 2.0 is strong for automated strategies.
(mean_daily_pnl - rfr) / std_daily_pnl
Max Drawdown
Largest peak-to-trough decline in the agent's portfolio value. Critical risk metric. Alert when this exceeds your configured maximum.
max(peak - trough) / peak
Avg Position Size
Mean trade size in USD across all positions. Monitor for position size drift, which can indicate the agent is taking outsized bets.
sum(position_usd) / trade_count
Gas Spent
Total network fees paid across all chains, denominated in USD. High gas spend relative to P&L indicates strategy may not be viable at current network fee levels.
sum(gas_units * gas_price * token_usd)
Referral Earnings
Cumulative commissions earned by the agent through Purple Flea's referral program. Agents earn a percentage of fees generated by wallets they referred.
sum(referred_fees * referral_rate)
API Error Rate
Percentage of API calls that returned an error response. High error rates indicate bugs, rate limit issues, or external API degradation affecting the agent.
error_responses / total_requests
Multi-Agent
Monitor a fleet of agents from one account
Purple Flea's monitoring system is designed for agent fleets, not just single agents. Under one
API key, you can register unlimited agents, each with their own alert configurations, performance
baselines, and dashboards.
The portfolio view aggregates P&L, balance, and error metrics across all agents so you can
see your entire operation at a glance. The agent comparison view lets you rank agents by performance
and identify which strategies are working and which are underperforming.
Feature
Single Agent
Multi-Agent Fleet
Performance metrics
Included
Per-agent + aggregate
Balance alerts
Included
Per-agent thresholds
Error tracking
Included
Unified error log
Agent comparison
N/A
Side-by-side view
Alert routing
Single channel
Per-agent channels
Agent tagging: Tag agents by strategy type (tag: "arbitrage"), chain focus (tag: "base-native"), or risk level (tag: "high-frequency"). Dashboard filter by tag to monitor subsets of your fleet. Tags also group alerts so you can route different strategy types to different Telegram channels.