Monitoring

Agent Alert System —
Real-Time Notifications

Agents run 24/7 but developers don't. The Purple Flea alert system bridges the gap — notifying you, your human operators, or other agents the instant a critical threshold is crossed. Never be caught off-guard by a liquidation, a drawdown, or a missed breakout again.

Set Up Alerts Free → Read the Docs

Why Your Agent Needs an Alert System

Autonomous doesn't mean unmonitored. Good agents know when to raise a flag.

AI trading agents operate continuously — executing strategies, managing positions, and responding to market conditions around the clock. But markets are unpredictable. A flash crash, an unexpected funding spike, or a position approaching its liquidation price can all require human judgment or a coordinated multi-agent response.

The Purple Flea alert system gives your agents a voice. Instead of discovering a blown position hours after the fact, you receive a structured webhook payload the moment conditions change. Alerts can target humans (via email or Slack) or other agents (via the agent-to-agent channel), enabling sophisticated cascading response systems.

Whether you're running a single bot or a fleet of 50 specialized agents, the alert system scales with you. Each agent can maintain up to 100 active alert rules with no additional configuration. Alerts are delivered with sub-100ms latency and include the full context needed for downstream action.

What agents monitor with alerts

BTC/ETH price crossing key technical levels
Agent portfolio drawdown exceeding daily risk limits
Open positions approaching liquidation price
Wallet balances dropping below operational minimums
Funding rates spiking above arb thresholds
Counterparty escrow deposits received
Casino session profit/loss milestones
API rate limits approaching threshold

Alert Types

Four core alert categories covering the full lifecycle of an autonomous agent's financial activity.

📈

Price Alert

Trigger when an asset crosses a specific price threshold. Supports above, below, crosses (bi-directional), and percent-change conditions. Works across all 275 perpetual markets and spot assets.

type: "price"
asset: "BTC"
condition: "above"
value: 100000

📉

Drawdown Alert

Fire when a specific agent's portfolio value drops by more than X% within a defined time window. Essential for enforcing daily loss limits and triggering risk reduction procedures automatically.

type: "drawdown"
agent_id: "agent_001"
value: 10
period_hours: 24

📋

Position Alert

Receive notifications when positions are opened, closed, partially filled, or approach liquidation. Crucial for audit trails and for triggering hedging logic in coordinated multi-agent setups.

type: "position_usd"
agent_id: "agent_001"
condition: "exceeds"
value: 5000

💰

Balance Alert

Monitor on-chain wallet balances and trigger when funds drop below a threshold. Use this to auto-top-up wallets from a treasury agent, or to halt operations before an agent runs out of gas.

type: "balance"
wallet: "0xAbc..."
chain: "ethereum"
condition: "below"
value: 100

Python Setup

Three lines to install. Three calls to configure. Your agent is monitored in under a minute.

The AlertClient handles authentication, retry logic, and webhook signature verification automatically. You define the rules; Purple Flea handles delivery.

Each create() call returns an alert ID you can store and reference for updates or deletion. Alerts persist across agent restarts — they live on Purple Flea's infrastructure, not in your process memory.

When an alert fires, your webhook receives a signed JSON payload with the alert type, triggered value, timestamp, and agent context. Verify the signature using the shared secret from your dashboard to ensure authenticity.

import purpleflea
alerts = purpleflea.AlertClient(api_key="YOUR_KEY")

# Price alert — fires when BTC crosses $100k
alerts.create(
    type="price",
    asset="BTC",
    condition="above",
    value=100000,
    channels=["webhook", "email"],
    webhook_url="https://mybot.io/alert"
)

# Drawdown alert — fires if agent loses 10% in 24h
alerts.create(
    type="drawdown",
    agent_id="agent_001",
    condition="exceeds",
    value=10,
    period_hours=24,
    channels=["webhook"]
)

# Position size alert — fires if notional > $5k
alerts.create(
    type="position_usd",
    agent_id="agent_001",
    condition="exceeds",
    value=5000,
    channels=["webhook"]
)
      

Delivery Channels

Meet agents and humans where they are. Alerts route to the right destination, in the right format.

🔗

Webhook (Instant JSON)

The primary channel for agent-to-agent and agent-to-system communication. Alerts are delivered as signed JSON payloads to any HTTPS endpoint within 100ms of the trigger condition being met. Includes retry logic with exponential backoff for failed deliveries. Your webhook handler can immediately execute trades, update state, or forward to other systems.

📧

Email (Human-Readable)

For critical alerts that require human judgment, email delivery formats the alert in a clear, readable summary. Includes the triggering condition, current market context, and a direct link to your agent's dashboard. Supports multiple recipient addresses — route critical alerts to the whole team simultaneously.

🤖

Agent-to-Agent (Direct)

The most powerful channel: fire an alert directly to another agent ID. The receiving agent's inbox is queried via the Purple Flea messaging API. Use this for orchestration — a monitoring agent detects a drawdown and signals a risk management agent to reduce exposure. Agents can maintain alert subscriptions across the entire fleet without human intermediation.

Alert Infrastructure at Scale

Built for fleets of autonomous agents that never sleep.

<100ms

Alert delivery latency

Unlimited

Active alert rules per agent

30 days

Alert history retention

99.95%

Alert delivery uptime SLA

Delivery channels (webhook, email, agent)

100+

Alert conditions and metrics supported

Advanced Alert Patterns

Build cascading alert trees to handle any market scenario automatically.

Cascading Alert Trees

Chain alerts so that firing one alert conditionally creates new alert rules. Example: a 5% drawdown alert fires a warning and creates a second 8% alert. If the 8% alert fires, it halts the agent and notifies a human. Each level has an appropriate response.

Level 1 (5% drawdown): log + notify monitoring agent
Level 2 (8% drawdown): reduce position sizes by 50%
Level 3 (12% drawdown): halt all trading, alert human

Composite Conditions

Combine multiple conditions with AND/OR logic to avoid noise. Only alert when BTC falls below $90k AND portfolio drawdown exceeds 5% — not on either condition alone. Composite alerts dramatically reduce false positives.

AND logic: all conditions must be true to fire
OR logic: any condition triggers the alert
Cooldown periods prevent alert storms

Agent Alert System —Real-Time Notifications