> ## Documentation Index
> Fetch the complete documentation index at: https://bigbrainape.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

***

## 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

<ParamField body="type" 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
</ParamField>

<ParamField body="token" type="string">
  The token to monitor. Accepts a ticker symbol (e.g. `SOL`) or a contract address. Required for `price`, `volume`, and `whale` alert types.
</ParamField>

<ParamField body="condition" type="string">
  The directional trigger for the alert. Accepted values: `above`, `below`. Required when `type` is `price`.
</ParamField>

<ParamField body="targetPrice" type="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`.
</ParamField>

<ParamField body="channel" type="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.
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="data.id" type="string">
  Unique identifier for the created alert. Use this ID to retrieve or delete the alert later.
</ResponseField>

<ResponseField name="data.type" type="string">
  The alert type as submitted.
</ResponseField>

<ResponseField name="data.token" type="string">
  The token being monitored.
</ResponseField>

<ResponseField name="data.condition" type="string">
  The directional condition (`above` or `below`) for price alerts.
</ResponseField>

<ResponseField name="data.targetPrice" type="number">
  The price threshold that triggers this alert, in USD.
</ResponseField>

<ResponseField name="data.channel" type="string">
  The notification channel that will be used when the alert fires.
</ResponseField>

<ResponseField name="data.status" type="string">
  Current status of the alert. Starts as `active`. Becomes `triggered` once fired, or `disabled` if you manually disable it.
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 UTC timestamp for when this alert was created.
</ResponseField>

***

## GET /alerts

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

**Required scope:** `alerts`

### Query Parameters

<ParamField query="status" type="string">
  Filter alerts by their current status. Accepted values: `active`, `triggered`, `disabled`. Omit to return all alerts regardless of status.
</ParamField>

<ParamField query="token" type="string">
  Filter alerts associated with a specific token symbol or contract address.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET 'https://api.bigbrainape.com/v1/alerts?status=active' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response

```json theme={null}
{
  "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

<ResponseField name="data.total" type="number">
  The total number of alerts matching your filter criteria.
</ResponseField>

<ResponseField name="data.alerts" type="array">
  List of alert objects matching the requested filters.

  <Expandable title="alert item fields">
    <ResponseField name="id" type="string">
      Unique alert identifier.
    </ResponseField>

    <ResponseField name="type" type="string">
      The alert type: `price`, `volume`, `whale`, or `portfolio`.
    </ResponseField>

    <ResponseField name="token" type="string">
      The token being monitored. Not present for `portfolio` alerts.
    </ResponseField>

    <ResponseField name="condition" type="string">
      The trigger condition (`above` or `below`). Only present for `price` alerts.
    </ResponseField>

    <ResponseField name="targetPrice" type="number">
      The price threshold in USD. Only present for `price` alerts.
    </ResponseField>

    <ResponseField name="channel" type="string">
      The notification channel configured for this alert.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current alert status: `active`, `triggered`, or `disabled`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 UTC timestamp for when the alert was created.
    </ResponseField>

    <ResponseField name="triggeredAt" type="string">
      ISO 8601 UTC timestamp for when the alert last fired. `null` if it has not triggered yet.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## DELETE /alerts/{id}

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

<ParamField path="id" type="string" required>
  The unique alert ID to delete (e.g. `alert_xyz789`).
</ParamField>

### Example Request

```bash theme={null}
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.

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

<Tip>
  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.
</Tip>