Cohorts

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

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:

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`);

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")

Use cohorts to filter API queries

Pass cohort addresses to fill queries to analyze specific groups:

TypeScript

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

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

Getting Started

Concepts

Guides

Terminal

SDKs

Predefined cohorts

Custom cohorts

Use cohorts to filter API queries

Manage cohorts

Tier limits

​Predefined cohorts

​Custom cohorts

​Use cohorts to filter API queries

​Manage cohorts

​Tier limits

Predefined cohorts

Custom cohorts

Use cohorts to filter API queries

Manage cohorts

Tier limits