Price Alert Endpoints

POST /price-alert

Create a price alert with webhook notification.

Cost: $0.04 USDC

Request Body

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

Parameters

Field	Type	Required	Description
symbol	string	Yes	Token symbol (uppercase, max 20 chars)
condition	string	Yes	above, below, crosses_above, or crosses_below
target_price	float	Yes	Price threshold (must be positive)
webhook_url	string	Yes	Callback URL (must be HTTPS)
agent_wallet	string	No	EVM (0x...) or Solana wallet for tracking
expires_in_hours	int	No	Alert lifetime in hours, 1–168 (default: 24, max: 168 = 7 days)

Conditions

Value	Description
above	Trigger when price rises above target
below	Trigger when price falls below target
crosses_above	Trigger once when price crosses upward through target
crosses_below	Trigger once when price crosses downward through target

Request Example

const res = await fetchWithPayment("https://api.foursec.xyz/price-alert", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    symbol: "ETH",
    condition: "below",
    target_price: 2400,
    webhook_url: "https://your-bot.com/webhook",
    expires_in_hours: 24
  })
});
const alert = await res.json();

Response

{
  "alert_id": "alert_eth_1720447800_001",
  "symbol": "ETH",
  "condition": "below",
  "target_price": 2400,
  "status": "active",
  "created_at": "2026-07-08T15:30:00Z",
  "expires_at": "2026-07-09T15:30:00Z",
  "expires_in_hours": 24,
  "webhook_url": "https://your-bot.com/webhook",
  "trigger_count": 0,
  "delivery_attempts": 0,
  "message": "Alert created successfully"
}

---

GET /price-alert/:id

Check the status of an existing alert.

Cost: FREE

Request Example

curl https://api.foursec.xyz/price-alert/alert_eth_1720447800_001

Response

{
  "alert_id": "alert_eth_1720447800_001",
  "symbol": "ETH",
  "condition": "below",
  "target_price": 2400,
  "status": "active",
  "created_at": "2026-07-08T15:30:00Z",
  "expires_at": "2026-07-09T15:30:00Z",
  "trigger_count": 0
}

---

DELETE /price-alert/:id

Cancel an active alert.

Cost: FREE

Request Example

curl -X DELETE https://api.foursec.xyz/price-alert/alert_eth_1720447800_001

Response

{
  "alert_id": "alert_eth_1720447800_001",
  "status": "cancelled",
  "message": "Alert cancelled successfully"
}

---

GET /price-alerts

List all active price alerts.

Cost: FREE

Query Parameters

Param	Type	Description
wallet	string	Filter by agent_wallet address
symbol	string	Filter by token symbol

Request Example

curl "https://api.foursec.xyz/price-alerts?symbol=ETH"

---

POST /price-alert/:id/extend

Extend the duration of an active alert.

Cost: $0.02 USDC

Request Body

{
  "add_hours": 24
}

Field	Type	Description
add_hours	int	Hours to add (default: 24, max: 168)

---

Webhook Payload

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

{
  "event": "price_alert",
  "alert_id": "alert_eth_1720447800_001",
  "symbol": "ETH",
  "severity": "medium",
  "data": {
    "triggered": true,
    "current_price": 2399.50,
    "target_price": 2400,
    "condition": "below",
    "condition_met": "ETH below $2400"
  },
  "timestamp": "2026-07-09T03:15:00Z"
}

Webhook Handler Example (Node.js)

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook/price-alert', (req, res) => {
  const signature = req.headers['x-4sec-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const data = JSON.parse(req.body);
  console.log(`ALERT: ${data.symbol} — ${data.data.condition_met}`);
  console.log(`Current price: $${data.data.current_price}`);
  // Execute your trading logic here
  res.send('OK');
});

Security

Webhook payloads include an HMAC signature in the X-4SEC-Signature header (format: sha256=<hex>):

import hmac, hashlib

def verify_webhook(payload_bytes, signature_header, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Alert Lifecycle

1. active — Alert is registered and being checked every 10 seconds
2. triggered — Condition met, webhook called (1-minute cooldown before re-trigger)
3. expired — Duration elapsed without trigger
4. cancelled — Manually cancelled via DELETE endpoint

Error Responses

Error	Cause	Fix
invalid_webhook_url	URL not HTTPS	Use HTTPS webhook URL
invalid_condition	Not one of the 4 valid conditions	Use above, below, crosses_above, or crosses_below
expires_in_hours_too_long	Over 168 hours	Max 168 hours (7 days)
symbol_not_found	Unsupported symbol	Check supported symbols list
alert_not_found	Invalid or expired alert ID	Verify alert ID exists

TIP

Alerts check prices every 10 seconds with a 1-minute cooldown after each trigger. Use expires_in_hours to set duration (max 7 days). Extend anytime with POST /price-alert/:id/extend.