Unified Alerts

The Unified Alerts API provides a single interface for managing all alert types: gas, monitoring, performance, price, and system alerts.

Alert Types

Type	Description	Use Case
gas	Gas price threshold alerts	Notify when gas drops below target
monitoring	System health alerts	Service degradation notifications
performance	Metrics monitoring alerts	Latency or throughput thresholds
price	Token/asset price alerts	Price movement notifications
system	Critical system alerts	Infrastructure issues

---

Endpoints

Create Alert

POST /v1/alerts

Create an alert of any supported type.

Request

{
  "name": "Low Gas Alert",
  "alert_type": "gas",
  "threshold": 25.0,
  "chain_id": "1",
  "condition": "below",
  "email": "user@example.com",
  "enabled": true
}

Parameters

Field	Type	Required	Description
name	string	Yes	Alert name
alert_type	string	Yes	Type: gas, monitoring, performance, price, system
threshold	float	Yes	Threshold value
chain_id	string	No	Chain ID (for gas/price alerts)
condition	string	No	above or below (default: above)
email	string	No	Notification email
webhook_url	string	No	Webhook for notifications
enabled	boolean	No	Enable alert (default: true)

Response

{
  "id": "alert_abc123",
  "name": "Low Gas Alert",
  "alert_type": "gas",
  "threshold": 25.0,
  "chain_id": "1",
  "condition": "below",
  "email": "user@example.com",
  "enabled": true,
  "created_at": "2026-01-15T10:30:00Z",
  "last_triggered": null,
  "trigger_count": 0
}

---

Get Alerts

GET /v1/alerts

Retrieve all alerts for the current user.

Query Parameters

Parameter	Type	Description
alert_type	string	Filter by type
enabled_only	boolean	Only enabled alerts
limit	int	Max results (1-200, default: 100)
offset	int	Pagination offset

Response

[
  {
    "id": "alert_abc123",
    "name": "Low Gas Alert",
    "alert_type": "gas",
    "threshold": 25.0,
    "chain_id": "1",
    "condition": "below",
    "enabled": true,
    "last_triggered": "2026-01-15T08:15:00Z",
    "trigger_count": 5
  },
  {
    "id": "alert_def456",
    "name": "ETH Price Alert",
    "alert_type": "price",
    "threshold": 4000.0,
    "condition": "above",
    "enabled": true,
    "last_triggered": null,
    "trigger_count": 0
  }
]

---

Delete Alert

DELETE /v1/alerts/{alert_id}

Delete an alert.

Response

{
  "message": "Alert alert_abc123 deleted successfully"
}

---

Acknowledge Alert

POST /v1/alerts/{alert_id}/acknowledge

Acknowledge an active alert to stop further notifications until the condition changes.

Request

{
  "notes": "Investigating high gas prices"
}

Response

{
  "alert_id": "alert_abc123",
  "acknowledged": true,
  "acknowledged_by": "user@example.com",
  "notes": "Investigating high gas prices"
}

---

Resolve Alert

POST /v1/alerts/{alert_id}/resolve

Resolve an alert and move it to history.

Request

{
  "resolution": "Gas prices normalized after network congestion cleared"
}

Response

{
  "alert_id": "alert_abc123",
  "resolved": true,
  "resolved_by": "user@example.com",
  "resolution": "Gas prices normalized after network congestion cleared"
}

---

Get Alert Types

GET /v1/alerts/types

Returns list of supported alert types.

["gas", "monitoring", "performance", "price", "system"]

---

Get Alert Summary

GET /v1/alerts/summary

Get summary statistics for your alerts.

{
  "total_alerts": 15,
  "enabled_alerts": 12,
  "by_type": {
    "gas": {"total": 5, "enabled": 4},
    "price": {"total": 6, "enabled": 5},
    "monitoring": {"total": 3, "enabled": 2},
    "performance": {"total": 1, "enabled": 1}
  },
  "recent_activity": 8
}

---

Alert Type Examples

Gas Price Alert

Get notified when Ethereum gas drops below 25 gwei:

{
  "name": "ETH Low Gas",
  "alert_type": "gas",
  "threshold": 25.0,
  "chain_id": "1",
  "condition": "below",
  "email": "user@example.com"
}

Price Alert

Get notified when ETH exceeds $4000:

{
  "name": "ETH Price Target",
  "alert_type": "price",
  "threshold": 4000.0,
  "condition": "above",
  "webhook_url": "https://your-server.com/webhook"
}

Monitoring Alert

Get notified on system health degradation:

{
  "name": "System Health",
  "alert_type": "monitoring",
  "threshold": 0.8,
  "condition": "below",
  "email": "ops@example.com"
}

Performance Alert

Get notified when latency exceeds threshold:

{
  "name": "High Latency",
  "alert_type": "performance",
  "threshold": 500.0,
  "condition": "above",
  "email": "dev@example.com"
}

---

Code Examples

Python - Alert Manager

import requests
from dataclasses import dataclass
from enum import Enum
from typing import Optional

class AlertType(str, Enum):
    GAS = "gas"
    MONITORING = "monitoring"
    PERFORMANCE = "performance"
    PRICE = "price"
    SYSTEM = "system"

@dataclass
class Alert:
    id: str
    name: str
    alert_type: AlertType
    threshold: float
    enabled: bool
    trigger_count: int

class AlertManager:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.axol.io/api/v1/alerts"
        self.headers = {"X-API-Key": api_key}

    def create_gas_alert(
        self,
        name: str,
        chain_id: str,
        threshold: float,
        condition: str = "below",
        email: Optional[str] = None
    ) -> dict:
        """Create a gas price alert."""
        return self._create_alert({
            "name": name,
            "alert_type": "gas",
            "chain_id": chain_id,
            "threshold": threshold,
            "condition": condition,
            "email": email,
            "enabled": True
        })

    def create_price_alert(
        self,
        name: str,
        threshold: float,
        condition: str = "above",
        webhook_url: Optional[str] = None
    ) -> dict:
        """Create a price alert."""
        return self._create_alert({
            "name": name,
            "alert_type": "price",
            "threshold": threshold,
            "condition": condition,
            "webhook_url": webhook_url,
            "enabled": True
        })

    def _create_alert(self, data: dict) -> dict:
        response = requests.post(
            self.base_url,
            headers=self.headers,
            json={k: v for k, v in data.items() if v is not None}
        )
        response.raise_for_status()
        return response.json()

    def get_alerts(
        self,
        alert_type: Optional[AlertType] = None,
        enabled_only: bool = False
    ) -> list[Alert]:
        """Get all alerts with optional filtering."""
        params = {"enabled_only": enabled_only}
        if alert_type:
            params["alert_type"] = alert_type.value

        response = requests.get(
            self.base_url,
            headers=self.headers,
            params=params
        )
        response.raise_for_status()

        return [
            Alert(
                id=a["id"],
                name=a["name"],
                alert_type=AlertType(a["alert_type"]),
                threshold=a["threshold"],
                enabled=a["enabled"],
                trigger_count=a["trigger_count"]
            )
            for a in response.json()
        ]

    def delete_alert(self, alert_id: str) -> bool:
        """Delete an alert."""
        response = requests.delete(
            f"{self.base_url}/{alert_id}",
            headers=self.headers
        )
        return response.status_code == 200

    def acknowledge_alert(self, alert_id: str, notes: str = None) -> dict:
        """Acknowledge an alert."""
        response = requests.post(
            f"{self.base_url}/{alert_id}/acknowledge",
            headers=self.headers,
            json={"notes": notes} if notes else {}
        )
        response.raise_for_status()
        return response.json()

    def get_summary(self) -> dict:
        """Get alert summary statistics."""
        response = requests.get(
            f"{self.base_url}/summary",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
manager = AlertManager(api_key="YOUR_KEY")

# Create gas alert for low Ethereum gas
gas_alert = manager.create_gas_alert(
    name="ETH Low Gas",
    chain_id="1",
    threshold=25.0,
    condition="below",
    email="user@example.com"
)
print(f"Created alert: {gas_alert['id']}")

# Create price alert
price_alert = manager.create_price_alert(
    name="ETH $4K Target",
    threshold=4000.0,
    condition="above"
)

# Get all gas alerts
gas_alerts = manager.get_alerts(alert_type=AlertType.GAS)
print(f"Active gas alerts: {len(gas_alerts)}")

# Get summary
summary = manager.get_summary()
print(f"Total alerts: {summary['total_alerts']}")
print(f"Enabled: {summary['enabled_alerts']}")

TypeScript - Alert System

interface AlertConfig {
  name: string;
  alert_type: 'gas' | 'monitoring' | 'performance' | 'price' | 'system';
  threshold: number;
  chain_id?: string;
  condition?: 'above' | 'below';
  email?: string;
  webhook_url?: string;
  enabled?: boolean;
}

interface Alert extends AlertConfig {
  id: string;
  created_at: string;
  last_triggered: string | null;
  trigger_count: number;
}

interface AlertSummary {
  total_alerts: number;
  enabled_alerts: number;
  by_type: Record<string, { total: number; enabled: number }>;
  recent_activity: number;
}

class AlertClient {
  private apiKey: string;
  private baseUrl = 'https://api.axol.io/api/v1/alerts';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request<T>(
    method: string,
    path = '',
    body?: object
  ): Promise<T> {
    const response = await fetch(`${this.baseUrl}${path}`, {
      method,
      headers: {
        'X-API-Key': this.apiKey,
        'Content-Type': 'application/json'
      },
      body: body ? JSON.stringify(body) : undefined
    });

    if (!response.ok) {
      throw new Error(`Alert API error: ${response.statusText}`);
    }

    return response.json();
  }

  async createAlert(config: AlertConfig): Promise<Alert> {
    return this.request<Alert>('POST', '', config);
  }

  async getAlerts(options?: {
    alertType?: string;
    enabledOnly?: boolean;
    limit?: number;
  }): Promise<Alert[]> {
    const params = new URLSearchParams();
    if (options?.alertType) params.set('alert_type', options.alertType);
    if (options?.enabledOnly) params.set('enabled_only', 'true');
    if (options?.limit) params.set('limit', options.limit.toString());

    const query = params.toString();
    return this.request<Alert[]>('GET', query ? `?${query}` : '');
  }

  async deleteAlert(alertId: string): Promise<void> {
    await this.request('DELETE', `/${alertId}`);
  }

  async acknowledgeAlert(
    alertId: string,
    notes?: string
  ): Promise<{ acknowledged: boolean }> {
    return this.request('POST', `/${alertId}/acknowledge`, { notes });
  }

  async resolveAlert(
    alertId: string,
    resolution?: string
  ): Promise<{ resolved: boolean }> {
    return this.request('POST', `/${alertId}/resolve`, { resolution });
  }

  async getSummary(): Promise<AlertSummary> {
    return this.request<AlertSummary>('GET', '/summary');
  }

  async getTypes(): Promise<string[]> {
    return this.request<string[]>('GET', '/types');
  }
}

// Usage
const client = new AlertClient(process.env.AXOL_API_KEY!);

// Create alerts for MEV trading
async function setupTradingAlerts() {
  // Gas alert - notify when gas is low enough for profitable trades
  const gasAlert = await client.createAlert({
    name: 'Low Gas for Trading',
    alert_type: 'gas',
    threshold: 20,
    chain_id: '1',
    condition: 'below',
    webhook_url: 'https://your-bot.com/webhook/gas'
  });
  console.log(`Gas alert created: ${gasAlert.id}`);

  // Price alert - ETH price movement
  const priceAlert = await client.createAlert({
    name: 'ETH Volatility',
    alert_type: 'price',
    threshold: 3500,
    condition: 'below',
    email: 'trader@example.com'
  });
  console.log(`Price alert created: ${priceAlert.id}`);

  // Performance alert - API latency
  const perfAlert = await client.createAlert({
    name: 'API Latency High',
    alert_type: 'performance',
    threshold: 300,
    condition: 'above',
    webhook_url: 'https://your-bot.com/webhook/performance'
  });
  console.log(`Performance alert created: ${perfAlert.id}`);
}

// Monitor alerts
async function monitorAlerts() {
  const summary = await client.getSummary();
  console.log(`Total alerts: ${summary.total_alerts}`);
  console.log(`Recently triggered: ${summary.recent_activity}`);

  // Check for triggered gas alerts
  const gasAlerts = await client.getAlerts({ alertType: 'gas' });
  const triggered = gasAlerts.filter(a => a.last_triggered !== null);

  if (triggered.length > 0) {
    console.log(`${triggered.length} gas alerts have triggered`);
  }
}

setupTradingAlerts();

---

Webhook Notifications

When an alert triggers, webhooks receive a POST request:

{
  "event": "alert_triggered",
  "alert": {
    "id": "alert_abc123",
    "name": "Low Gas Alert",
    "alert_type": "gas",
    "threshold": 25.0,
    "condition": "below"
  },
  "current_value": 22.5,
  "triggered_at": "2026-01-15T10:30:00Z",
  "chain_id": "1"
}

---

Best Practices

1. Use Appropriate Thresholds

Alert Type	Recommended Approach
Gas	Set based on your average transaction cost tolerance
Price	Use percentage change rather than absolute values for volatile assets
Performance	Set above P95 latency to avoid noise
Monitoring	0.8-0.9 health score threshold

2. Combine Alerts with Actions

# Example: Auto-execute when gas is low
def handle_gas_webhook(payload: dict):
    if payload["current_value"] < 20:
        execute_pending_transactions()

3. Clean Up Old Alerts

# Remove alerts that haven't triggered in 30 days
alerts = manager.get_alerts()
for alert in alerts:
    if alert.trigger_count == 0:
        manager.delete_alert(alert.id)

---

See Also

• Unified Metrics - System metrics
• Gas Oracle - Real-time gas data
• DeFi Liquidations - Liquidation alerts