> ## Documentation Index
> Fetch the complete documentation index at: https://hypernode-docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/leaderboards/deployers

> Per-outcome deployer revenue — revenue earned by whoever deployed each market.

<Note>
  **Feature status: `pending_upstream`.** Hyperliquid's HIP-4 deployer fee rate is currently 0 across every market — no deployer is earning anything on-chain yet. This endpoint is wired and will populate automatically the moment HL deployers start charging. Builder fees (a separate mechanism) ARE active and ranked at [`/v1/leaderboards/builders`](/leaderboards/builders).
</Note>

Each HIP-4 outcome has a deployer who can charge a fee on every fill (think Polymarket's market creator royalty). This endpoint ranks outcomes by how much their deployer has earned.

## Endpoint

```
GET /v1/leaderboards/deployers
```

## Query parameters

| Param   | Type   | Default     | Description                       |
| ------- | ------ | ----------- | --------------------------------- |
| `by`    | string | `"revenue"` | One of `revenue`, `volume`, `bps` |
| `limit` | int    | 100         | Max rows (cap 500)                |

## Response (current — feature pending)

```json theme={null}
{
  "ranked_by": "revenue",
  "count": 0,
  "deployers": [],
  "note": "HIP-4 deployer fee rate is currently 0 across all markets — Hyperliquid has not activated deployer revenue on-chain yet. This endpoint will populate automatically once HL deployers start earning fees. Builder fees (separate mechanism) are tracked at /v1/leaderboards/builders.",
  "feature_status": "pending_upstream"
}
```

## Response (future — when HL activates deployer fees)

```json theme={null}
{
  "ranked_by": "revenue",
  "count": 1,
  "deployers": [
    {
      "rank": 1,
      "outcome_id": 0,
      "title": "BTC >= $78213 by 2026-05-03 06:00 UTC (1d)",
      "outcome_name": "Recurring",
      "underlying": "BTC",
      "target_price": "78213",
      "fills_count": 26732,
      "volume_usdh": "1147289.829980",
      "deployer_fees_total_usdh": "147.32",
      "effective_bps": "1.28",
      "distinct_fee_tokens": 1,
      "first_trade": { "us": 1777719604322000, "iso": "...", "relative": "7h ago" },
      "last_trade":  { "us": 1777743859009000, "iso": "...", "relative": "51m ago" }
    }
  ],
  "feature_status": "live"
}
```

| Field                      | Description                                                                   |
| -------------------------- | ----------------------------------------------------------------------------- |
| `deployer_fees_total_usdh` | Lifetime USDH-equivalent collected by this outcome's deployer                 |
| `effective_bps`            | `deployer_fees_total / volume_usdh × 10000` — average rate charged            |
| `distinct_fee_tokens`      | Number of different `fee_token` values seen (signals USDH vs share-side fees) |

## Ranking modes

* `by=revenue` — `deployer_fees_total` DESC. Default.
* `by=volume` — outcomes with biggest USDH volume regardless of deployer fee.
* `by=bps` — outcomes with the highest effective deployer rate. Useful for finding outliers.

## Use cases

* **Market-creator earnings dashboard** for HL teams running price-binary deployments.
* **Find outliers** — outcomes with `effective_bps > 50` are charging unusually high deployer fees.
* **Volume vs revenue analysis** — sort by volume, look at the bps column to see who's monetizing aggressively.

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -H "X-API-Key: hip4_live_..." \
    "https://hip4.polynode.dev/api/v1/leaderboards/deployers?limit=50"

  # Highest effective rate
  curl -H "X-API-Key: hip4_live_..." \
    "https://hip4.polynode.dev/api/v1/leaderboards/deployers?by=bps&limit=10"
  ```

  ```python Python theme={null}
  import requests
  r = requests.get("https://.../api/v1/leaderboards/deployers",
                   headers={"X-API-Key": key},
                   params={"by": "revenue"}).json()
  for d in r["deployers"][:10]:
      print(f"#{d['rank']:>2} oid={d['outcome_id']:>4} "
            f"vol=${d['volume_usdh']}  fees=${d['deployer_fees_total_usdh']}  "
            f"bps={d['effective_bps']}  {d['title'][:50]}")
  ```
</CodeGroup>

## Notes

* Currently empty across the board — see callout at top. Builder fees (active) are tracked at `/v1/leaderboards/builders`.
* `distinct_fee_tokens > 1` will mean the deployer has been collecting fees in different tokens across fills (e.g. some in USDH, some in share-side tokens).
* The deployer-of-an-outcome address is not exposed in current state — this endpoint groups by `outcome_id`, not by deployer address. Cross-outcome aggregation will arrive in a future schema update.

## How to know when this goes live

When `count > 0` and `feature_status: "live"` appears in the response, HL has activated deployer fees and revenue is flowing. The route shape is stable — no client changes needed.