{"openapi":"3.1.0","info":{"title":"x402 Quant API","description":"Quantitative crypto-derivatives data (Hyperliquid), pay-per-call.","version":"0.1.0"},"paths":{"/api/v1/funding/{coin}":{"get":{"tags":["funding"],"summary":"Current and projected funding rate of a perp","description":"Funding-rate state of a Hyperliquid perpetual, read from the data lake: the latest tick's hourly rate, its annualized projection, 24h and 7d annualized means, and sign streaks. Returns data, not recommendations.","operationId":"get_funding_api_v1_funding__coin__get","parameters":[{"name":"coin","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9@_-]+$","description":"Perp symbol, e.g. 'HYPE'.","title":"Coin"},"description":"Perp symbol, e.g. 'HYPE'."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundingResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/basis/{coin}":{"get":{"tags":["basis"],"summary":"Spot-perp premium (basis) of a perp","description":"Spot-perp premium state of a Hyperliquid perpetual, read from the data lake: the latest tick's premium (~(mark - oracle) / oracle) in basis points, its 24h and 7d means, sign streaks, and how often it crossed zero in the last 24h. Returns data, not recommendations.","operationId":"get_basis_api_v1_basis__coin__get","parameters":[{"name":"coin","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9@_-]+$","description":"Perp symbol, e.g. 'HYPE'.","title":"Coin"},"description":"Perp symbol, e.g. 'HYPE'."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasisResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hip3/{dex}/{asset}":{"get":{"tags":["hip3"],"summary":"HIP-3 (builder-deployed) market health","description":"Risk/health snapshot of a HIP-3 perp on Hyperliquid (tokenized stocks, commodities, forex, pre-IPO): oracle deviation, impact-spread liquidity, open interest vs cap, 24h volume & change, funding (with the builder's custom multiplier), oracle/deployer controllers, plus risk flags and a health score. Live, point-in-time. Returns data, not recommendations.","operationId":"get_hip3_api_v1_hip3__dex___asset__get","parameters":[{"name":"dex","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Builder dex, e.g. 'xyz'.","title":"Dex"},"description":"Builder dex, e.g. 'xyz'."},{"name":"asset","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Asset, e.g. 'NVDA'.","title":"Asset"},"description":"Asset, e.g. 'NVDA'."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hip3HealthResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hip3/{dex}/{asset}/decision":{"get":{"tags":["hip3"],"summary":"HIP-3 pre-trade decision (composite)","description":"ONE decision-ready call before trading or sizing a HIP-3 market: a tradeability verdict (tradeable/caution/avoid), the cost to execute (round-trip impact spread), the health score with its sub-components, funding, spot-perp basis, OI-vs-cap, and human-readable risk flags. Composes the funding/basis/health signals into one answer. Data, not advice.","operationId":"get_hip3_decision_route_api_v1_hip3__dex___asset__decision_get","parameters":[{"name":"dex","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Builder dex.","title":"Dex"},"description":"Builder dex."},{"name":"asset","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Asset.","title":"Asset"},"description":"Asset."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hip3DecisionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/hip3/{dex}/{asset}/preview":{"get":{"tags":["hip3"],"summary":"HIP-3 decision preview (free)","description":"Free teaser: the verdict band (tradeable/caution/avoid) and a one-line reason. The cost-to-execute and the full sub-score breakdown are in the paid /decision endpoint.","operationId":"get_hip3_preview_route_api_v1_hip3__dex___asset__preview_get","parameters":[{"name":"dex","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Builder dex.","title":"Dex"},"description":"Builder dex."},{"name":"asset","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9]+$","description":"Asset.","title":"Asset"},"description":"Asset."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hip3PreviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/methodology":{"get":{"tags":["methodology"],"summary":"HIP-3 scoring & verdict methodology","description":"The exact formula behind the health score and the tradeability verdict: each sub-component's signal, threshold and penalty, and the verdict rules. Free, transparent, and the single source of truth for the thresholds.","operationId":"get_methodology_api_v1_methodology_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Methodology Api V1 Methodology Get"}}}}}}}},"components":{"schemas":{"BasisResponse":{"properties":{"coin":{"type":"string","title":"Coin","description":"Perp symbol, e.g. 'HYPE'."},"latest_premium":{"type":"string","title":"Latest Premium","description":"Spot-perp premium of the latest tick, as a decimal fraction (~(mark - oracle) / oracle)."},"latest_ts":{"type":"string","format":"date-time","title":"Latest Ts","description":"UTC timestamp of the latest tick available in the data lake."},"age_seconds":{"type":"integer","title":"Age Seconds","description":"Age of the latest tick in seconds (now - latest_ts). Premium is hourly."},"stale":{"type":"boolean","title":"Stale","description":"True if the latest tick is older than the service's freshness threshold."},"latest_premium_bps":{"type":"number","title":"Latest Premium Bps","description":"Latest premium expressed in basis points (premium × 10000)."},"mean_premium_bps_24h":{"type":"number","title":"Mean Premium Bps 24H","description":"Mean premium over the last 24 hours, in basis points."},"mean_premium_bps_7d":{"type":"number","title":"Mean Premium Bps 7D","description":"Mean premium over the last 7 days, in basis points."},"positive_streak_hours":{"type":"integer","title":"Positive Streak Hours","description":"Consecutive hours with premium > 0 at the end of the series."},"negative_streak_hours":{"type":"integer","title":"Negative Streak Hours","description":"Consecutive hours with premium < 0 at the end of the series."},"sign_flips_24h":{"type":"integer","title":"Sign Flips 24H","description":"Number of times the premium crossed zero over the last 24 hours (churn)."}},"type":"object","required":["coin","latest_premium","latest_ts","age_seconds","stale","latest_premium_bps","mean_premium_bps_24h","mean_premium_bps_7d","positive_streak_hours","negative_streak_hours","sign_flips_24h"],"title":"BasisResponse","description":"Spot-perp premium state of a Hyperliquid perp (read from the data lake)."},"FundingResponse":{"properties":{"coin":{"type":"string","title":"Coin","description":"Perp symbol, e.g. 'HYPE'."},"latest_rate":{"type":"string","title":"Latest Rate","description":"Hourly funding rate of the latest tick, as a decimal per hour."},"latest_ts":{"type":"string","format":"date-time","title":"Latest Ts","description":"UTC timestamp of the latest tick available in the data lake."},"age_seconds":{"type":"integer","title":"Age Seconds","description":"Age of the latest tick in seconds (now - latest_ts). Funding is hourly."},"stale":{"type":"boolean","title":"Stale","description":"True if the latest tick is older than the service's freshness threshold."},"annualized_pct":{"type":"number","title":"Annualized Pct","description":"Annualized projection of the current rate: rate × 24 × 365 × 100 (%)."},"mean_24h_pct_annualized":{"type":"number","title":"Mean 24H Pct Annualized","description":"Mean rate over the last 24 hours, annualized (%)."},"mean_7d_pct_annualized":{"type":"number","title":"Mean 7D Pct Annualized","description":"Mean rate over the last 7 days, annualized (%)."},"positive_streak_hours":{"type":"integer","title":"Positive Streak Hours","description":"Consecutive hours with rate > 0 at the end of the series."},"negative_streak_hours":{"type":"integer","title":"Negative Streak Hours","description":"Consecutive hours with rate < 0 at the end of the series."}},"type":"object","required":["coin","latest_rate","latest_ts","age_seconds","stale","annualized_pct","mean_24h_pct_annualized","mean_7d_pct_annualized","positive_streak_hours","negative_streak_hours"],"title":"FundingResponse","description":"Funding-rate state of a Hyperliquid perp (read from the data lake)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Hip3DecisionResponse":{"properties":{"market":{"type":"string","title":"Market","description":"Market id, 'dex:ASSET' (e.g. 'xyz:NVDA')."},"dex":{"type":"string","title":"Dex","description":"Builder dex slug."},"asset":{"type":"string","title":"Asset","description":"Asset symbol within the dex."},"verdict":{"type":"string","title":"Verdict","description":"tradeable | caution | avoid — the pre-trade call."},"reasons":{"items":{"type":"string"},"type":"array","title":"Reasons","description":"Execution-framed reason per active risk flag."},"cost_to_execute_bps":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost To Execute Bps","description":"Round-trip impact spread at Hyperliquid's impact notional (the headline execution cost; same signal as the liquidity component)."},"health_score":{"type":"integer","title":"Health Score","description":"Heuristic health score 0 (worst)..100 (best)."},"components":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Components","description":"Per-dimension breakdown (liquidity, oracle, capacity, funding, volume): value + which flag tripped, if any."},"funding_apr_pct":{"type":"number","title":"Funding Apr Pct","description":"Annualized funding (%)."},"basis_bps":{"type":"number","title":"Basis Bps","description":"Spot-perp basis = (mark - oracle) / oracle in bps (oracle = spot ref)."},"oi_utilization_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oi Utilization Pct","description":"Open interest as % of its cap."},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"Active risk flags."},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"UTC timestamp the live data was fetched."}},"type":"object","required":["market","dex","asset","verdict","reasons","health_score","components","funding_apr_pct","basis_bps","flags","as_of"],"title":"Hip3DecisionResponse","description":"Pre-trade decision for a HIP-3 market: verdict + execution-framed breakdown."},"Hip3HealthResponse":{"properties":{"market":{"type":"string","title":"Market","description":"Market id, 'dex:ASSET' (e.g. 'xyz:NVDA')."},"dex":{"type":"string","title":"Dex","description":"Builder dex slug (e.g. 'xyz', 'vntl', 'flx')."},"asset":{"type":"string","title":"Asset","description":"Asset symbol within the dex (e.g. 'NVDA')."},"mark_price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mark Price","description":"Current mark price."},"oracle_price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oracle Price","description":"Current oracle price."},"mid_price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mid Price","description":"Current mid price, if available."},"oracle_deviation_bps":{"type":"number","title":"Oracle Deviation Bps","description":"(mark - oracle) / oracle in basis points; large => price dislocated."},"impact_spread_bps":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Impact Spread Bps","description":"Impact ask/bid spread over mid, in bps; a liquidity proxy."},"open_interest_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Open Interest Usd","description":"Open interest in USD (OI × mark)."},"oi_cap_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oi Cap Usd","description":"Streaming OI cap (USD), if published."},"oi_utilization_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oi Utilization Pct","description":"Open interest as a percentage of its cap; near 100 => saturated."},"day_volume_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Day Volume Usd","description":"24h notional volume (USD)."},"day_change_pct":{"type":"number","title":"Day Change Pct","description":"24h price change vs previous day (%)."},"funding_rate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Funding Rate","description":"Latest hourly funding rate (decimal)."},"funding_apr_pct":{"type":"number","title":"Funding Apr Pct","description":"Annualized funding: rate × 24 × 365 × 100 (%)."},"funding_multiplier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Funding Multiplier","description":"Builder's custom funding multiplier, if set."},"max_leverage":{"type":"integer","title":"Max Leverage","description":"Max leverage allowed on the market."},"oracle_updater":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Oracle Updater","description":"Address allowed to move the oracle (centralization risk)."},"deployer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployer","description":"Builder-dex deployer address."},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"Active risk flags: wide_spread, thin_volume, oracle_drift, near_cap, extreme_funding."},"health_score":{"type":"integer","title":"Health Score","description":"Heuristic health score 0 (worst)..100 (best)."},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"UTC timestamp the live data was fetched."}},"type":"object","required":["market","dex","asset","mark_price","oracle_price","oracle_deviation_bps","open_interest_usd","day_volume_usd","day_change_pct","funding_rate","funding_apr_pct","max_leverage","flags","health_score","as_of"],"title":"Hip3HealthResponse","description":"Health snapshot of a HIP-3 (builder-deployed) Hyperliquid perp market."},"Hip3PreviewResponse":{"properties":{"market":{"type":"string","title":"Market","description":"Market id, 'dex:ASSET'."},"verdict":{"type":"string","title":"Verdict","description":"tradeable | caution | avoid."},"reason":{"type":"string","title":"Reason","description":"One-line, number-free reason for the verdict."},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"UTC timestamp the live data was fetched."}},"type":"object","required":["market","verdict","reason","as_of"],"title":"Hip3PreviewResponse","description":"Free teaser: verdict band + a number-free one-line reason.\n\nDeliberately withholds `cost_to_execute_bps`, the sub-score breakdown, and the\nnumeric reasons — those are the position-sizing inputs gated behind x402."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}