Price Alerts API

BETA FEATURE

This feature is currently in beta. API endpoints and functionality may change.

Want early access? Email us at [email protected] to join the beta program.

Overview

The Price Alerts API allows you to set up automated notifications when commodity prices reach your specified thresholds. Get notified via email, SMS, or webhook when prices move.

Features

Price Targets: Alert when price hits a specific value
Percentage Moves: Alert on percentage changes (±5%, ±10%, etc.)
Multiple Channels: Email, SMS, webhook delivery
All Commodities: Works with any commodity code
Trigger History: View past alert triggers

Endpoints

List All Alerts

GET /v1/alerts

Response:

{
  "alerts": [
    {
      "id": "alert_123",
      "commodity_code": "WTI_USD",
      "condition": "above",
      "threshold": 80.00,
      "enabled": true,
      "delivery": ["email", "webhook"],
      "created_at": "2025-01-15T10:00:00Z",
      "last_triggered": "2025-01-20T14:30:00Z"
    }
  ],
  "total": 5,
  "max_alerts": 10
}

Create Alert

POST /v1/alerts

Request Body:

{
  "commodity_code": "BRENT_CRUDE_USD",
  "condition": "below",
  "threshold": 70.00,
  "delivery": ["email", "webhook"],
  "webhook_url": "https://your-app.com/webhook",
  "message": "Brent dropped below $70!"
}

Conditions:

above - Trigger when price goes above threshold
below - Trigger when price goes below threshold
change_percent - Trigger on percentage change (use threshold: 5 for 5%)

Get Alert Details

GET /v1/alerts/:id

Update Alert

PATCH /v1/alerts/:id

Request Body:

{
  "threshold": 75.00,
  "enabled": false
}

Delete Alert

DELETE /v1/alerts/:id

View Trigger History

GET /v1/alerts/triggers

Response:

{
  "triggers": [
    {
      "alert_id": "alert_123",
      "commodity_code": "WTI_USD",
      "triggered_at": "2025-01-20T14:30:00Z",
      "price_at_trigger": 80.15,
      "threshold": 80.00,
      "delivery_status": {
        "email": "delivered",
        "webhook": "delivered"
      }
    }
  ]
}

Test Alert

POST /v1/alerts/:id/test

Sends a test notification to verify your alert delivery is working.

Alert Conditions

Condition	Description	Example
`above`	Price exceeds threshold	Alert when WTI > $80
`below`	Price drops below threshold	Alert when Brent < $70
`change_percent`	Price moves by percentage	Alert on 5% daily move

Delivery Channels

Email

Alerts sent to your account email address.

SMS

Requires phone verification. See SMS API.

Webhook

POST request to your specified URL with JSON payload:

{
  "event": "price_alert_triggered",
  "alert_id": "alert_123",
  "commodity_code": "WTI_USD",
  "commodity_name": "WTI Crude Oil",
  "current_price": 80.15,
  "threshold": 80.00,
  "condition": "above",
  "triggered_at": "2025-01-20T14:30:00Z",
  "message": "WTI hit your target price!"
}

Limits by Plan

Plan	Max Alerts	Delivery Channels
Free	1	Email only
Hobby	3	Email only
Starter	5	Email, Webhook
Professional	10	Email, SMS, Webhook
Business	25	Email, SMS, Webhook
Enterprise	Unlimited	All channels

Get Beta Access

JOIN THE BETA

Price Alerts are currently invite-only. To request access:

Email [email protected]

Include which commodities you want to track and your preferred delivery channel.