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

> Fire a webhook when a trader's aggregated realized PnL for a market category crosses your configured bounds.

<Note>
  **Event:** `trader_category_pnl` \
  **Cost:** 0.1 credits per delivery
</Note>

Fires when a trader's aggregated realized PnL across all markets in a category crosses your configured bounds. The full payload schema is in the auto-generated [Trader Category PnL callback](/api-reference/webhook-callbacks/category-pnl-callback) reference; this page documents the filters and matching behavior.

## When to use this

* Alert when a trader's combined PnL across a market category (such as Politics or Sports) clears a profit or loss threshold.
* Track category-level specialization by scoping to the categories a trader is active in rather than individual markets.
* Qualify category conviction by pairing PnL bounds with volume, win rate, and the number of distinct markets traded.

## Subscription filters

Add these to the `filters` object when you create the subscription.

| Filter                 | Type      | Description                                             |
| ---------------------- | --------- | ------------------------------------------------------- |
| `traders`              | string\[] | Restrict to specific trader wallet addresses (max 500). |
| `categories`           | string\[] | Restrict to specific market categories (max 500).       |
| `min_realized_pnl_usd` | number    | Minimum realized PnL in USD.                            |
| `max_realized_pnl_usd` | number    | Maximum realized PnL in USD.                            |
| `min_volume_usd`       | number    | Minimum traded volume in USD.                           |
| `max_volume_usd`       | number    | Maximum traded volume in USD.                           |
| `min_buy_usd`          | number    | Minimum buy-side volume in USD.                         |
| `min_sell_volume_usd`  | number    | Minimum sell-side volume in USD.                        |
| `min_win_rate`         | number    | Minimum win rate, `0.0`–`100.0`.                        |
| `min_markets_traded`   | integer   | Minimum number of distinct markets traded.              |
| `timeframes`           | string\[] | One or more PnL windows: `1d`, `7d`, `30d`, `lifetime`. |

## Example

```json theme={null}
{
  "url": "https://your-server.com/webhooks",
  "event": "trader_category_pnl",
  "filters": {
    "categories": ["Politics"],
    "min_realized_pnl_usd": 20000,
    "min_win_rate": 55.0,
    "min_markets_traded": 3,
    "timeframes": ["30d"]
  }
}
```

## Notes

* Combine `min_realized_pnl_usd` and `max_realized_pnl_usd` to match a PnL band rather than a single bound.
* `timeframes` scopes the window over which aggregated category PnL is measured; `lifetime` uses the trader's full history in that category.