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

# Price Change Events

> Track token price movements with market-wide sliding windows or personalized alerts based on individual trading history. Get instant notifications when tokens hit thresholds, with smart filtering that cuts through market noise.

<Note>
  **Beta Access Required**

  Price Change Events are currently in beta. To request early access, please contact our team at [hello@dialect.to](mailto:hello@dialect.to).
</Note>

## Overview

Dialect offers two types of price change detection:

1. **Market-Based Price Changes**: Track price movements over sliding time windows (e.g., "SOL is up 10% in 24h")
2. **Trade-Based Price Changes**: Personalized alerts relative to users' actual trade prices (e.g., "SOL is up 50% since you bought")

Both systems use complex threshold detection and advanced filtering to deliver only the most relevant alerts.

## Market-Based Price Changes

Market-Based Price Changes are triggered by significant price movements of a token over sliding time windows using percentage change thresholds.

### How It Works

Dialect continuously monitors token prices and analyzes percentage changes over sliding time windows. When a token's price change exceeds the configured threshold within a time window, a webhook is triggered with detailed information about the price movement.

### Sliding Window Analysis

Price changes are calculated using a sliding window approach:

* **Window Duration**: Configurable time periods (1h, 3h, 6h, 12h, 24h, 7d)
* **Threshold**: Percentage change required to trigger an event
* **Direction**: Both upward and downward movements are detected

### Supported Time Windows

| Window | Beta Status   | Use Case                                    |
| ------ | ------------- | ------------------------------------------- |
| 1h     | Future        | Momentum detection, immediate market shifts |
| 3h     | **Available** | Short-term trend confirmation               |
| 6h     | **Available** | Intraday trend identification               |
| 12h    | **Available** | Half-day trend analysis                     |
| 24h    | **Available** | Daily price movement tracking               |
| 7d     | Planned       | Weekly trend detection                      |

### Market-Based Webhook Payload

```json theme={null}
{
  "events": [
    {
      "event": "token_price_change",
      "timestamp": "2025-07-04T14:30:00Z",
      "token": {
        "symbol": "SOL",
        "address": "So11111111111111111111111111111111111111112"
      },
      "trigger": {
        "type": "sliding_window_percentage_change",
        "window": {
          "duration": "24h"
        },
        "threshold": 10.0
      },
      "change": {
        "direction": "up",
        "from": {
          "timestamp": "2025-07-03T14:30:00Z",
          "value": 154.25
        },
        "to": {
          "timestamp": "2025-07-04T14:30:00Z",
          "value": 171.85
        },
        "absolute": 17.6,
        "percentage": 11.42
      }
    }
  ]
}
```

#### Market-Based Field Details

##### Event Metadata

* **event**: `token_price_change`
* **timestamp**: ISO 8601 UTC timestamp when event was generated

##### Token Information

* **symbol**: Token ticker symbol
* **address**: Token mint address on Solana

##### Trigger Details

* **type**: `sliding_window_percentage_change`
* **window**: Sliding window configuration
  * **duration**: Time window used for the calculation (e.g., `1h`, `3h`, `6h`, `12h`, `24h`, `7d`)
* **threshold**: The percentage change that must be crossed within the window to trigger the event

##### Change Information

* **direction**: `up` for price increases, `down` for decreases
* **from**: Price and timestamp at the start of the window
* **to**: Price and timestamp at the end of the window
* **absolute**: Raw price difference (`to.value - from.value`)
* **percentage**: Percentage change over the window (`(to.value - from.value) / from.value * 100`)

## Trade-Based Price Changes (Last Trade)

Trade-Based Price Changes are triggered by significant price movements of a token relative to a user's actual trading history. They offer a more personalized approach to [price change alerts](/alerts/events/price-change#market-based-price-changes), providing alerts based on a user's buy/sell behavior rather than market-wide price movements.

### How It Works

<Note>
  Please note that during the beta, we only support `buy` transactions that happened **after** the wallet was registered.
</Note>

1. **Registration**: Wallets must be explicitly registered to receive last trade events
2. **Trade Detection**: System monitors all swap transactions for the wallet
3. **Anchor Points**: Last buy price becomes the baseline for percentage calculations
4. **Threshold Monitoring**: Price changes are evaluated against market cap-specific thresholds
5. **Event Triggering**: Alerts fire when thresholds are crossed in either direction

### Registration Process

Wallets must be explicitly registered to receive last trade events. During beta:

* Contact us at [hello@dialect.to](mailto:hello@dialect.to) to register your wallets
* Projects provide wallet lists to Dialect for monitoring
* No backfill of historical trades (monitoring starts from registration)

### Trade-Based Threshold System

Thresholds are determined based on token market capitalization at the time of initial tracking:

#### Standard Position Thresholds

| Market Cap Range         | Uptrend Triggers             | Downtrend Triggers                     |
| ------------------------ | ---------------------------- | -------------------------------------- |
| **Large Cap** (>\$1B)    | +5%, +10%, then every +10%   | -5%, -10%, then every -10%             |
| **Mid Cap** ($50M-$500M) | +20%, +50%, then 2x, 3x, 4x… | -20%, -30%, then every -10% until -90% |
| **Small Cap** (\<\$50M)  | +50%, then 2x, 3x, 4x…       | -20%, -30%, then every -10% until -90% |
| **Micro Cap** (\<\$1M)   | +50%, 2x, then every 1x      | -30%, -50%, -70%, -90%                 |

#### Post-Exit Thresholds

After a full sell (100% position exit), different thresholds apply:

| Market Cap Range         | Uptrend Trigger | Downtrend Trigger |
| ------------------------ | --------------- | ----------------- |
| **Large Cap** (>\$1B)    | +30%            | -30%              |
| **Mid Cap** ($50M-$500M) | 2x              | -50%              |
| **Small Cap** (\<\$50M)  | 3x              | -50%              |
| **Micro Cap** (\<\$1M)   | 5x              | -70%              |

### Event Triggering Rules

#### Threshold Crossing

* Events trigger when price **fully crosses** a threshold
* Same threshold cannot trigger twice consecutively
* Price must cross another threshold before original can trigger again

#### Round Trip Detection

* System tracks when price returns to previous thresholds
* Generates contextual alerts like "TOKEN back to +50% from 2x"
* Helps users understand retracement patterns

#### Multiple Threshold Handling

* If multiple thresholds crossed in 5-minute window, only most significant triggers
* Prioritizes largest movement (highest for uptrend, lowest for downtrend)

### Trade-Based Webhook Payload

```json theme={null}
{
  "events": [
    {
      "event": "token_last_trade_price_change",
      "timestamp": "2025-09-17T16:03:10.259Z",
      "token": {
        "symbol": "TOKEN",
        "address": "TokenMintAddress..."
      },
      "walletAddress": "UserWalletAddress...",
      "trigger": {
        "type": "trade_percentage_change",
        "trade": {
          "type": "buy",
          "timestamp": "2024-01-15T10:00:00.000Z",
          "transactionId": "TxSignature...",
          "balance": {
            "before": 0,
            "after": 1000,
            "change": 1000
          }
        },
        "threshold": 50
      },
      "changes": {
        "triggerTrade": {
          "type": "trade_change",
          "trade": {
            "type": "buy",
            "timestamp": "2024-01-15T10:00:00.000Z",
            "transactionId": "TxSignature...",
            "balance": {
              "before": 0,
              "after": 1000,
              "change": 1000
            }
          },
          "change": {
            "direction": "up",
            "from": {
              "timestamp": "2024-01-15T10:00:00.000Z",
              "value": 1.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": 0.50,
            "percentage": 50.0
          }
        },
        "lastTrade": {
          "type": "trade_change",
          "trade": {
            "type": "buy",
            "timestamp": "2024-01-15T10:00:00.000Z",
            "transactionId": "TxSignature...",
            "balance": {
              "before": 0,
              "after": 1000,
              "change": 1000
            }
          },
          "change": {
            "direction": "up",
            "from": {
              "timestamp": "2024-01-15T10:00:00.000Z",
              "value": 1.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": 0.50,
            "percentage": 50.0
          }
        },
        "lastPeak": {
          "type": "peak_change",
          "change": {
            "direction": "down",
            "from": {
              "timestamp": "2025-09-17T12:00:00.000Z",
              "value": 2.00
            },
            "to": {
              "timestamp": "2025-09-17T16:03:10.259Z",
              "value": 1.50
            },
            "absolute": -0.50,
            "percentage": -25.0
          }
        }
      }
    }
  ]
}
```

#### Trade-Based Field Descriptions

##### Event Metadata

* **event**: `token_last_trade_price_change`
* **timestamp**: ISO 8601 UTC timestamp when event was generated
* **walletAddress**: The wallet being monitored for this event

##### Token Information

* **symbol**: Token ticker symbol
* **address**: Token mint address on Solana

##### Trigger Details

* **type**: `trade_percentage_change`
* **trade**: The anchor trade (last buy or sell) used for calculations
  * **type**: `buy` or `sell`
  * **timestamp**: When the trade occurred
  * **transactionId**: Blockchain transaction signature
  * **balance**: Token balance changes
    * **before**: Balance before trade
    * **after**: Balance after trade
    * **change**: Net change (positive for buys, negative for sells)
* **threshold**: The percentage threshold that was crossed

##### Change Information

* **triggerTrade**: Price change from the anchor trade
* **lastTrade**: Price change from most recent trade
* **lastPeak**: Price change from previous alert threshold (optional)
  * Each contains:
    * **direction**: `up` or `down`
    * **from/to**: Start and end prices with timestamps
    * **absolute**: USD price difference
    * **percentage**: Percentage change

### Edge Cases

#### Partial Sells

* Last buy price remains the anchor
* Partial sells don't reset calculation baseline
* Allows tracking performance of remaining position
* If a subsequent **buy** occurs after a partial sell, that new buy **immediately replaces** the anchor; thresholds reset from the new buy price
* When multiple trades happen within the same 5‑minute time window, `lastTrade` always refers to the **chronologically latest** trade

#### SOL Handling

* Trade‑based SOL price changes are **muted in MVP**
* SOL is treated as an investment vehicle rather than a tracked asset for trade‑based alerts
* **Market‑based SOL** price change alerts remain available and are unaffected

#### Multiple Buys (DCA)

* Only most recent buy price is used as anchor
* No averaging across multiple purchases
* We do **not** average across buys. Any new buy supersedes the prior anchor and restarts threshold tracking

## Implementation Examples

### Market-Based Price Change Handler

```javascript theme={null}
app.post('/webhook/price-events', (req, res) => {
  const event = req.body;

  // Send push notification to users holding this token
  sendPushNotification({
    title: `${event.token.symbol} ${event.change.direction === 'up' ? '📈' : '📉'} ${event.change.percentage.toFixed(1)}%`,
    body: `${event.token.symbol} moved ${event.change.percentage.toFixed(1)}% in the last ${event.trigger.window.duration}`,
    data: {
      tokenAddress: event.token.address,
      priceChange: event.change.percentage
    }
  });

  res.status(200).send('OK');
});
```

### Trade-Based Price Change Handler

```javascript theme={null}
app.post('/webhook/last-trade-events', async (req, res) => {
  const { events } = req.body;

  for (const event of events) {
    const { walletAddress, token, trigger, changes } = event;

    // Determine alert message based on context
    let message;
    if (trigger.trade.type === 'buy' && !changes.lastPeak) {
      // Simple price change from buy
      message = `${token.symbol} is ${changes.triggerTrade.change.direction} ` +
        `${Math.abs(changes.triggerTrade.change.percentage).toFixed(1)}% ` +
        `since you bought`;
    } else if (changes.lastPeak) {
      // Round trip from previous threshold
      message = `${token.symbol} is back to ` +
        `${changes.triggerTrade.change.percentage > 0 ? '+' : ''}` +
        `${Math.abs(changes.triggerTrade.change.percentage).toFixed(1)}% ` +
        `from ${changes.lastPeak.change.percentage > 0 ? '+' : ''}` +
        `${Math.abs(changes.lastPeak.change.percentage).toFixed(1)}%`;
    }

    // Send personalized notification
    await sendUserNotification(walletAddress, {
      title: `${token.symbol} Price Alert`,
      body: message,
      data: {
        tokenAddress: token.address,
        currentPrice: changes.triggerTrade.change.to.value
      }
    });
  }

  res.status(200).send('OK');
});
```