Skip to main content

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.

Returns markets ranked by activity — pick the window (24h or lifetime) and the metric (volume, traders, fills, fees).

​
Endpoint

GET /v1/leaderboards/markets

​
Query parameters

ParamTypeDefaultDescription
windowstring"lifetime"lifetime (all time) or 24h (rolling 24h)
bystring"volume"One of volume, traders, fills, fees
statusstring"all"One of active, resolved, all
limitint100Max rows (cap 500)

​
Response

{
  "window": "lifetime",
  "ranked_by": "volume",
  "status_filter": "all",
  "count": 1,
  "markets": [
    {
      "rank": 1,
      "outcome_id": 0,
      "title": "BTC >= $78213 by 2026-05-03 06:00 UTC (1d)",
      "underlying": "BTC",
      "target_price": "78213",
      "expiry_str": "20260503-0600",
      "status": "active",
      "fills_count": 26732,
      "unique_traders": 1299,
      "unique_takers": 1037,
      "unique_makers": 562,
      "volume_usdh": "1147289.829980",
      "volume_shares": "2261326.0",
      "fees_total": "6.28153367",
      "builder_fees_total": "6.28153367",
      "first_trade": { "us": 1777719604322000, "iso": "...", "relative": "7h ago" },
      "last_trade":  { "us": 1777743859009000, "iso": "...", "relative": "51m ago" }
    }
  ]
}
FieldDescription
unique_tradersDistinct wallets that filled either side
unique_takersDistinct takers (crossed the spread)
unique_makersDistinct makers (provided liquidity)
volume_sharesTotal shares matched (both sides combined)
fees_totalSum of all fees: base + builder + deployer

​
Ranking modes

  • by=volume — total USDH notional. Default. The “biggest market” view.
  • by=traders — distinct trader count. Best signal for “viral” markets even at low ticket size.
  • by=fills — count of fills. Activity / churn measure.
  • by=fees — total fees paid. The “highest-revenue market” leaderboard.

​
Use cases

  • Homepage “trending markets” widget: window=24h, by=volume, status=active, limit=20.
  • Largest-ever HIP-4 markets: window=lifetime, by=volume.
  • Most-engaged markets: by=traders to surface markets where lots of distinct wallets play, not just one whale.

​
Examples

# Trending in last 24h
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/leaderboards/markets?window=24h&by=volume&status=active&limit=20"

# All-time biggest by trader count
curl -H "X-API-Key: hip4_live_..." \
  "https://hip4.polynode.dev/api/v1/leaderboards/markets?by=traders&limit=50"

​
Notes

  • The 24h window is a rolling aggregation, refreshed each minute. Numbers are exact at the moment of the last refresh.
  • fees_total and builder_fees_total are equal whenever no deployer fee is being charged (current state on HIP-4 mainnet).
  • The maker/taker/trader counts are NOT additive — the same wallet can be a maker on some fills and a taker on others.