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.

Feature status: pending_upstream. Hyperliquid does not currently emit question metadata on-chain. The route is wired and stable but every call returns 404 until HL ships question records. See /v1/questions for the broader explanation.
A “question” on HIP-4 is a group of related outcomes (e.g. “Which team wins the Super Bowl?” with 32 child outcomes, one per team). Each outcome trades independently as its own Yes/No binary, but you usually want them aggregated. This endpoint does that math.

​
Endpoint

GET /v1/questions/:qid/aggregate
The :qid is the integer question_id from /v1/questions.

​
Response

{
  "question_id": 7,
  "name": "SuperBowl2027",
  "description": "Which team wins Super Bowl LXI",
  "outcome_count": 32,
  "fallback_outcome": null,
  "totals": {
    "fills_count": 8421,
    "unique_traders": 1240,
    "volume_usdh": "456789.123456",
    "sum_yes_probabilities": "1.04",
    "implied_overround_pct": "4.0"
  },
  "favorite_outcome_id": 12,
  "favorite_yes_mid": "0.34",
  "resolved_outcomes": 0,
  "active_outcomes": 32,
  "outcomes": [
    {
      "outcome_id": 12,
      "title": "Chiefs win Super Bowl LXI",
      "status": "active",
      "yes_mid": "0.34",
      "fills_count": 2031,
      "unique_traders": 488,
      "volume_usdh": "120832.10"
    },
    { "outcome_id": 5, "title": "Eagles ...", "yes_mid": "0.18", "...": "..." }
  ]
}
Top-level fieldDescription
outcome_countNumber of child outcomes belonging to this question
fallback_outcomeThe outcome that wins if none of the others do (e.g. “field” for sports)
favorite_outcome_idOutcome with the highest current yes_mid
favorite_yes_midThe favorite’s implied probability
resolved_outcomes / active_outcomesStatus counts across the family
totals fieldDescription
volume_usdhΣ lifetime volume across all child outcomes
unique_tradersΣ across child outcomes — note this DOUBLE-COUNTS wallets that traded multiple legs
sum_yes_probabilitiesΣ of yes_mid across all outcomes. Should ≈ 1.0 in an efficient market
implied_overround_pct(sum_yes_probabilities - 1) × 100. Positive = book is “vigged” / overpriced; negative = arbitrage available

​
Cross-outcome interpretations

  • sum_yes_probabilities ≈ 1.0: market is internally consistent. Buying every outcome’s Yes share at mid would cost ~1 USDH per “complete set.”
  • sum_yes_probabilities > 1.0: book is taking a vig — buying every Yes costs more than 1 USDH. The implied_overround_pct is the “rake.”
  • sum_yes_probabilities < 1.0: theoretical arbitrage — buying every Yes for less than 1 USDH guarantees a payout of exactly 1. Watch for stale mids on illiquid sides before you act on this.

​
Use cases

  • Question detail page — render a sortable table of outcomes with implied probabilities.
  • Find favorites + longshots at a glance.
  • Cross-outcome arbitrage scanner — flag questions where implied_overround_pct < 0.
  • Market efficiency comparison — compare overround across questions to find which markets are most/least competitive.

​
Examples

curl -H "X-API-Key: hip4_live_..." \
  https://hip4.polynode.dev/api/v1/questions/7/aggregate

​
404

HTTP 404
{
  "error": "question 7 not found",
  "note": "HIP-4 question metadata is not yet emitted on-chain by Hyperliquid. No questions exist in this index yet. Endpoint will work automatically once HL ships question records.",
  "feature_status": "pending_upstream"
}
Returned if the question doesn’t exist. Currently every call returns 404 because HL has not yet emitted any question records on-chain — see the callout at the top of this page.

​
Notes

  • unique_traders in totals is a Σ, NOT a distinct count across the question. A wallet that filled both leg A and leg B counts twice. Use /v1/markets/:id/holders per outcome for true distinct sets.
  • sum_yes_probabilities is computed from the latest poll mid per side (cadence ~1s). It can briefly be stale during fast moves.
  • favorite_outcome_id is whichever child has the highest yes_mid right now — recompute clientside if you want a 24h-stable favorite.
  • volume_usdh is lifetime; for 24h windows, query /v1/leaderboards/markets?window=24h and filter to the question’s outcome_ids.