Alerts API — Create, List, and Delete Price Alerts

POST /alerts creates a new price or volume alert and GET /alerts lists your active alerts. Use the Big Brain Ape Alerts API to automate your monitoring.

The Alerts API lets you configure automated notifications for market events that matter to you. Create price threshold alerts, volume spike monitors, whale movement trackers, and portfolio-level triggers — then receive real-time notifications via email, push, or Telegram so you never miss a move.

Free plan accounts are limited to 5 active alerts at a time. Upgrade to Pro for unlimited active alerts across all alert types and notification channels.

---

POST /alerts

Create a new alert. Once created, the alert becomes active immediately and starts monitoring for your configured condition.

Required scope: alerts

Request Body

type · string · required

The category of alert to create. Accepted values:

• price — trigger when a token crosses a price threshold
• volume — trigger on unusual volume spikes
• whale — trigger on large wallet movements for a token
• portfolio — trigger based on your overall portfolio value or PnL

token · string

The token to monitor. Accepts a ticker symbol (e.g. SOL) or a contract address. Required for price, volume, and whale alert types.

condition · string

The directional trigger for the alert. Accepted values: above, below. Required when type is price.

targetPrice · number

The USD price at which the alert fires. Required when type is price. The alert triggers when the token price crosses this value in the direction specified by condition.

channel · string · required

The notification channel to use when the alert fires. Accepted values: email, push, telegram. Your account must have the corresponding channel configured in notification settings before using it.

Example Request

curl -X POST https://api.bigbrainape.com/v1/alerts \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "price",
    "token": "SOL",
    "condition": "above",
    "targetPrice": 200,
    "channel": "email"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "alert_xyz789",
    "type": "price",
    "token": "SOL",
    "condition": "above",
    "targetPrice": 200,
    "channel": "email",
    "status": "active",
    "createdAt": "2024-01-15T14:32:00Z"
  },
  "timestamp": "2024-01-15T14:32:00Z"
}

Response Fields

data.id · string

Unique identifier for the created alert. Use this ID to retrieve or delete the alert later.

data.type · string

The alert type as submitted.

data.token · string

The token being monitored.

data.condition · string

The directional condition (above or below) for price alerts.

data.targetPrice · number

The price threshold that triggers this alert, in USD.

data.channel · string

The notification channel that will be used when the alert fires.

data.status · string

Current status of the alert. Starts as active. Becomes triggered once fired, or disabled if you manually disable it.

data.createdAt · string

ISO 8601 UTC timestamp for when this alert was created.

---

GET /alerts

Retrieve all alerts on your account. Filter by status or token to narrow the results.

Required scope: alerts

Query Parameters

status · string

Filter alerts by their current status. Accepted values: active, triggered, disabled. Omit to return all alerts regardless of status.

token · string

Filter alerts associated with a specific token symbol or contract address.

Example Request

curl -X GET 'https://api.bigbrainape.com/v1/alerts?status=active' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "success": true,
  "data": {
    "total": 3,
    "alerts": [
      {
        "id": "alert_xyz789",
        "type": "price",
        "token": "SOL",
        "condition": "above",
        "targetPrice": 200,
        "channel": "email",
        "status": "active",
        "createdAt": "2024-01-15T14:32:00Z",
        "triggeredAt": null
      },
      {
        "id": "alert_def456",
        "type": "whale",
        "token": "ETH",
        "channel": "telegram",
        "status": "active",
        "createdAt": "2024-01-14T09:15:00Z",
        "triggeredAt": null
      },
      {
        "id": "alert_ghi012",
        "type": "price",
        "token": "ETH",
        "condition": "below",
        "targetPrice": 2800,
        "channel": "push",
        "status": "active",
        "createdAt": "2024-01-13T18:00:00Z",
        "triggeredAt": null
      }
    ]
  },
  "timestamp": "2024-01-15T14:32:00Z"
}

Response Fields

data.total · number

The total number of alerts matching your filter criteria.

data.alerts · array

List of alert objects matching the requested filters.

Show alert item fields

id · string

Unique alert identifier.

type · string

The alert type: price, volume, whale, or portfolio.

token · string

The token being monitored. Not present for portfolio alerts.

condition · string

The trigger condition (above or below). Only present for price alerts.

targetPrice · number

The price threshold in USD. Only present for price alerts.

channel · string

The notification channel configured for this alert.

status · string

Current alert status: active, triggered, or disabled.

createdAt · string

ISO 8601 UTC timestamp for when the alert was created.

triggeredAt · string

ISO 8601 UTC timestamp for when the alert last fired. null if it has not triggered yet.

---

DELETE /alerts/

Permanently delete an alert. Once deleted, the alert stops monitoring immediately and cannot be recovered. If you want to pause monitoring without losing your configuration, disable the alert instead via your Big Brain Ape dashboard.

Required scope: alerts

Path Parameters

id · string · required

The unique alert ID to delete (e.g. alert_xyz789).

Example Request

curl -X DELETE 'https://api.bigbrainape.com/v1/alerts/alert_xyz789' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response

A successful deletion returns HTTP 204 No Content with an empty body. No JSON envelope is returned for this endpoint.

If the alert ID does not exist or belongs to a different account, the API returns a 404 Not Found response.

{
  "success": false,
  "error": {
    "code": "ALERT_NOT_FOUND",
    "message": "No alert found with the provided ID."
  },
  "timestamp": "2024-01-15T14:32:00Z"
}

To avoid hitting the 5-alert limit on the Free plan, delete alerts that have already triggered and are no longer needed. Triggered alerts count toward your active limit until explicitly deleted or disabled.