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

# Trader Category PnL

> Get notified when a trader's per-category PnL crosses a configured threshold.

<Note>
  **Event:** `trader_category_pnl` \
  **Endpoint:** `wss://api.struct.to/ws/alerts` \
  **Cost:** 0.1 credits per event
</Note>

Fires when a trader's profit and loss aggregated across all markets in a given category (for example politics, sports, or crypto) crosses the configured thresholds. This is useful for tracking how a wallet performs within a specific category rather than across its whole portfolio or a single market.

## Filters

| Filter | Type | Required | Description |
| - | - | - | - |
| `traders` | `string[]` | No | Specific trader wallet addresses (max 500) |
| `categories` | `string[]` | No | Restrict to specific categories (max 500) |
| `min_realized_pnl_usd` | `number` | No | Minimum realized PnL in USD |
| `max_realized_pnl_usd` | `number` | No | Maximum realized PnL in USD |
| `min_volume_usd` | `number` | No | Minimum total volume in USD |
| `max_volume_usd` | `number` | No | Maximum total volume in USD |
| `min_buy_usd` | `number` | No | Minimum buy volume in USD |
| `min_sell_volume_usd` | `number` | No | Minimum sell volume in USD |
| `min_win_rate` | `number` | No | Minimum win rate percentage (0.0 to 100.0) |
| `min_markets_traded` | `number` | No | Minimum number of markets traded within the category |
| `timeframes` | `string[]` | No | Timeframe windows: `1d`, `7d`, `30d`, `lifetime` (max 500) |

## Subscribe

```json theme={null}
{
  "op": "subscribe",
  "event": "trader_category_pnl",
  "traders": ["0x37BA57e2942A57F05B5E4BCFD4d027845cFC40ec"],
  "categories": ["politics"],
  "min_realized_pnl_usd": 2000,
  "min_markets_traded": 3
}
```

## Response

```json theme={null}
{
  "event": "trader_category_pnl",
  "timestamp": 1775913505260,
  "data": {
    "trader": "0x37BA57e2942A57F05B5E4BCFD4d027845cFC40ec",
    "category": "politics",
    "timeframe": "7d",
    "realized_pnl_usd": 8500.25,
    "total_pnl_usd": 9100.00,
    "markets_in_category": 12,
    "markets_traded": 5,
    "outcomes_traded": 8,
    "total_buys": 45,
    "total_sells": 30,
    "total_redemptions": 10,
    "total_merges": 3,
    "total_splits": 1,
    "total_volume_usd": 75000.00,
    "buy_usd": 50000.00,
    "sell_usd": 15000.00,
    "redemption_usd": 8000.00,
    "merge_usd": 2000.00,
    "split_volume_usd": 500.00,
    "convert_collateral_usd": 1200.00,
    "total_shares_bought": 120000.00,
    "markets_won": 4,
    "markets_lost": 1,
    "market_win_rate_pct": 80.00,
    "avg_hold_time_seconds": 432000.0,
    "best_trade_pnl_usd": 3200.00,
    "best_trade_condition_id": "0x4fec624c0ff2bfae89956cebd6fbc9c58f995f824382dc587dc5a32a4b15940b",
    "worst_trade_pnl_usd": -450.00,
    "worst_trade_condition_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
    "total_wins_usd": 9800.00,
    "total_losses_usd": -1300.00,
    "avg_win_usd": 2450.00,
    "avg_loss_usd": -1300.00,
    "profit_factor": 7.54,
    "total_fees": 150.00,
    "first_trade_at": 1712966400,
    "last_trade_at": 1713052800
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.