---
updatedAt: 2026-07-10T10:27:39.000Z
agentTools:
  projectIndex: https://docs.getembed.ai/llms.txt
---

# Notifications

Build notification products in Console with algorithms, notification configs, webhooks, cooldowns, and budgets.

# Notifications

Notifications in the current Console are algorithm-driven. A notification product starts with a saved algorithm that returns user-specific notification candidates, then a notification config controls delivery.

The legacy alpha notification API is not the current Console user workflow.

## Current Console Workflow

1. Open **Algo**.
2. Build a notification candidate algorithm with Search, Hydration, and DSL.
3. Save and validate the algorithm.
4. Open **Notifications**.
5. Create a notification config that references one or more saved algorithm IDs.
6. Set delivery controls such as webhook URL, cooldown, priority filter, and daily budget.
7. Test webhook delivery.
8. Monitor delivered notifications in your application.

## What The Algorithm Does

The algorithm chooses candidates. It should return records with enough information to decide who gets notified and what the notification is about.

Typical candidate requirements:

* `user_id` or another deliverable user identifier.
* `item_id`, market ID, wallet ID, or signal ID for idempotency.
* A `timestamp` or event time.
* Optional priority, label, or score fields used by the config.
* Hydrated metadata needed by the webhook payload.

## What The Notification Config Does

The config controls delivery.

| Setting         | Purpose                                                     |
| --------------- | ----------------------------------------------------------- |
| Algorithms      | Saved algo IDs used as notification candidate sources       |
| Webhook URL     | Your endpoint that receives notification payloads           |
| Cooldown        | Prevents repeated notifications for the same user or item   |
| Priority filter | Limits delivery to selected priorities such as `P0` or `P1` |
| Daily budget    | Caps total deliveries for a period                          |

## Ingestion And Delivery

Notification inputs come from searchable event indices such as:

* `dex-notifications`
* `hyperliquid-notifications`
* `kalshi-notifications`
* `polymarket-notifications`

The saved algorithm searches those events and hydrates the metadata needed for delivery. The notification config then sends matching results to your webhook subject to cooldowns, priority filters, and budgets.

Your webhook should be idempotent. Use a stable key such as `user_id + item_id`, `user_id + signal_id`, or the event ID so retries do not create duplicate user-visible notifications.

## Example: Polymarket Notification Candidates

```js
import mbd from "algo-dsl";

export default async function algo() {
  return mbd
    .search()
    .index("polymarket-notifications")
    .notNull("user_id")
    .notNull("item_id")
    .notNull("timestamp")
    .sortBy("timestamp", "desc")
    .size(100);
}
```

Use this pattern when each notification candidate should map to a user and a market/item.

## Example: Hyperliquid Notification Candidates

```js
import mbd from "algo-dsl";

export default async function algo() {
  return mbd
    .search()
    .index("hyperliquid-notifications")
    .notNull("user_id")
    .notNull("timestamp")
    .sortBy("timestamp", "desc")
    .size(100);
}
```

Hydrate any wallet, market, or asset metadata your webhook needs before delivery.

## Example Notification Config Shape

```js
import mbd from "algo-dsl";

export default async function notificationConfig() {
  return mbd
    .notification("wallet-alerts")
    .algos([172, 173])
    .webhook("https://your-app.com/webhooks/embed-notifications")
    .cooldown({ hours: 4, by: "user_id" })
    .priorityFilter("P0,P1")
    .dailyBudget(5000)
    .save();
}
```

Replace the algorithm IDs with saved notification-candidate algorithms from your Console account.

## Notification DSL Patterns

Use these patterns to build notification candidate algorithms. The notification config controls delivery; the algorithm should focus on returning clean candidates.

| Pattern                       | When to use it                                        | Main DSL ideas                                               |
| ----------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| Priority notifications        | Deliver only high-priority candidates                 | Notification index, priority filter, timestamp sort          |
| Position-change notifications | Alert when a wallet or market position changes enough | Wallet-position index, numeric threshold, cooldown in config |
| Market/event notifications    | Alert from notification event streams                 | Notification index, `user_id`, stable item or signal ID      |

### Pattern: P0/P1 Polymarket Notifications

```js
import mbd from "algo-dsl";

export default async function algo() {
  const candidates = await mbd.search()
    .index("polymarket-notifications")
    .size(50)
    .include()
      .terms("priority.keyword", ["P0", "P1"])
    .sortBy("timestamp", "desc")
    .execute();

  mbd.addCandidates(candidates);
  mbd.show();
}
```

How to build it in Console:

1. Choose `polymarket-notifications` in Search.
2. Add a priority filter for `P0` and `P1`.
3. Sort by `timestamp desc`.
4. Hydrate fields your webhook needs.
5. Save the algo and reference it from a notification config.

### Pattern: Position-Change Notifications

```js
import mbd from "algo-dsl";

export default async function algo() {
  const candidates = await mbd.search()
    .index("polymarket-wallet-positions")
    .size(50)
    .include()
      .numeric("<position_change_field>", ">=", 20)
    .sortBy("timestamp", "desc")
    .execute();

  mbd.addCandidates(candidates);
  mbd.show();
}
```

Use the exact threshold and field name shown in Console for the selected index. If the candidate pool is too small, lower the threshold or use a broader notification fallback algo.

## Testing Checklist

Before enabling delivery:

* The algorithm returns candidates in preview.
* Each candidate has a stable user identifier.
* Each candidate has a stable item, signal, or event identifier.
* Hydration includes the fields your webhook needs.
* Cooldown scope matches the product behavior.
* Priority filter is not too strict.
* Daily budget is high enough for testing but safe for production.
* The webhook handles retries idempotently.

## Next

* Build candidate algorithms in [Building Algorithms](../Algorithm/guide-building-algorithms).
* Review notification DSL in [Notification DSL Functions](./notifications-dsl-functions).
* Use supported notification indices from [Supported Indices](../Algorithm/supported-indices).