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

# Using Events

> Learn how to use events to build powerful applications with real-time price alerts and trending token detection. Integrate webhooks, handle events, and deliver timely notifications to your users.

## Quick Start

### 1. Configure Webhook Endpoint

Set up an endpoint to receive event webhooks:

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/events', (req, res) => {
  const event = req.body;
  
  console.log('Received event:', event.event);
  console.log('Token:', event.token.symbol);
  
  // Process the event
  handleEvent(event);
  
  // Always respond with 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});
```

### 2. Registration

#### 2.1 Register Your Webhook (required)

Contact us at [hello@dialect.to](mailto:hello@dialect.to) to register your webhook endpoint.

### 2.2 Register Users Wallets (only for last trade price change events)

If you want to offer last trade price change events to your users, you need to register their wallets. This can be done by submitting a list of wallet addresses to us. Please contact us at [hello@dialect.to](mailto:hello@dialect.to) before sending any materials.

### 3. Handle Events

Implement event handlers based on the event type:

```javascript theme={null}
function handleEvent(event) {
  switch (event.event) {
    case 'token_price_change':
      handlePriceChangeEvent(event);
      break;
    case 'token_last_trade_price_change':
      handleLastTradePriceChangeEvent(event);
      break;
    default:
      console.log('Unknown event type:', event.event);
  }
}
```

## Price Change Events

There are two types of price change events. Please remember to [send a list](/alerts/events/using-events#2-2-register-users-wallets-only-for-last-trade-price-change-events) with users wallets to us if you want to offer last trade price change events to your users.

### Market-Based Price Change Events

Price change events are triggered by significant price movements over sliding time windows using percentage change thresholds.

```javascript theme={null}
async function handlePriceChangeEvent(event) {
  const { token, change, trigger } = event;
  
  // Example: Notify users who hold this token
  const message = `${token.symbol} moved ${change.percentage.toFixed(1)}% over the last ${trigger.window.duration}`;
  
  // Send notifications based on your application logic
  await notifyUsers(token.address, message);
}
```

#### Available Windows

* 1h, 3h, 6h, 12h, 24h, 7d

#### Spam Prevention

Dialect's event detection includes built-in capabilities to ensure users don't receive too many alerts:

* **Debouncing & rolling averages** - Prevents rapid-fire alerts
* **Rate limits** - Controls notification frequency
* **Priority conflicts** - Manages competing events
* **Alert escalation** - Prioritizes important events

### Last Trade Price Change Events

Last trade price change events provide personalized alerts based on users' actual trading history. To use this feature, you need to [register](/alerts/events/using-events#2-2-register-users-wallets-only-for-last-trade-price-change-events) the wallets of your users.

```javascript theme={null}
async function handleLastTradePriceChangeEvent(event) {
  const { walletAddress, token, trigger, changes } = event;

  // Build contextual message based on trade history
  let message;
  const percentChange = Math.abs(changes.triggerTrade.change.percentage);
  const direction = changes.triggerTrade.change.direction;

  if (trigger.trade.type === 'buy') {
    // Alert relative to buy price
    message = `${token.symbol} is ${direction} ${percentChange.toFixed(1)}% since you bought`;
  } else if (trigger.trade.type === 'sell') {
    // Handle logic for sell events, 
    // e.g. send alert after full exit, 
    // partial sells, etc.
  }

  // Send personalized notification to specific wallet
  await sendWalletNotification(walletAddress, message);
}
```

### Key Features

* **Personalized Thresholds**: Based on market cap and position status
* **Round Trip Detection**: Alerts when returning to previous levels
* **Post-Exit Monitoring**: Continues tracking after full sells

## Trending Token Events (Coming Soon)

We're developing advanced event detection for newly launched tokens that meet specific safety and quality criteria. This system will focus on tokens with "staying power" rather than short-lived movements.

Learn more about our approach: See the [Trending Tokens Events](/alerts/events/trending-token) section for detailed information about detection criteria, safety filters, and the quality-first methodology.

<Tip>
  **Early Access Available**

  Trending token events are in development. The system is being tested internally with smart defaults before expanding to user customization.

  Contact us at [hello@dialect.to](mailto:hello@dialect.to) for early access or to discuss specific requirements.
</Tip>