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

# Building a builder revenue dashboard

> Assemble platform totals, revenue over time, top traders, retention cohorts, and volume concentration for a single Polymarket builder code using the Builders analytics endpoints.

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](/guides/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.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: global } = await client.builders.getGlobal({
    timeframe: "30d",
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/global?timeframe=30d" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/builders/global",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"timeframe": "30d"},
  )

  global_totals = response.json()["data"]
  ```
</CodeGroup>

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`.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: series } = await client.builders.getBuilderTimeseries({
    builder_code: "0xBUILDER",
    resolution: "D",
    count_back: 90,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/analytics/timeseries?resolution=D&count_back=90" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/builders/0xBUILDER/analytics/timeseries",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"resolution": "D", "count_back": 90},
  )

  series = response.json()["data"]
  ```
</CodeGroup>

Each `BuilderTimeBucketRow` uses compact single-letter keys to keep the payload small. They map as follows:

| Key  | Meaning             |
| ---- | ------------------- |
| `t`  | Bucket timestamp    |
| `v`  | Volume in USD       |
| `bv` | Buy volume in USD   |
| `sv` | Sell volume in USD  |
| `tc` | Transaction count   |
| `f`  | Total fees in USD   |
| `bf` | Builder fees in USD |
| `ut` | Unique 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.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: traders } = await client.builders.getBuilderTopTraders({
    builder_code: "0xBUILDER",
    sort_by: "builder_fees",
    sort_desc: true,
    limit: 25,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/top-traders?sort_by=builder_fees&sort_desc=true&limit=25" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/builders/0xBUILDER/top-traders",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"sort_by": "builder_fees", "sort_desc": True, "limit": 25},
  )

  traders = response.json()["data"]
  ```
</CodeGroup>

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.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: cohorts } = await client.builders.getBuilderRetention({
    builder_code: "0xBUILDER",
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/retention" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/builders/0xBUILDER/retention",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  cohorts = response.json()["data"]
  ```
</CodeGroup>

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.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: concentration } = await client.builders.getBuilderConcentration({
    builder_code: "0xBUILDER",
    timeframe: "30d",
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/concentration?timeframe=30d" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.struct.to/v1/polymarket/builders/0xBUILDER/concentration",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"timeframe": "30d"},
  )

  concentration = response.json()["data"]
  ```
</CodeGroup>

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.

<CodeGroup>
  ```typescript SDK theme={null}
  const { data: fees } = await client.builders.getBuilderFees({
    builder_code: "0xBUILDER",
  });

  const { data: feeHistory } = await client.builders.getBuilderFeesHistory({
    builder_code: "0xBUILDER",
    limit: 100,
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/fees" \
    -H "X-API-Key: YOUR_API_KEY"

  curl "https://api.struct.to/v1/polymarket/builders/0xBUILDER/fees/history?limit=100" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  headers = {"X-API-Key": "YOUR_API_KEY"}
  base = "https://api.struct.to/v1/polymarket/builders/0xBUILDER"

  fees = requests.get(f"{base}/fees", headers=headers).json()["data"]

  fee_history = requests.get(
      f"{base}/fees/history",
      headers=headers,
      params={"limit": 100},
  ).json()["data"]
  ```
</CodeGroup>

`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.

<Tip>
  For per-trade rows behind these aggregates, pair this dashboard with [Fetching trades by builder code](/guides/fetching-trades-by-builder-code).
</Tip>