The Alert Object

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.

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.

The Details Object

{
  "wallet_age_days": 0
}

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.

The Details Object

{
  "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
}

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.

The Details Object

{
  "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..."
  ]
}

The Full Payload Example

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

Right off the wire

{
  "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
  }
}

Getting Started

Real-Time

Reference

Core Fields

Resolution Fields

Alert Types Breakdown

The Full Payload Example

​Core Fields

​Resolution Fields

​Alert Types Breakdown

​The Full Payload Example

Core Fields

Resolution Fields

Alert Types Breakdown

The Full Payload Example