API Documentation
Access Buildix data programmatically. All endpoints return JSON with CORS enabled.
Base URL
https://www.buildix.trade/api/v1/api/v1/screenerAll Hyperliquid pairs with price, volume, funding, OI.
{
"count": 311,
"data": [
{
"symbol": "BTC",
"price": 68957.0,
"change24h": -2.35,
"volume24h": 1282780165,
"openInterest": 1802345000,
"funding": -0.0000132,
"fundingAnnualized": -1.45
}
],
"timestamp": 1711108800000
}/api/v1/pair/{symbol}Detailed data for a single pair (e.g. /api/v1/pair/BTC).
{
"symbol": "BTC",
"price": 68957.0,
"change24h": -2.35,
"volume24h": 1282780165,
"openInterest": 1802345000,
"funding": -0.0000132,
"fundingAnnualized": -1.45,
"markPrice": 68957.0,
"oraclePrice": 68960.5,
"maxLeverage": 50,
"deepViewUrl": "https://www.buildix.trade/pair/BTC"
}/api/v1/liquidation-mapWHALEOn-chain liquidation clusters with cascade simulation. Query params: symbol (required), exchange (optional, default hyperliquid), price_range_pct (optional, 1-20, default 10), scenarios (optional, CSV of integers 1-50, default 5,10,15 — generates symmetric down/up entries for each value).
curl -H "x-api-key: bx_xxx" \ "https://www.buildix.trade/api/v1/liquidation-map?symbol=BTC&scenarios=5,10,15"
{
"symbol": "BTC",
"exchange": "hyperliquid",
"timestamp": 1761177600,
"current_price": 68957.0,
"price_range_pct": 10,
"clusters": [
{
"price": 67572.1,
"side": "long",
"estimated_liquidation_size_usd": 225293125,
"cumulative_size_usd": 225293125,
"distance_pct": -1.33
}
],
"cascade_scenarios": [
{ "move_pct": -15, "price_target": 58613.45, "side_triggered": "long", "liquidations_triggered_usd": 1080000000, "clusters_count": 4 },
{ "move_pct": -10, "price_target": 62061.30, "side_triggered": "long", "liquidations_triggered_usd": 900000000, "clusters_count": 3 },
{ "move_pct": -5, "price_target": 65509.15, "side_triggered": "long", "liquidations_triggered_usd": 540000000, "clusters_count": 2 },
{ "move_pct": 5, "price_target": 72404.85, "side_triggered": "short", "liquidations_triggered_usd": 540000000, "clusters_count": 2 },
{ "move_pct": 10, "price_target": 75852.70, "side_triggered": "short", "liquidations_triggered_usd": 900000000, "clusters_count": 3 },
{ "move_pct": 15, "price_target": 79300.55, "side_triggered": "short", "liquidations_triggered_usd": 1080000000, "clusters_count": 4 }
]
}Note: this endpoint uses a funding-rate-derived skew applied to a 50/50 OI split. For real wallet-aggregated long vs short OI on supported symbols, see /api/v1/smart-money-positioning below.
/api/v1/smart-money-positioningWHALEAggregated open positions of a curated sample of smart money traders on Hyperliquid. Higher-fidelity alternative to the funding-skew model used by /api/v1/liquidation-map. Refreshed every 15 minutes. Mainnet HL only — HIP-3 markets (xyz:BRENTOIL etc.) return 400 unsupported_market. Query param: symbol (required, plain ticker e.g. BTC).
curl -H "x-api-key: bx_xxx" \ "https://www.buildix.trade/api/v1/smart-money-positioning?symbol=BTC"
{
"symbol": "BTC",
"exchange": "hl",
"computed_at": 1777234567,
"data_age_seconds": 312,
"long_oi_usd": 1234567890.12,
"short_oi_usd": 987654321.10,
"long_short_ratio": 1.250,
"wallets_sampled": 78,
"wallets_long": 45,
"wallets_short": 33,
"coverage_pct": 23.83,
"market_oi_usd": 5180000000,
"sample_quality": "strong"
}Sample quality reference
sample_quality is derived server-side from coverage_pct so callers do not have to interpret the percentage. Use it as a confidence label.
| sample_quality | coverage_pct band | interpretation | today's example |
|---|---|---|---|
| strong | ≥ 20% | Signal robust across many wallets, weight fully. | BTC 23.83% |
| fair | 10–20% | Sample informative, weight modestly. | ETH 17.43% |
| thin | 5–10% | Sample sparse, treat as directional hint only. | SOL 7.07% |
Symbols with coverage_pct < 5% are filtered out at the cron and return 404 insufficient_coverage. On long-tail markets the coverage can be very high but concentrated on one or two wallets — wallets_long + wallets_short tells you how many actually contributed. A single wallet flipping side will move the ratio meaningfully on those symbols. Treat with extra care.
Stale data: if the aggregator cron has not refreshed a symbol within 30 minutes the endpoint returns 503 data_stale instead of serving old numbers as live.
alert.triggeredWHALELiquidation Metadata fields, included in the webhook payload that Buildix POSTs to your alert URL when an alert fires. These four fields plus a top-level metadata_version marker are added only for Whale-tier customers. Trader, Pro, Starter, and Free customers continue to receive the previous payload shape unchanged.
{
"event": "alert.triggered",
"alert_id": "...",
"symbol": "BTC",
"current_price": 65000,
// ...standard fields (signal, trend_filter, etc.)...
// ---- Whale-only additions ----
"metadata_version": "v1",
"liq_asymmetry_ratio": 1.25,
"liq_nearest_cluster_pct": 4.32,
"liq_regime_label": "asymmetric",
"liq_sample_quality": "strong"
}Field reference
| field | type | meaning |
|---|---|---|
| metadata_version | "v1" | Top-level marker. Pin to "v1" — future formula changes will bump this so you can branch on it client-side. |
| liq_asymmetry_ratio | number | Ratio of opposite-side to same-side liquidation USD at the ±5% scenarios, oriented by the alert's signal direction. Values > 1 mean the side that would liquidate on a profit-direction move dominates. |
| liq_nearest_cluster_pct | number | USD-weighted center-of-mass distance (in %) of the target-side liquidation clusters, scaled by relative crowding. Lower = nearer cascade pressure. |
| liq_regime_label | "symmetric" "asymmetric" "fragile" | Direction-agnostic classification of the long/short total-mass ratio. symmetric = balanced book; asymmetric = moderate skew; fragile = one side dominates. |
| liq_sample_quality | "strong" "fair" "neutral" | Coarse classification of the directional magnitude. Derived server-side from |liq_asymmetry_ratio − 1|. See bands below. |
liq_sample_quality bands
| liq_sample_quality | |ratio − 1| band | example ratios |
|---|---|---|
| strong | ≥ 0.20 | 1.25, 0.78, 1.45 |
| fair | ≥ 0.10 and < 0.20 | 1.15, 0.85, 1.10 |
| neutral | < 0.10 | 1.08, 0.95, 1.00 |
Naming note. The wallet aggregator endpoint /api/v1/smart-money-positioning exposes a sample_quality field derived from coverage_pct (how much of the market the smart money sample captures), while alerts expose liq_sample_quality derived from the liquidation asymmetry magnitude. They measure different things despite the similar naming pattern; do not conflate them in your integration logic.
Exposure-only. These metadata fields are exposed for transparency. Buildix does not currently filter or boost alerts based on these values server-side. Use them as supplementary signals at your own discretion.
alert.triggeredWHALESuggested TP/SL (Whale)
Three additional fields appended to alert.triggered webhook payloads for Whale-tier customers on signal_buy and signal_sell alerts. They suggest take-profit and stop-loss price levels based on volatility (ATR) and liquidation cluster magnetism.
{
"event": "alert.triggered",
"alert_id": "...",
"symbol": "BTC",
"current_price": 65000,
// ...standard fields + Whale liq_* metadata...
// ---- Whale-only Suggested TP/SL ----
"suggested_tp": 65697.75,
"suggested_sl": 64535.00,
"tp_sl_method": "cluster_magnet"
}Field reference
| field | type | meaning |
|---|---|---|
| suggested_tp | number | null | Suggested take-profit price level. Null when the suggestion is unavailable (env disabled, missing ATR, or non-signal alert). |
| suggested_sl | number | null | Suggested stop-loss price level. Null under the same conditions as suggested_tp. |
| tp_sl_method | enum | How the levels were computed. See tp_sl_method table below. |
tp_sl_method enum
| value | meaning |
|---|---|
| cluster_magnet | At least one of TP or SL was snapped to a liquidation cluster acting as a magnetic price level (cascade pressure). The other side may be ATR-based. |
| atr_capped | Eligible clusters existed but ATR cap won both sides because the clusters were beyond the 1.5x ATR target. Levels are entry +/- 1.5*ATR (TP) and entry -/+ 1.0*ATR (SL). |
| atr_only | No eligible liquidation clusters within 5x ATR of entry. Pure ATR-based levels with no cluster reference. |
| null | ATR data missing or non-positive for this symbol. Both suggested_tp and suggested_sl are null. |
| disabled | Server-side feature flag SIGNAL_TPSL_SUGGESTIONS_ENABLED is off. Both prices are null. Field is still emitted so client integrations can branch on tp_sl_method rather than on key presence. |
Not financial advice. These are suggested levels based on volatility (ATR) and liquidation cluster magnetism. They are not financial advice and not guaranteed to be optimal exit points. Use at your own discretion.
Method. Take-profit defaults to entry +/- 1.5 * ATR and stop-loss to entry -/+ 1.0 * ATR (1.5:1 risk-reward). When a liquidation cluster on the profit side sits between entry and the ATR target, TP snaps to the cluster (price tends to cascade liquidations rather than overshoot them). When a cluster on the loss side sits closer than the ATR stop, SL tightens to it (exit before the cascade widens the loss). ATR is computed from the last 24 hourly Hyperliquid candles (period 14) and cached server-side.
/api/v1/docsThis documentation as JSON (machine-readable).
Rate Limits
Authentication
Currently open access with IP-based rate limits. API key authentication coming soon. Generate your key at Account Settings.
Questions? Contact hello@buildix.trade