Liquidation Alert

POST /liquidation/alert

Create a webhook alert triggered when liquidation cascade risk exceeds your threshold.

Cost: $0.06 USDC

Request Body

{
  "symbol": "BTC",
  "threshold_pct": 5.0,
  "min_value_usd": 100000000,
  "webhook_url": "https://your-bot.com/webhook",
  "expires_in_hours": 24
}

Parameters

Field	Type	Required	Description
symbol	string	Yes	Token symbol (e.g. BTC, ETH)
condition	string	No	Alert condition (default: cascade_risk)
threshold_pct	float	No	OI at risk % to trigger alert (default: 5.0)
min_value_usd	float	No	Minimum USD OI at risk to trigger (default: 0)
webhook_url	string	Yes	Callback URL (must be HTTPS)
expires_in_hours	int	No	Alert lifetime in hours, 1–168 (default: 24)

Response

{
  "alert_id": "alert_liq_btc_1720447800_001",
  "symbol": "BTC",
  "status": "active",
  "threshold_pct": 5.0,
  "min_value_usd": 100000000,
  "webhook_url": "https://your-bot.com/webhook",
  "expires_at": "2026-07-09T14:30:00Z",
  "message": "Liquidation alert created successfully"
}

---

GET /liquidation/alert/:id

Check the status of an existing liquidation alert.

Cost: FREE

curl https://api.foursec.xyz/liquidation/alert/alert_liq_btc_1720447800_001

---

DELETE /liquidation/alert/:id

Cancel an active liquidation alert.

Cost: FREE

curl -X DELETE \
  https://api.foursec.xyz/liquidation/alert/alert_liq_btc_1720447800_001

---

GET /liquidation/alerts

List all active liquidation alerts.

Cost: FREE

Query Parameters

Param	Type	Description
wallet	string	Filter by wallet address

---

POST /liquidation/alert/:id/extend

Extend the duration of an active liquidation alert.

Cost: $0.03 USDC

Request Body

{
  "add_hours": 24
}

---

Webhook Payload

When cascade risk threshold is exceeded:

{
  "event": "liquidation_alert",
  "alert_id": "alert_liq_btc_1720447800_001",
  "symbol": "BTC",
  "severity": "high",
  "data": {
    "triggered": true,
    "current_price": 57200,
    "oi_at_risk_usd": 450000000,
    "oi_at_risk_pct": 8.2,
    "cascade_risk": "high",
    "threshold_pct": 5.0
  },
  "timestamp": "2026-07-08T14:30:00Z"
}

Signature: X-4SEC-Signature: sha256=<hmac-hex> (same as price alerts).

Related Endpoints

• Heatmap — get current risk levels
• Recent Events — live liquidation stream