> For the complete documentation index, see [llms.txt](https://docs.zeroauthority.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zeroauthority.xyz/nova-bot/alerts-setup-guides/token-swaps-alerts.md).

# Token Swaps Alerts

Monitor any Stacks token in real time — get an alert whenever someone buys (or sells) your tracked tokens, with customizable thresholds and visuals.

| Plan    | Token Limit |
| ------- | ----------- |
| Free    | 3 tokens    |
| Premium | 20 tokens   |

***

## What Each Alert Includes

| Field           | Description                                       |
| --------------- | ------------------------------------------------- |
| Swap Direction  | Buy or Sell indicator                             |
| Position Change | New Holder, Position Up, or Position Down         |
| Token Amounts   | From/To token quantities                          |
| USD Value       | Dollar value of the trade                         |
| DEX             | Which decentralized exchange the swap happened on |
| Market Cap      | Current market cap (if available)                 |
| Custom Emoji    | Your chosen emoji displayed alongside the alert   |

***

## Setup

1. Use the `/nova` command and select **"Token Swaps"**.
2. Follow the wizard steps:
   * Toggle alerts on/off
   * **(Discord only)** pick a channel for the alerts — skip in DMs
   * **(Discord only)** confirm the blockchain (Stacks)
   * Enter the token's **smart contract address** (e.g. `SP123...::token-name`)
   * Choose alert mode: **Buys only** or **Buys & Sells**
   * Set a minimum transaction threshold: **$1**, **$10**, **$30**, **$100**, or **$1,000**
   * Select an **emoji** for your alerts
   * Upload a custom **image/GIF** or use the default
   * Review the summary and confirm
3. When you see the success message, your token swaps alerts are live.

***

## Configuration Options

| Option             | Description                                   | Required |
| ------------------ | --------------------------------------------- | -------- |
| Contract address   | The Stacks token contract to monitor          | Yes      |
| Alert mode         | Buys only, or Buys & Sells                    | Yes      |
| Min. USD threshold | Ignore swaps below this dollar amount         | Yes      |
| Emoji              | Custom emoji displayed in alerts              | Yes      |
| Image              | Custom image/GIF uploaded to IPFS, or default | Optional |