> 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/outcome-analytics/outcome-builder-dashboard.md).

# Outcome Builder Analytics

## Outcome Builder Analytics API

API reference for the **outcome builder** analytics endpoints. These expose trading volume, fees, and activity for builders operating on outcome (prediction) markets — both **builder-level** totals/time-series and a **per-category** breakdown (`crypto`, `sports`, `economics`, `politics`, …).

***

### Base URL

```
https://api.hydromancer.xyz
```

### Authentication

Send your API key as a Bearer token on every request:

```
Authorization: Bearer <your-api-key>
```

Your key must be authorized for these endpoints — contact us to enable access.

### Conventions

* **`builder`** — a builder address. Use `builder=null` for fills not attributed to any builder.
* **`category`** — the market category. Categories are resolved at **read time** from the market's registration / settlement metadata, so newly tagged markets (and any re-tagging) are reflected automatically. **Markets with no category tag resolve to `crypto`** (the default). New categories such as `politics` appear automatically once their markets are tagged upstream — no API change.
* **Volume** counts matched trades only (`Buy` / `Sell`). Settlement and other position-lifecycle actions are not counted as volume, fees, or users.
* **Decimal values** (prices, sizes, volumes, fees) are returned as **strings** to preserve precision, e.g. `"1234.56"`. Trade times are Unix milliseconds; hours and dates are UTC.
* Per-category series are **sparse**: a `(period, category)` row appears only if it had activity. A category with no fills in a period is simply absent.

***

## Builder-level analytics

### 1. All-time builder stats

```
GET /dashboard/outcome-builder-stats?builder=<address|null>
```

All-time outcome trading totals for one builder.

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-stats?builder=0xabc...123"
```

```json
{
  "builder": "0xabc...123",
  "builderFee": "10523.40",
  "volume": "48210334.50",
  "volumeShare": "0.1834",
  "fills": 91245,
  "uniqueUsers": 5120
}
```

| Field         | Description                                |
| ------------- | ------------------------------------------ |
| `builderFee`  | Total builder fees collected               |
| `volume`      | All-time traded volume (notional)          |
| `volumeShare` | Share of total outcome market volume (0–1) |
| `fills`       | Number of trades                           |
| `uniqueUsers` | Distinct users who traded                  |

***

### 2. Daily volume

```
GET /dashboard/outcome-builder-volume-daily
```

Daily volume time-series. With no `builder`, returns the top builders by volume; with a `builder`, returns just that builder.

| Param           | Default     | Description                                                         |
| --------------- | ----------- | ------------------------------------------------------------------- |
| `startDate`     | 30 days ago | Inclusive start, `YYYY-MM-DD`                                       |
| `endDate`       | today (UTC) | Inclusive end, `YYYY-MM-DD`                                         |
| `builder`       | —           | Restrict to a single builder (or `null`)                            |
| `limitBuilders` | `20`        | Number of top builders (max `100`)                                  |
| `format`        | `packed`    | `rows` for one row per builder/day, `packed` for chart-ready arrays |

Date range cannot exceed 365 days.

**Packed** (default — aligned arrays for charting):

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-volume-daily?startDate=2026-06-01&endDate=2026-06-03&limitBuilders=2"
```

```json
{
  "startDate": "2026-06-01",
  "endDate": "2026-06-03",
  "builders": ["0xabc...123", "0xdef...456"],
  "dates": ["2026-06-01", "2026-06-02", "2026-06-03"],
  "series": {
    "volume":      [["120000.00", "98000.00", "143000.00"], ["50000.00", "61000.00", "47000.00"]],
    "fills":       [[820, 640, 910], [310, 402, 288]],
    "uniqueUsers": [[140, 122, 165], [70, 88, 64]],
    "builderFee":  [["240.00", "196.00", "286.00"], ["100.00", "122.00", "94.00"]]
  }
}
```

In `series`, each metric is indexed `[builder][day]`, aligned to `builders[]` and `dates[]`.

**Rows** (`format=rows`):

```json
{
  "startDate": "2026-06-01",
  "endDate": "2026-06-03",
  "builders": ["0xabc...123"],
  "days": [
    { "date": "2026-06-01", "builder": "0xabc...123", "volume": "120000.00", "fills": 820, "uniqueUsers": 140, "builderFee": "240.00" }
  ]
}
```

***

### 3. Hourly stats

```
GET /dashboard/outcome-builder-hourly?builder=<address|null>
```

Hourly time-series for one builder.

| Param     | Default      | Description                          |
| --------- | ------------ | ------------------------------------ |
| `builder` | — (required) | Builder address, or `null`           |
| `hours`   | `72`         | Lookback window in hours (max `168`) |
| `format`  | `packed`     | `rows` or `packed`                   |

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-hourly?builder=0xabc...123&hours=3"
```

```json
{
  "builder": "0xabc...123",
  "startHour": "2026-06-15 09:00:00",
  "endHour": "2026-06-15 11:00:00",
  "hours": ["2026-06-15 09:00:00", "2026-06-15 10:00:00", "2026-06-15 11:00:00"],
  "series": {
    "volume":              ["12000.00", "9800.00", "14300.00"],
    "fills":               [82, 64, 91],
    "activeUsers":         [14, 12, 16],
    "newUsers":            [3, 1, 2],
    "biggestNotionalFill": ["2400.00", "1900.00", "3100.00"]
  }
}
```

Each array in `series` is aligned to `hours[]`. Hours are UTC, formatted `YYYY-MM-DD HH:00:00`.

| Field                 | Description                                        |
| --------------------- | -------------------------------------------------- |
| `activeUsers`         | Users who traded in the hour                       |
| `newUsers`            | Users trading with this builder for the first time |
| `biggestNotionalFill` | Largest single trade (notional) in the hour        |

**Rows** (`format=rows`):

```json
{
  "builder": "0xabc...123",
  "startHour": "2026-06-15 09:00:00",
  "endHour": "2026-06-15 11:00:00",
  "rows": [
    { "hour": "2026-06-15 09:00:00", "volume": "12000.00", "fills": 82, "activeUsers": 14, "newUsers": 3, "biggestNotionalFill": "2400.00" }
  ]
}
```

***

### 4. Recent fills

```
GET /dashboard/outcome-builder-recent-fills?builder=<address>
```

The 100 most recent trades for one builder, newest first. Requires a builder address (the unattributed `null` bucket is not available for this endpoint).

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-recent-fills?builder=0xabc...123"
```

```json
{
  "builder": "0xabc...123",
  "fills": [
    {
      "coin": "#TRUMP-YES",
      "px": "0.62",
      "sz": "1500",
      "side": "B",
      "dir": "Buy",
      "time": 1750000000000,
      "fee": "0.93",
      "builderFee": "0.31",
      "feeToken": "USDC",
      "user": "0xuser...789"
    }
  ]
}
```

| Field                | Description                 |
| -------------------- | --------------------------- |
| `coin`               | Outcome market symbol       |
| `px` / `sz`          | Trade price / size          |
| `side`               | `B` (buy) or `A` (sell)     |
| `dir`                | `Buy` or `Sell`             |
| `time`               | Trade time (Unix ms)        |
| `fee` / `builderFee` | Total fee / builder portion |
| `user`               | Trader address              |

***

## Per-category analytics

These endpoints break a builder's activity down by market **category** — `crypto`, `sports`, `economics`, `politics`, … — for volume, fees, fills, and unique traders. **1 outcome = 1 market.**

### 5. All-time category breakdown

```
GET /dashboard/outcome-builder-category-stats?builder=<address|null>
```

All-time per-category totals for one builder, ordered by volume (descending).

| Param     | Default      | Description                |
| --------- | ------------ | -------------------------- |
| `builder` | — (required) | Builder address, or `null` |

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-category-stats?builder=0xabc...123"
```

```json
{
  "builder": "0xabc...123",
  "overall": {
    "tradingDays": 52,
    "uniqueMarkets": 431,
    "maxMarketsDay": { "date": "2026-06-11", "markets": 74 }
  },
  "categories": [
    {
      "category": "crypto",
      "builderFee": "8021.10",
      "volume": "36900000.00",
      "volumeShare": "0.7655...",
      "fills": 71200,
      "fillsShare": "0.7804...",
      "uniqueUsers": 4100,
      "uniqueUsersShare": "0.8007...",
      "tradingDays": 51,
      "uniqueMarkets": 228,
      "maxMarketsDay": { "date": "2026-06-17", "markets": 14 }
    },
    {
      "category": "sports",
      "builderFee": "2210.30",
      "volume": "10800000.00",
      "volumeShare": "0.2240...",
      "fills": 19000,
      "fillsShare": "0.2082...",
      "uniqueUsers": 2600,
      "uniqueUsersShare": "0.5078...",
      "tradingDays": 30,
      "uniqueMarkets": 202,
      "maxMarketsDay": { "date": "2026-06-11", "markets": 62 }
    }
  ]
}
```

`overall` is the builder's totals across all categories (omitted if the builder has no activity). Each `categories[]` entry carries the same metrics scoped to that category:

| Field              | Description                                                                          |
| ------------------ | ------------------------------------------------------------------------------------ |
| `category`         | Market category (`crypto` for untagged markets)                                      |
| `builderFee`       | Builder fees collected in this category                                              |
| `volume`           | Traded volume (notional) in this category                                            |
| `volumeShare`      | Category volume ÷ the builder's **total** volume (0–1)                               |
| `fills`            | Number of trades in this category                                                    |
| `fillsShare`       | Category fills ÷ the builder's **total** fills (0–1)                                 |
| `uniqueUsers`      | Distinct traders in this category                                                    |
| `uniqueUsersShare` | Category distinct traders ÷ the builder's **total distinct traders**                 |
| `tradingDays`      | Distinct UTC dates on which the builder traded (in this category)                    |
| `uniqueMarkets`    | Distinct markets traded (**1 outcome = 1 market**)                                   |
| `maxMarketsDay`    | The date with the most distinct markets traded, and that count (`{ date, markets }`) |

> `uniqueMarkets` is additive across categories (each market belongs to one category), but `tradingDays` and `maxMarketsDay` are **not** — `overall` recomputes them over the builder's whole activity (e.g. one day may be the peak for several categories at once).

> `volumeShare` and `fillsShare` partition the builder's totals and sum to 1 across categories. `uniqueUsersShare` uses the builder's **actual** distinct trader count as the denominator (not a sum of per-category counts), so it is the fraction of the builder's traders who traded each category — these **can sum to more than 1**, because a trader active in two categories is counted in both.

***

### 6. Daily category series

```
GET /dashboard/outcome-builder-category-daily?builder=<address|null>
```

Daily per-category time-series for one builder.

| Param       | Default      | Description                   |
| ----------- | ------------ | ----------------------------- |
| `builder`   | — (required) | Builder address, or `null`    |
| `startDate` | 30 days ago  | Inclusive start, `YYYY-MM-DD` |
| `endDate`   | today (UTC)  | Inclusive end, `YYYY-MM-DD`   |

Date range cannot exceed 365 days.

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-category-daily?builder=0xabc...123&startDate=2026-06-20&endDate=2026-06-21"
```

```json
{
  "builder": "0xabc...123",
  "startDate": "2026-06-20",
  "endDate": "2026-06-21",
  "rows": [
    { "date": "2026-06-20", "category": "crypto",  "volume": "898353.00",  "fills": 28335, "uniqueUsers": 1180, "builderFee": "180.40", "biggestNotionalFill": "1010.00" },
    { "date": "2026-06-20", "category": "sports",  "volume": "3115011.00", "fills": 15985, "uniqueUsers": 5400, "builderFee": "623.00", "biggestNotionalFill": "16618.00" },
    { "date": "2026-06-21", "category": "crypto",  "volume": "1106184.00", "fills": 34377, "uniqueUsers": 1240, "builderFee": "221.20", "biggestNotionalFill": "1189.00" }
  ]
}
```

Rows are ordered by `date` ascending, then `category`.

***

### 7. Hourly category series

```
GET /dashboard/outcome-builder-category-hourly?builder=<address|null>
```

Hourly per-category time-series for one builder over a rolling window.

| Param     | Default      | Description                          |
| --------- | ------------ | ------------------------------------ |
| `builder` | — (required) | Builder address, or `null`           |
| `hours`   | `72`         | Lookback window in hours (max `168`) |

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-category-hourly?builder=0xabc...123&hours=3"
```

```json
{
  "builder": "0xabc...123",
  "startHour": "2026-06-22 03:00:00",
  "endHour": "2026-06-22 05:00:00",
  "rows": [
    { "hour": "2026-06-22 03:00:00", "category": "crypto", "volume": "205068.00", "fills": 7978, "uniqueUsers": 48, "builderFee": "41.00", "biggestNotionalFill": "1546.00" },
    { "hour": "2026-06-22 03:00:00", "category": "sports", "volume": "151581.00", "fills": 259,  "uniqueUsers": 67, "builderFee": "30.30", "biggestNotionalFill": "16618.00" },
    { "hour": "2026-06-22 05:00:00", "category": "crypto", "volume": "569723.00", "fills": 24779, "uniqueUsers": 70, "builderFee": "113.90", "biggestNotionalFill": "1189.00" }
  ]
}
```

Rows are ordered by `hour` ascending, then `category`. Hours are UTC, formatted `YYYY-MM-DD HH:00:00`.

#### Daily / hourly category row fields

The daily and hourly category rows carry the **same** metric set (only the period key differs — `date` vs `hour`):

| Field                 | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `volume`              | Traded volume (notional) in the period × category               |
| `fills`               | Number of trades                                                |
| `uniqueUsers`         | Distinct traders                                                |
| `builderFee`          | Builder fees collected (`"0.00"` for the `null` builder bucket) |
| `biggestNotionalFill` | Largest single trade (notional) in the period × category        |

***

### 8. Recent fills by category

```
GET /dashboard/outcome-builder-category-recent-fills?builder=<address>&category=<category>
```

The 100 most recent trades for one builder, newest first, **each labeled with its category**. Pass `category` to return only that category's fills (including `category=crypto` for untagged markets); omit it to return all categories.

| Param      | Default      | Description                                       |
| ---------- | ------------ | ------------------------------------------------- |
| `builder`  | — (required) | Builder address, or `null` for unattributed fills |
| `category` | — (all)      | Restrict to a single category, e.g. `sports`      |

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.hydromancer.xyz/dashboard/outcome-builder-category-recent-fills?builder=0xabc...123&category=sports"
```

Each fill is the **standard fill object** (same shape as the other fills endpoints) with an added `category`. The example below shows the commonly used fields; the full object also includes `startPosition`, `closedPnl`, `hash`, `oid`, `crossed`, `tid`, `cloid`, `deployerFee`, `priorityGas`, `twapId`, `txIndex`, `liquidation`, and `builder`.

```json
{
  "builder": "0xabc...123",
  "category": "sports",
  "fills": [
    {
      "coin": "#1001",
      "px": "0.62",
      "sz": "1500",
      "side": "B",
      "dir": "Buy",
      "time": 1750000000000,
      "fee": "0.93",
      "builderFee": "0.31",
      "feeToken": "USDC",
      "user": "0xuser...789",
      "category": "sports"
    }
  ]
}
```

| Field                | Description                                                    |
| -------------------- | -------------------------------------------------------------- |
| `coin`               | Outcome market symbol (`#<assetId>`)                           |
| `px` / `sz`          | Trade price / size                                             |
| `side`               | `B` (buy) or `A` (sell)                                        |
| `dir`                | `Buy` or `Sell`                                                |
| `time`               | Trade time (Unix ms)                                           |
| `fee` / `builderFee` | Total fee / builder portion                                    |
| `user`               | Trader address                                                 |
| `category`           | Resolved category for the fill's market (`crypto` if untagged) |

When `category` is omitted, the top-level `category` field is `null` and each fill is labeled with its own category.

***

### Errors

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| `400`  | Missing or invalid parameter              |
| `401`  | Missing or invalid API key                |
| `403`  | Key not authorized for this endpoint      |
| `404`  | No data for the requested builder         |
| `429`  | Rate limit exceeded — slow down and retry |

Errors are returned as JSON:

```json
{ "error": "builder is required" }
```