Skip to main content
The Builders namespace exposes aggregated analytics for every Polymarket builder_code, the 0x app or integrator code attached to routed order flow. This guide stitches those endpoints into a single dashboard: headline KPIs, a revenue chart, a top-traders leaderboard, retention cohorts, and a concentration breakdown, plus the current fee configuration and its change log. For raw, per-trade attribution rather than aggregates, see Fetching trades by builder code.

​
When to use this

  • Giving a partner or integrator a self-serve revenue and engagement dashboard.
  • Tracking builder fees earned over time and how fee-rate changes affected them.
  • Understanding who a builder’s biggest traders are and how concentrated their volume is.
  • Measuring how well a builder retains traders after their first day.
Every response below is wrapped in an envelope, so the payload lives under .data. With the SDK, destructure const { data } = await client.builders.... With cURL or Python, read response.json()["data"].

​
Platform-wide totals

Start with getGlobal for platform context across all builders. The timeframe parameter accepts "lifetime", "24h", "1d", "7d", "30d", or "1mo". Use these figures as the baseline a single builder is measured against. 
const { data: global } = await client.builders.getGlobal({
  timeframe: "30d",
});
The BuilderGlobalLatestRow payload returns volume_usd, buy_volume_usd, sell_volume_usd, unique_traders, txn_count, fees_usd, builder_fees, and distinct_builders, along with ts and block marking when the snapshot was taken.

​
Revenue over time

getBuilderTimeseries returns one row per time bucket so you can plot a builder’s revenue trend. The resolution parameter accepts "60" and "240" (minutes), "D" or "1D" (daily), "W" or "1W" (weekly), and "M" or "1M" (monthly), defaulting to "60". Bound the range with from, to, or count_back. 
const { data: series } = await client.builders.getBuilderTimeseries({
  builder_code: "0xBUILDER",
  resolution: "D",
  count_back: 90,
});
Each BuilderTimeBucketRow uses compact single-letter keys to keep the payload small. They map as follows:
KeyMeaning
tBucket timestamp
vVolume in USD
bvBuy volume in USD
svSell volume in USD
tcTransaction count
fTotal fees in USD
bfBuilder fees in USD
utUnique traders
For a revenue chart, plot bf (builder fees earned) over t, and overlay f (total fees) or v (volume) for context. The most recent row’s bf doubles as a live “builder fees this bucket” KPI for the dashboard header.

​
Top traders

getBuilderTopTraders ranks the wallets driving a builder’s flow. Sort with sort_by, one of "volume", "txns", "fees", or "builder_fees", and set sort_desc to control direction. limit defaults to 10 and caps at 250. The optional timeframe scopes the window. 
const { data: traders } = await client.builders.getBuilderTopTraders({
  builder_code: "0xBUILDER",
  sort_by: "builder_fees",
  sort_desc: true,
  limit: 25,
});
Each TopTraderRow carries the trader profile plus volume_usd, txn_count, fees_usd, and builder_fees, which map directly onto a leaderboard table.

​
Retention cohorts

getBuilderRetention groups traders by the day they first traded through the builder, then reports how many came back. Bound the cohorts with the optional from and to parameters. 
const { data: cohorts } = await client.builders.getBuilderRetention({
  builder_code: "0xBUILDER",
});
Each CohortRetentionRow reports cohort_day (epoch seconds at UTC midnight), cohort_size, a retained object with absolute counts (D1, D7, D30), and a retention object with the same keys expressed as fractions. Render retention as a cohort grid where rows are cohort_day and columns are the D1 / D7 / D30 windows.

​
Volume concentration

getBuilderConcentration shows how much of a builder’s volume comes from its largest wallets, a quick read on whether revenue is broad-based or dependent on a few accounts. The optional timeframe scopes the calculation. 
const { data: concentration } = await client.builders.getBuilderConcentration({
  builder_code: "0xBUILDER",
  timeframe: "30d",
});
The ConcentrationResponse returns total_volume_usd and total_traders alongside top1_volume_usd, top10_volume_usd, and top100_volume_usd, plus the matching top1_share, top10_share, and top100_share fractions. The share fields are ideal for a concentration bar or a single “top 10 wallets drive X percent of volume” stat.

​
Fee configuration and history

Two endpoints round out the dashboard. getBuilderFees returns the builder’s current fee rates, and getBuilderFeesHistory returns the change log so you can annotate the revenue chart with rate changes. On the history call, limit defaults to 100 and caps at 1000. 
const { data: fees } = await client.builders.getBuilderFees({
  builder_code: "0xBUILDER",
});

const { data: feeHistory } = await client.builders.getBuilderFeesHistory({
  builder_code: "0xBUILDER",
  limit: 100,
});
getBuilderFees returns a BuilderFeeRate with code, builder_maker_fee_rate_bps, builder_taker_fee_rate_bps, and enabled. Rates are in basis points. Each BuilderFeeRateHistoryEntry repeats those fields and adds observed_at (epoch seconds), so the entries form a timeline of every rate change.
For per-trade rows behind these aggregates, pair this dashboard with Fetching trades by builder code.
Last modified on June 13, 2026