POST /price-alert

Create a price alert with webhook notification.

Cost: $0.05 USDC

Request Body

{
  "symbol": "ETH",
  "condition": "below",
  "target_price": 2400,
  "webhook_url": "https://your-bot.com/webhook",
  "duration_hours": 24
}

Parameters

Field	Type	Required	Description
symbol	string	Yes	Token symbol
condition	string	Yes	"above" or "below"
target_price	float	Yes	Price threshold
webhook_url	string	Yes	Callback URL (HTTPS required)
duration_hours	int	No (default: 24)	Alert lifetime, max 168 (7 days)

Request Example

alert = client.post("https://api.foursec.xyz/price-alert", json={
   "symbol": "ETH",
    "condition": "below",
    "target_price": 2400,
    "webhook_url": "https://your-bot.com/webhook",
    "duration_hours": 24
}).json()

Response

{
  "alert_id": "alt_abc123",
  "symbol": "ETH",
  "condition": "below",
  "target_price": 2400,
  "status": "active",
  "created_at": "2026-07-04T15:30:00Z",
  "expires_at": "2026-07-05T15:30:00Z",
  "webhook_url": "https://your-bot.com/webhook"
}

Webhook Payload

When the condition is met, a POST request is sent to your webhook_url:

{
  "alert_id": "alt_abc123",
  "event": "price_alert_triggered",
  "symbol": "ETH",
  "condition": "below",
  "target_price": 2400,
  "current_price": 2399.50,
  "condition_met": true,
  "timestamp": "2026-07-05T03:15:00Z",
  "sources": [
    {"dex": "Uniswap V3", "price": 2399.50},
    {"dex": "BaseSwap", "price": 2399.55},
    {"dex": "SushiSwap", "price": 2399.45}
  ]
}

Webhook Handler Example (Flask)

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook/price-alert', methods=['POST'])
def handle_alert():
    data = request.json
    print(f"ALERT: {data['symbol']} is now ${data['current_price']}")
    print(f"Condition: {data['condition']} {data['target_price']}")
    # Execute your trading logic here
    return 'OK', 200

Alert Lifecycle

1. created — Alert is registered and monitoring
2. active — Price is being checked every 30 seconds
3. triggered — Condition met, webhook called
4. expired — Duration elapsed without trigger
5. cancelled — Manually cancelled by user

Error Responses

Error	Cause	Fix
invalid_webhook_url	URL not HTTPS or unreachable	Use HTTPS webhook
invalid_condition	Not "above" or "below"	Use correct value
duration_too_long	Over 168 hours	Reduce duration
symbol_not_found	Unsupported symbol	Check supported list

Managing Alerts

TIP

Alerts are one-time use. Once triggered, the alert is consumed. Create new alerts for continued monitoring.

Security

Webhook payloads include an HMAC signature in the X-4SEC-Signature header:

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)