GET /v1/leaderboards/builders

​

Endpoint

GET /v1/leaderboards/builders

​

Query parameters

​

Response

{
  "ranked_by": "revenue",
  "count": 3,
  "builders": [
    {
      "rank": 1,
      "builder_addr": "0xb84c7fb41ee7d8781e2b0d59eed2accd2ae99533",
      "fills_count": 344,
      "unique_users": 6,
      "unique_outcomes": 1,
      "volume_usdh": "14296.808060",
      "builder_fees_total_usdh": "2.80447791",
      "market_share_pct": "0.16060788145399383904",
      "first_seen": { "us": 1777726493006000, "iso": "...", "relative": "5h ago" },
      "last_seen":  { "us": 1777742873043000, "iso": "...", "relative": "1h ago" }
    }
  ]
}

​

Ranking modes

• by=revenue — builder_fees_total DESC. The “who’s making money” leaderboard. Default.
• by=volume — total USDH routed through, regardless of fee rate.
• by=fills — count of fills routed.
• by=users — distinct wallets that have used this builder.

​

Use cases

• Track a competing UI’s growth by polling weekly and watching volume_usdh climb.
• Identify integration partners — top builders by unique_users are well-distributed UIs worth talking to.
• Effective fee rate analysis — builder_fees_total / volume_usdh × 10000 = bps charged.

​

Examples

# Top 20 by revenue
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/leaderboards/builders?limit=20"

# Top by volume routed
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/leaderboards/builders?by=volume"

import requests
r = requests.get("https://.../api/v1/leaderboards/builders",
                 headers={"X-API-Key": key},
                 params={"by": "revenue", "limit": 25}).json()
for b in r["builders"]:
    bps = (float(b['builder_fees_total_usdh']) /
           float(b['volume_usdh']) * 10000) if float(b['volume_usdh']) > 0 else 0
    print(f"#{b['rank']:>2} {b['builder_addr'][:10]}...  "
          f"vol=${b['volume_usdh']}  fees=${b['builder_fees_total_usdh']}  "
          f"({bps:.1f} bps)  {b['unique_users']} users")

​

Notes

• Builders without a builder_addr (default HL frontend, or programmatic API users) are excluded.
• market_share_pct is recomputed every minute.
• Builder fees can be charged as a percentage of size — bps may vary across this builder’s fills.