> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/builder-guides/builder-performance-analytics.md).

# Builder performance analytics

Measure builder revenue, volume, trader outcomes, positioning and retention.

Use Builder Dashboard endpoints to measure your routed trading activity. The dashboard supports product reporting, builder economics, and trader-quality analysis.

### Start with window stats

Call [Builder Dashboard](https://docs.hydromancer.xyz/readme/builder-analytics/builder-dashboard.md) with your builder address and a window such as `7d` or `30d`.

The response includes routed volume, eligible builder-fee revenue, fills, distinct traders, and market share. Revenue includes fees paid in `USDC`, `USDT0`, or `USDE` only.

```bash
curl --compressed -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/builder-stats?builder=0xYOUR_BUILDER&window=7d"
```

Use `withToday=true` to add the current UTC day's partial results. The settled window remains unchanged.

### Build your dashboard

Use these endpoints together:

* [Builder Dashboard](https://docs.hydromancer.xyz/readme/builder-analytics/builder-dashboard.md) — window totals, per-asset volume, daily series, positioning, profitability, and cohorts.
* [builderFills](https://docs.hydromancer.xyz/readme/websocket/builder-data/builderfills.md) — live fills routed through your builder.
* [builderOrdersByTime](https://docs.hydromancer.xyz/readme/rest-api/historical-data/builderordersbytime.md) — historical order-status updates for operational reporting.

Treat the `builder` field as routing attribution. A fill counts here when the order used your builder code.

### Understand trader outcomes

Use the profitability endpoint for completed perp and spot trades. It reports wins, losses, net PnL, fees, funding PnL, and hold-time percentiles.

Outcome-market activity is separate. Use [Outcome Builder Analytics](https://docs.hydromancer.xyz/readme/outcome-analytics/outcome-builder-dashboard.md) for HIP-4 volumes, fees, category breakdowns, and outcome profitability.

{% hint style="info" %}
Do not add the perp/spot and outcome profitability results without care. Each API uses a separate trade lineage.
{% endhint %}

### Measure retention

Use `builder-retention-cohorts` to group traders by their first routed fill. Each later week shows how many returned through your builder.

Weeks run Monday through Sunday in UTC. Use `censored` to identify cohorts affected by the start of available history.

### Handle empty results

A known builder with no activity during a requested window returns zero totals. An address that has never routed a fill returns `404`.
