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

# Cohorts

> Track groups of addresses — predefined smart money groups or your own custom lists.

Cohorts are named address groups you can use to filter market data. Ironflow provides six predefined cohorts computed from on-chain activity, and lets Enterprise customers create custom ones.

## Predefined cohorts

All predefined cohorts are recomputed from live ClickHouse data every 30 minutes and served from cache, so requests never block on a query. Names are stable; values rotate as activity changes.

| Cohort | Description |
| - | - |
| `top_pnl_30d` | Top 100 addresses by realized PnL over the last 30 days |
| `high_volume_30d` | Top 100 addresses by trading volume over the last 30 days |
| `whale_fills` | Addresses with individual fills exceeding \$1M in the last 7 days |
| `net_withdrawers_7d` | Addresses with net negative flow (withdrawals > deposits) in the last 7 days |
| `liquidation_prone` | Addresses with 2 or more liquidations in the last 30 days |
| `vault_whales` | Top 100 addresses by total vault deposit volume in the last 30 days |

```typescript TypeScript theme={null}
const cohorts = await client.listCohorts();
// [{ name: "top_pnl_30d", description: "Top 100 addresses by realized PnL ..." }, ...]

const result = await client.cohortAddresses("top_pnl_30d");
// { addresses: [{ address: "0x...", value: "428193.55" }, ...], fetched_at: 1718400000000 }
```

The `value` field carries the aggregate metric for that cohort: realized PnL for `top_pnl_30d`, traded notional for `high_volume_30d`, liquidation count for `liquidation_prone`, and so on.

## Custom cohorts

Create your own address groups to track specific wallets:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Ironflow } from "@ironflowsh/sdk";

  const client = new Ironflow("if_your_api_key");

  // Create a cohort of addresses you want to track
  const cohort = await client.createCohort({
    name: "my_copy_targets",
    addresses: [
      "0xalice_address",
      "0xbob_address",
      "0xcharlie_address",
    ],
  });

  console.log(`Created cohort with ${cohort.address_count} addresses`);
  ```

  ```python Python theme={null}
  from ironflow_sdk import Ironflow

  async with Ironflow("if_your_api_key") as client:
      cohort = await client.create_cohort(
          name="my_copy_targets",
          addresses=["0xalice_address", "0xbob_address", "0xcharlie_address"],
      )
      print(f"Created cohort with {cohort.address_count} addresses")
  ```
</CodeGroup>

## Use cohorts to filter API queries

Pass cohort addresses to fill queries to analyze specific groups:

```typescript TypeScript theme={null}
const addresses = await client.cohortAddresses("my_copy_targets");

for (const { address } of addresses.addresses) {
  const fills = await client.fills({ address, market: "BTC-PERP", limit: 10 });
  console.log(`${address}: ${fills.data.length} recent fills`);
}
```

## Manage cohorts

```typescript TypeScript theme={null}
// List all cohorts
const all = await client.listCohorts();

// Delete a custom cohort (predefined cohorts cannot be deleted)
await client.deleteCohort("my_copy_targets");
```

## Tier limits

| Tier | Custom cohorts | Max addresses per cohort |
| - | - | - |
| Free | 0 (predefined only) | - |
| Explorer | 0 (predefined only) | - |
| Builder | 0 (predefined only) | - |
| Enterprise | Unlimited | 10,000 |


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