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

# The Alert Object

> Understand exactly what we're handing you when we catch a whale.

Whether you're hitting the REST APIs (`/alerts`, `/hot-markets`) or listening to the live WebSocket stream, every single alert you receive follows this exact JSON structure.

## Core Fields

| Field            | Type    | What it tells you                                                       |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| `id`             | integer | Our internal unique tracking ID.                                        |
| `alert_type`     | string  | `fresh`, `fresh_accumulator`, or `cluster`. (See below).                |
| `wallet_address` | string  | The literal on-chain address of the trader.                             |
| `market_id`      | string  | The Polymarket contract address for this specific market.               |
| `event_slug`     | string  | The URL-friendly name of the market.                                    |
| `event_title`    | string  | The actual human-readable market question.                              |
| `side`           | string  | Always `BUY` or `SELL`.                                                 |
| `outcome`        | string  | What they bet on (`Yes`, `No`, or a specific multi-choice name).        |
| `entry_price`    | float   | The price they paid per share (0.01 – 0.99).                            |
| `usdc_value`     | float   | Exactly how much USDC they deployed on this specific trade.             |
| `signal_score`   | integer | Our AI rating from 0–100 measuring the likelihood of insider knowledge. |
| `trade_count`    | integer | How many different markets this wallet has historically traded.         |
| `category`       | string  | e.g., `crypto`, `politics`, `world`.                                    |
| `created_at`     | string  | UTC timestamp of when we detected the trade.                            |

### Resolution Fields

These fields are populated only after the market has officially resolved on Polymarket. While the market is live, they remain `null` or `false`.

| Field         | Type    | What it tells you                                           |
| ------------- | ------- | ----------------------------------------------------------- |
| `resolved`    | boolean | True if the market has officially closed and paid out.      |
| `won`         | boolean | True if this specific alerted trade ended up taking profit. |
| `profit_usdc` | float   | The net P\&L realized by the trader.                        |

***

## Alert Types Breakdown

We classify insider activity into three distinct buckets, and inject specific tracking data into the `details` object depending on what we see.

<AccordionGroup>
  <Accordion title="fresh — The Ghost Protocol">
    A brand new wallet with zero or near-zero history suddenly drops heavy volume on a specific outcome. These are the strongest raw insider signals because wallets are often funded exclusively to execute this one trade without tying back to a main identity.

    ```json The Details Object theme={null}
    {
      "wallet_age_days": 0
    }
    ```
  </Accordion>

  <Accordion title="fresh_accumulator — The High Conviction Buyer">
    A fresh wallet that isn't just buying once — they are repeatedly smashing the buy button on the exact same market over time. This shows extreme conviction.

    ```json The Details Object theme={null}
    {
      "wallet_age_days": 2,
      "is_accumulating": true,
      "market_buy_count": 4,          // How many separate buys they've executed
      "market_total_bought": 6200.0,  // Total USDC deployed across all buys
      "market_avg_price": 0.31        // Their blended average entry price
    }
    ```
  </Accordion>

  <Accordion title="cluster — The Coordinated Strike">
    We detect multiple completely separate wallets all buying the exact same outcome within a very tight time window. Highly indicative of coordinated groups or single actors using distributed wallets.

    ```json The Details Object theme={null}
    {
      "cluster_size": 5,              // How many wallets moved together
      "cluster_total_usdc": 12500.0,  // The combined volume of the strike
      "cluster_wallets": [            // The addresses involved
        "0x1abc...", 
        "0x2def...", 
        "0x3ghi..."
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## The Full Payload Example

Here is exactly what a `fresh_accumulator` alert looks like when it hits your server:

```json Right off the wire theme={null}
{
  "id": 2220,
  "alert_type": "fresh_accumulator",
  "wallet_address": "0x9B3b4e3bD0e9c72FF8b1A3cE7dA1f6BC3",
  "market_id": "0x1234...abcd",
  "event_slug": "us-strikes-iran-by-march-31-2026",
  "event_title": "US strikes Iran by March 31?",
  "side": "BUY",
  "outcome": "Yes",
  "entry_price": 0.19,
  "usdc_value": 1900.0,
  "signal_score": 80,
  "trade_count": 1,
  "category": "world",
  "created_at": "2026-02-27 11:35:26",
  "resolved": false,
  "won": null,
  "profit_usdc": null,
  "details": {
    "wallet_age_days": 2,
    "is_accumulating": true,
    "market_buy_count": 3,
    "market_total_bought": 4500.0,
    "market_avg_price": 0.22
  }
}
```