{"externalDocs":{"description":"Full API, keyless and with a key","url":"https://docs.ironflow.sh/openapi.yaml"},"info":{"contact":{"email":"hello@ironflow.sh","name":"Ironflow","url":"https://ironflow.sh"},"description":"Hyperliquid market data from Ironflow's own nodes, paid per call in USDC on Base with x402: no account and no key. These are the endpoints listed in the x402 Bazaar. Every /v1 endpoint, free without a key within limits or with a free key, is in the full spec: https://docs.ironflow.sh/openapi.yaml","title":"Ironflow pay-per-call API (x402)","version":"1.0.0","x-guidance":"Call a path below; it answers 402 with x402 PAYMENT-REQUIRED terms. Pay them (any x402 client, e.g. @x402/fetch) and retry with PAYMENT-SIGNATURE. Paid calls are served at Builder limits: one year of history. from and to take Unix ms, ISO 8601 or relative times (-7d, now). A call that fails is not charged."},"openapi":"3.1.0","paths":{"/x402/v1/analytics/leaderboard-pnl":{"get":{"description":"Hyperliquid trader PnL leaderboard computed from every fill: wallets ranked by realized PnL, biggest losses or volume over a window, with win rate, fills, maker share, markets traded and max drawdown. Use it to find top traders and smart money wallets on Hyperliquid to study, follow or copy.","operationId":"getAnalyticsLeaderboardPnl","parameters":[{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-30d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Wallets to return","example":"50","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Ranking (default realized_pnl)","example":"realized_pnl","in":"query","name":"sort_by","required":false,"schema":{"enum":["realized_pnl","loss","volume"],"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"now","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"address":"0x1234567890abcdef1234567890abcdef12345678","fills":1415,"markets_count":4,"max_drawdown_pct":0.066,"pct_maker":0.852,"realized_pnl":503093.88,"volume_usd":14267972.06,"win_rate":0.753}],"sort_by":"realized_pnl"},"schema":{"description":"Wallets ranked","properties":{"data":{"description":"Wallets","items":{"description":"A wallet","properties":{"address":{"description":"Wallet address","type":"string"},"fills":{"description":"Fills","type":"integer"},"losses":{"description":"Losing closing fills","type":"integer"},"markets_count":{"description":"Markets traded","type":"integer"},"max_drawdown_pct":{"description":"Largest peak-to-trough drop in realized PnL, as a fraction","type":"number"},"pct_maker":{"description":"Share of fills as maker","type":"number"},"realized_pnl":{"description":"Realized PnL in the window, USD","type":"number"},"volume_usd":{"description":"Traded volume, USD","type":"number"},"win_rate":{"description":"wins / (wins + losses)","type":"number"},"wins":{"description":"Profitable closing fills","type":"integer"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"from":{"description":"Unix time in milliseconds","type":"integer"},"sort_by":{"description":"Ranking","type":"string"},"to":{"description":"Unix time in milliseconds","type":"integer"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Trader PnL leaderboard","tags":["hyperliquid","leaderboard","top-traders","smart-money","crypto"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/analytics/liquidation-levels":{"get":{"description":"Liquidated size on a Hyperliquid perp bucketed by price: at which price levels longs and shorts were liquidated, with count and total size per bucket and side, over a window of up to 7 days anywhere in the last year. Use it to map liquidation clusters and the crypto price levels where leverage was flushed, for BTC, ETH, SOL, HYPE or any other perp.","operationId":"getAnalyticsLiquidationLevels","parameters":[{"description":"Price bucket width (default 100)","example":"1000","in":"query","name":"bucket_size","required":false,"schema":{"enum":["1","5","10","50","100","500","1000","5000"],"type":"string"}},{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-7d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Buckets to return, busiest first","example":"50","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Market: BTC, ETH-PERP, HYPE/USDC, xyz:NVDA (HIP-3) or a Hyperliquid coin name","example":"BTC","in":"query","name":"market","required":true,"schema":{"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"now","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"count":4120,"market":"BTC-PERP","price_bucket":"78000","side":"sell","total_size":"352.7"}]},"schema":{"description":"Price buckets, most liquidations first","properties":{"data":{"description":"One row per price bucket and side","items":{"description":"A bucket","properties":{"count":{"description":"Liquidations in the bucket","type":"integer"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"price_bucket":{"description":"Bucket's lower price","type":"string"},"side":{"description":"Liquidation order side: sell closes a long, buy closes a short","enum":["buy","sell"],"type":"string"},"total_size":{"description":"Liquidated size in the base asset","type":"string"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Liquidation levels by price","tags":["hyperliquid","liquidation-levels","liquidations","crypto","perps"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/analytics/user-state":{"get":{"description":"Open positions and margin of any Hyperliquid wallet right now: per market size, entry and mark price, position value, unrealized PnL, return on equity and leverage, plus totals. Use it to check whether a wallet (a whale, a vault, a trader you follow) is long or short and how much it is up or down.","operationId":"getAnalyticsUserState","parameters":[{"description":"0x wallet address (42 characters)","example":"0x010461c14e146ac35fe42271bdc1134ee31c703a","in":"query","name":"address","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"address":"0x010461c14e146ac35fe42271bdc1134ee31c703a","asset_positions":[{"entry_price":78182,"leverage":5,"leverage_type":"cross","mark_price":77740,"market":"BTC-PERP","market_class":"perp","position_value":4189.41,"return_on_equity":-0.028,"size":0.05389,"unrealized_pnl":-23.82}],"margin_summary":{"open_markets_count":1,"total_position_value":4189.41,"total_unrealized_pnl":-23.82}},"schema":{"description":"A wallet's open positions","properties":{"address":{"description":"Wallet address","type":"string"},"asset_positions":{"description":"Open positions","items":{"description":"A position","properties":{"entry_price":{"description":"Average entry price","type":"number"},"leverage":{"description":"Leverage","type":"number"},"leverage_type":{"description":"Margin mode","enum":["cross","isolated"],"type":"string"},"mark_price":{"description":"Mark price","type":"number"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"market_class":{"description":"perp, spot, prediction or option","type":"string"},"position_value":{"description":"Position value, USD","type":"number"},"return_on_equity":{"description":"Unrealized PnL over margin used","type":"number"},"size":{"description":"Signed size in the base asset: negative is short","type":"number"},"unrealized_pnl":{"description":"Unrealized PnL, USD","type":"number"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"margin_summary":{"description":"Totals","properties":{"open_markets_count":{"description":"Open positions","type":"integer"},"total_position_value":{"description":"USD","type":"number"},"total_unrealized_pnl":{"description":"USD","type":"number"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Wallet positions","tags":["hyperliquid","wallet","positions","pnl","crypto"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/book":{"get":{"description":"Live L2 order book of any Hyperliquid market: up to 20 price levels a side with size and order count, best bid and ask, mid, spread in basis points and USD depth per side. Use it to check liquidity and slippage before a trade, or to read the book of crypto perps, spot pairs and HIP-3 stock and commodity markets. Optional sig_figs aggregates levels for a deeper view.","operationId":"getBook","parameters":[{"description":"Levels a side, 1 to 20 (default 20)","example":"20","in":"query","name":"depth","required":false,"schema":{"type":"string"}},{"description":"Market: BTC, ETH-PERP, HYPE/USDC, xyz:NVDA (HIP-3) or a Hyperliquid coin name","example":"BTC","in":"query","name":"market","required":true,"schema":{"type":"string"}},{"description":"Aggregate prices to 2 to 5 significant figures; leave out for full precision","example":"5","in":"query","name":"sig_figs","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"ask_depth_usd":40005,"asks":[{"orders":2,"price":"80010","size":"0.5"}],"best_ask":"80010","best_bid":"79990","bid_depth_usd":119985,"bids":[{"orders":3,"price":"79990","size":"1.5"}],"coin":"BTC","market":"BTC-PERP","mid":80000,"spread_bps":2.5,"time":1793900000000},"schema":{"description":"An order book","properties":{"ask_depth_usd":{"description":"USD notional of the asks returned","type":"number"},"asks":{"description":"Ask levels, best first","items":{"description":"A level","properties":{"orders":{"description":"Resting orders at the level","type":"integer"},"price":{"description":"Price","type":"string"},"size":{"description":"Size in the base asset","type":"string"}},"type":"object"},"type":"array"},"best_ask":{"description":"Best ask","type":"string"},"best_bid":{"description":"Best bid","type":"string"},"bid_depth_usd":{"description":"USD notional of the bids returned","type":"number"},"bids":{"description":"Bid levels, best first","items":{"description":"A level","properties":{"orders":{"description":"Resting orders at the level","type":"integer"},"price":{"description":"Price","type":"string"},"size":{"description":"Size in the base asset","type":"string"}},"type":"object"},"type":"array"},"coin":{"description":"Hyperliquid coin name","type":"string"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"mid":{"description":"Mid price","type":"number"},"spread_bps":{"description":"Spread in basis points of the mid","type":"number"},"stale":{"description":"True when Hyperliquid could not be reached and a book up to 10 s old is served","type":"boolean"},"time":{"description":"Unix time in milliseconds","type":"integer"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Live L2 order book","tags":["hyperliquid","order-book","l2","liquidity","crypto"],"x-payment-info":{"price":{"amount":"0.001","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/candles":{"get":{"description":"Hyperliquid OHLCV candles for any market from Ironflow's own nodes: open, high, low, close, base volume and trade count, intervals 1m to 1w, up to a year back. Use it for crypto price history, charting, backtests and indicators on perps, spot and HIP-3 stock or commodity markets.","operationId":"getCandles","parameters":[{"description":"next_cursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-30d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Candle interval (default 1h)","example":"1h","in":"query","name":"interval","required":false,"schema":{"enum":["1m","3m","5m","15m","30m","1h","2h","4h","8h","12h","1d","3d","1w"],"type":"string"}},{"description":"Candles per page","example":"720","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Market: BTC, ETH-PERP, HYPE/USDC, xyz:NVDA (HIP-3) or a Hyperliquid coin name","example":"BTC","in":"query","name":"market","required":true,"schema":{"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"now","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"close":"79660","high":"79661","interval":"1h","low":"79657","market":"BTC-PERP","open":"79657","timestamp":1793880000000,"trade_count":91,"volume":"11.36"}]},"schema":{"description":"Candles in time order","properties":{"data":{"description":"One row per candle","items":{"description":"A candle","properties":{"close":{"description":"Close price","type":"string"},"high":{"description":"High price","type":"string"},"interval":{"description":"Interval","type":"string"},"low":{"description":"Low price","type":"string"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"open":{"description":"Open price","type":"string"},"timestamp":{"description":"Candle open time, Unix ms","type":"integer"},"trade_count":{"description":"Trades in the candle","type":"integer"},"volume":{"description":"Volume in the base asset","type":"string"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"pagination":{"description":"Paging: pass next_cursor as cursor= for the next page","properties":{"has_more":{"description":"Whether more rows match","type":"boolean"},"next_cursor":{"description":"Cursor for the next page, empty when there is none","type":"string"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"OHLCV candles","tags":["hyperliquid","ohlcv","candles","price-history","crypto"],"x-payment-info":{"price":{"amount":"0.002","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/funding":{"get":{"description":"Hyperliquid perp funding rate history per market from Ironflow's own nodes: the hourly funding rate as charged, for native perps and HIP-3 markets, up to a year back. Use it for perp funding rates history, carry and basis trades, or to compare funding across crypto perps.","operationId":"getFunding","parameters":[{"description":"next_cursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-7d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Rows per page","example":"168","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Market: BTC, ETH-PERP, HYPE/USDC, xyz:NVDA (HIP-3) or a Hyperliquid coin name","example":"BTC","in":"query","name":"market","required":true,"schema":{"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"now","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"market":"BTC-PERP","rate":"0.0000125","timestamp":1793887206845}]},"schema":{"description":"Funding rates, one per market and hour","properties":{"data":{"description":"One row per funding interval","items":{"description":"A funding rate","properties":{"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"rate":{"description":"Hourly funding rate as a fraction (0.0000125 is 0.00125% an hour)","type":"string"},"timestamp":{"description":"Unix time in milliseconds","type":"integer"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"pagination":{"description":"Paging: pass next_cursor as cursor= for the next page","properties":{"has_more":{"description":"Whether more rows match","type":"boolean"},"next_cursor":{"description":"Cursor for the next page, empty when there is none","type":"string"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Funding rate history","tags":["hyperliquid","funding-rates","perps","crypto","derivatives"],"x-payment-info":{"price":{"amount":"0.002","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/liquidations":{"get":{"description":"Hyperliquid liquidations, one row per liquidated fill, from Ironflow's own nodes: market, side, price, size, wallet, realized PnL and time. Use it to look up crypto perp liquidations for a market, a wallet or any window up to a year back, or poll it with after= for new ones. Covers native perps and HIP-3 markets (stocks, commodities, FX).","operationId":"getLiquidations","parameters":[{"description":"0x wallet address (42 characters)","in":"query","name":"address","required":false,"schema":{"type":"string"}},{"description":"poll_cursor from the previous response: only newer liquidations","in":"query","name":"after","required":false,"schema":{"type":"string"}},{"description":"next_cursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-7d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Rows per page, 1 to 1000 (default 100)","example":"100","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Market, or a comma list (BTC,ETH); omit for every market","example":"BTC","in":"query","name":"market","required":false,"schema":{"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"-6d","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"complete_until":1793887710000,"data":[{"address":"0x1234567890abcdef1234567890abcdef12345678","hash":"0x357aac23552009e636f404482106b20000b5c408f02328b8d94357761423e3d0","market":"BTC-PERP","price":"79556","realized_pnl":"-30.45","side":"sell","size":"0.03496","timestamp":1793887706280}],"poll_cursor":"1793887706280-9"},"schema":{"description":"Liquidations, newest first","properties":{"complete_until":{"description":"Every liquidation up to this Unix ms time is included","type":"integer"},"data":{"description":"One row per liquidated fill","items":{"description":"A liquidation","properties":{"address":{"description":"Wallet address","type":"string"},"hash":{"description":"Transaction hash on Hyperliquid","type":"string"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"price":{"description":"Fill price","type":"string"},"realized_pnl":{"description":"PnL the liquidated wallet realized on this fill, USD","type":"string"},"side":{"description":"Liquidation order side: sell closes a long, buy closes a short","enum":["buy","sell"],"type":"string"},"size":{"description":"Size in the base asset","type":"string"},"timestamp":{"description":"Unix time in milliseconds","type":"integer"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"pagination":{"description":"Paging: pass next_cursor as cursor= for the next page","properties":{"has_more":{"description":"Whether more rows match","type":"boolean"},"next_cursor":{"description":"Cursor for the next page, empty when there is none","type":"string"}},"type":"object"},"poll_cursor":{"description":"Pass as after= to get only newer liquidations","type":"string"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Hyperliquid liquidations","tags":["hyperliquid","liquidations","perps","crypto","derivatives"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/liquidations/summary":{"get":{"description":"Hyperliquid liquidation totals over trailing windows (15m to 7d): long and short USD liquidated, number of liquidations and wallets, and the largest one, per market and overall. Use it to answer how much was liquidated in the last hour or day, or to rank crypto markets by liquidations, without paging raw rows. bucket=1h adds a long and short series per market.","operationId":"getLiquidationsSummary","parameters":[{"description":"Optional series per market over the longest window; needs market (at most 10)","example":"1h","in":"query","name":"bucket","required":false,"schema":{"enum":["15m","1h","4h"],"type":"string"}},{"description":"Optional comma list of markets; omit for every market","example":"BTC,ETH","in":"query","name":"market","required":false,"schema":{"type":"string"}},{"description":"Comma list of trailing windows: 15m, 1h, 4h, 12h, 24h, 7d (default 1h,4h,24h)","example":"1h,24h,7d","in":"query","name":"windows","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"as_of":1793890770944,"windows":[{"from":1793887170944,"largest":{"market":"BTC-PERP","price":78803.46,"side":"long","timestamp":1793889926067,"usd":2063941.3},"total":{"liquidations":6137,"long_usd":44981648.9,"short_usd":171729.7,"wallets":4727},"window":"1h"}]},"schema":{"description":"Totals per window","properties":{"as_of":{"description":"Unix time in milliseconds","type":"integer"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"windows":{"description":"One entry per requested window","items":{"description":"A window","properties":{"from":{"description":"Unix time in milliseconds","type":"integer"},"largest":{"description":"The largest liquidation in the window","properties":{"address":{"description":"Wallet address","type":"string"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"price":{"description":"Price","type":"number"},"side":{"description":"Position liquidated","enum":["long","short"],"type":"string"},"timestamp":{"description":"Unix time in milliseconds","type":"integer"},"usd":{"description":"USD size","type":"number"}},"type":"object"},"markets":{"description":"The same totals per market, largest first","items":{"description":"A market's totals","properties":{"liquidations":{"description":"Number of liquidations","type":"integer"},"long_usd":{"description":"USD of longs liquidated","type":"number"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"short_usd":{"description":"USD of shorts liquidated","type":"number"},"wallets":{"description":"Distinct wallets","type":"integer"}},"type":"object"},"type":"array"},"total":{"description":"All markets together","properties":{"liquidations":{"description":"Number of liquidations","type":"integer"},"long_usd":{"description":"USD of longs liquidated","type":"number"},"short_usd":{"description":"USD of shorts liquidated","type":"number"},"wallets":{"description":"Distinct wallets liquidated","type":"integer"}},"type":"object"},"window":{"description":"Window, e.g. 1h","type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Liquidation totals by window and market","tags":["hyperliquid","liquidations","crypto","market-summary","derivatives"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/markets/snapshot":{"get":{"description":"Every Hyperliquid market in one call: mark price, 24h change, open interest in base and USD, funding rate and 24h volume, for perps, spot, HIP-3 builder markets (stocks, commodities, FX) and HIP-4 outcomes. Use it as the starting point: to list markets, screen crypto perps by open interest, funding or volume, or get many prices at once.","operationId":"getMarketsSnapshot","parameters":[{"description":"Only one kind of market; omit for all","example":"perp","in":"query","name":"market_class","required":false,"schema":{"enum":["perp","spot","prediction","option"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"change_24h_pct":-0.031,"display_symbol":"BTC-PERP","funding_rate":0.0000125,"mark_price":78242,"mark_ts_ms":1793890758948,"market_class":"perp","open_interest_base":38019.06,"open_interest_usd":2974687102,"volume_24h_usd":3120000000}]},"schema":{"description":"One row per market","properties":{"data":{"description":"Markets","items":{"description":"A market","properties":{"change_24h_pct":{"description":"Change over 24 hours as a fraction","type":"number"},"display_symbol":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"funding_rate":{"description":"Current hourly funding rate","type":"number"},"issuer":{"description":"HIP-3 deployer (xyz, flx, ...), empty for native","type":"string"},"mark_price":{"description":"Mark price","type":"number"},"mark_ts_ms":{"description":"Unix time in milliseconds","type":"integer"},"market_class":{"description":"perp, spot, prediction or option","type":"string"},"open_interest_base":{"description":"Open interest in the base asset","type":"number"},"open_interest_usd":{"description":"Open interest in USD","type":"number"},"volume_24h_usd":{"description":"24-hour volume in USD","type":"number"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"pagination":{"description":"Paging: pass next_cursor as cursor= for the next page","properties":{"has_more":{"description":"Whether more rows match","type":"boolean"},"next_cursor":{"description":"Cursor for the next page, empty when there is none","type":"string"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Every market: price, open interest, funding, volume","tags":["hyperliquid","market-data","open-interest","funding-rates","crypto"],"x-payment-info":{"price":{"amount":"0.001","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/open-interest/changes":{"get":{"description":"Hyperliquid open interest movers: markets ranked by the change in open interest over 1h, 4h, 24h or 7d, in USD or percent, with start and end open interest and the mark price. Use it to find where positioning is building or unwinding across crypto perps and HIP-3 markets.","operationId":"getOpenInterestChanges","parameters":[{"description":"Only one HIP-3 deployer, e.g. xyz","in":"query","name":"dex","required":false,"schema":{"type":"string"}},{"description":"Markets, 1 to 200","example":"20","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Skip markets with less open interest than this, USD","example":"1000000","in":"query","name":"min_oi_usd","required":false,"schema":{"type":"string"}},{"description":"Rank by USD change or percent change (default usd)","example":"usd","in":"query","name":"sort","required":false,"schema":{"enum":["usd","pct"],"type":"string"}},{"description":"Window (default 24h)","example":"24h","in":"query","name":"window","required":false,"schema":{"enum":["1h","4h","24h","7d"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"count":20,"data":[{"change_pct":-4.81,"change_usd":-150454177,"mark":78242,"market":"BTC-PERP","oi_end":38019.06,"oi_end_usd":2974687102,"oi_start":39941.99}],"sort":"usd","window":"24h"},"schema":{"description":"Markets ranked by open interest change","properties":{"count":{"description":"Markets returned","type":"integer"},"data":{"description":"Markets","items":{"description":"A market","properties":{"change_pct":{"description":"Change in percent","type":"number"},"change_usd":{"description":"Change in USD","type":"number"},"dex":{"description":"HIP-3 deployer, absent for native perps","type":"string"},"mark":{"description":"Mark price","type":"number"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"oi_end":{"description":"Open interest now, base asset","type":"number"},"oi_end_usd":{"description":"Open interest now, USD","type":"number"},"oi_start":{"description":"Open interest at the start, base asset","type":"number"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"sort":{"description":"Ranking","type":"string"},"window":{"description":"Window","type":"string"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Open interest movers","tags":["hyperliquid","open-interest","perps","crypto","derivatives"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/predictions/summary":{"get":{"description":"Hyperliquid HIP-4 outcome (prediction) market activity: total notional, fills, wallets and active markets over 4h, 1d or 1w, an hourly series, and the active outcome markets with last price and 24h volume. Use it to see what is trading on Hyperliquid's prediction markets and how busy they are.","operationId":"getPredictionsSummary","parameters":[{"description":"Window (default 1d)","example":"1d","in":"query","name":"window","required":false,"schema":{"enum":["4h","1d","1w"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"active_markets":[{"display_symbol":"English Premier League 2026/2027-Arsenal-Yes","fills_24h":870,"last_price":0.5,"notional_24h":45382.3}],"fills_total":373500,"markets_active":1400,"notional_total":17662121.06,"wallets_total":2367,"window_hours":24},"schema":{"description":"Outcome market activity","properties":{"active_markets":{"description":"Active outcome markets","items":{"description":"A market","properties":{"display_symbol":{"description":"Outcome name","type":"string"},"fills_24h":{"description":"Fills in 24 hours","type":"integer"},"hl_coin":{"description":"Hyperliquid coin id","type":"string"},"last_price":{"description":"Last price (0 to 1)","type":"number"},"notional_24h":{"description":"USD in 24 hours","type":"number"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"fills_total":{"description":"Fills","type":"integer"},"hourly":{"description":"Hourly series","items":{"description":"An hour","properties":{"fills":{"description":"Fills","type":"integer"},"hour":{"description":"Hour, ISO 8601","type":"string"},"notional":{"description":"USD","type":"number"}},"type":"object"},"type":"array"},"markets_active":{"description":"Markets with fills","type":"integer"},"notional_total":{"description":"Traded notional, USD","type":"number"},"wallets_total":{"description":"Distinct wallets","type":"integer"},"window_hours":{"description":"Window in hours","type":"integer"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"HIP-4 outcome market activity","tags":["hyperliquid","prediction-markets","hip-4","outcomes","crypto"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/query":{"post":{"description":"Read-only ClickHouse SQL over Ironflow's Hyperliquid tables: every fill, trade, liquidation, funding payment, candle, open interest reading and wallet of the last year (hl.* tables; GET /v1/query/schema lists them for free). Use it when no single endpoint answers the question: custom aggregations, joins, wallet cohorts or backtest datasets. Up to 30 s and 10,000 rows a query.","operationId":"postQuery","requestBody":{"content":{"application/json":{"example":{"max_rows":100,"sql":"SELECT market, round(sum(volume_usd)) AS usd FROM hl.market_hourly WHERE hour \u003e now() - INTERVAL 1 DAY GROUP BY market ORDER BY usd DESC LIMIT 5"},"schema":{"properties":{"max_rows":{"description":"Most rows to return, up to 10000","type":"integer"},"sql":{"description":"One SELECT over hl.* tables","type":"string"}},"required":["sql"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"example":{"columns":["market","usd"],"rows":[["BTC-PERP",1530000000]]},"schema":{"description":"Query result","properties":{"columns":{"description":"Column names","items":{"description":"Column","type":"string"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"rows":{"description":"Rows, each an array in column order","items":{"type":"array"},"type":"array"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"SQL over Hyperliquid data","tags":["hyperliquid","sql","onchain-sql","crypto","analytics"],"x-payment-info":{"price":{"amount":"0.01","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}},"/x402/v1/trades":{"get":{"description":"Every Hyperliquid trade (fill) for a market from Ironflow's own nodes: price, size, taker side, wallet, fee, realized PnL, direction (open or close, long or short), order and trade ids. Use it for tick-level crypto trade history, a wallet's fills, or large trades (min_size) in any window up to a year back. Covers perps, spot, HIP-3 and HIP-4 markets.","operationId":"getTrades","parameters":[{"description":"Only this wallet's fills (0x address)","in":"query","name":"address","required":false,"schema":{"type":"string"}},{"description":"next_cursor from the previous page","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Start: Unix ms, ISO 8601, or relative (-7d, now-24h); up to a year back","example":"-1d","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"Rows per page, 1 to 1000","example":"100","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Market: BTC, ETH-PERP, HYPE/USDC, xyz:NVDA (HIP-3) or a Hyperliquid coin name","example":"BTC","in":"query","name":"market","required":true,"schema":{"type":"string"}},{"description":"Smallest size in the base asset","example":"1","in":"query","name":"min_size","required":false,"schema":{"type":"string"}},{"description":"Time order (default desc)","example":"desc","in":"query","name":"order","required":false,"schema":{"enum":["asc","desc"],"type":"string"}},{"description":"End: Unix ms, ISO 8601, relative (-1h) or now (default)","example":"-23h","in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"address":"0x1234567890abcdef1234567890abcdef12345678","dir":"Close Short","fee":"-0.11","hash":"0xa76b60d4baf4e789a8e5044820e90402024b00ba55f8065b4b340c2779f8c174","market":"BTC-PERP","notional":"11113.02","price":"79629","realized_pnl":"17.33","side":"buy","size":"0.13956","tid":770596025780393,"timestamp":1793887172660}]},"schema":{"description":"Fills, newest first by default","properties":{"data":{"description":"One row per fill","items":{"description":"A fill","properties":{"address":{"description":"Wallet address","type":"string"},"dir":{"description":"Open Long, Close Long, Open Short, Close Short, Buy or Sell","type":"string"},"fee":{"description":"Fee paid (negative is a rebate)","type":"string"},"hash":{"description":"Transaction hash on Hyperliquid","type":"string"},"market":{"description":"Market symbol, e.g. BTC-PERP, HYPE/USDC, xyz:NVDA-PERP","type":"string"},"notional":{"description":"Price times size, USD","type":"string"},"oid":{"description":"Order id","type":"integer"},"price":{"description":"Fill price","type":"string"},"realized_pnl":{"description":"PnL realized by the fill, USD","type":"string"},"side":{"description":"Side of this wallet's fill","enum":["buy","sell"],"type":"string"},"size":{"description":"Size in the base asset","type":"string"},"tid":{"description":"Trade id","type":"integer"},"timestamp":{"description":"Unix time in milliseconds","type":"integer"}},"type":"object"},"type":"array"},"error":{"description":"Present instead of the data on a 4xx or 5xx answer.","properties":{"code":{"description":"Machine-readable code: INVALID_PARAMETER, HISTORY_OUT_OF_RANGE, QUERY_WINDOW_EXCEEDED, RATE_LIMIT_EXCEEDED, NOT_FOUND, INTERNAL_ERROR","type":"string"},"message":{"description":"What went wrong and how to fix the request","type":"string"},"upgrade":{"description":"On a limit error: the plan or paid call that lifts it","properties":{},"type":"object"}},"type":"object"},"pagination":{"description":"Paging: pass next_cursor as cursor= for the next page","properties":{"has_more":{"description":"Whether more rows match","type":"boolean"},"next_cursor":{"description":"Cursor for the next page, empty when there is none","type":"string"}},"type":"object"}},"type":"object"}}},"description":"The data, served at builder limits for this call"},"400":{"description":"Invalid parameter: the body has error.code and error.message; no payment is settled"},"402":{"description":"Payment Required: pay the x402 PAYMENT-REQUIRED terms and retry with PAYMENT-SIGNATURE"}},"security":[],"summary":"Hyperliquid trades (fills)","tags":["hyperliquid","trades","tick-data","crypto","perps"],"x-payment-info":{"price":{"amount":"0.002","currency":"USD","mode":"fixed"},"protocols":[{"x402":{"asset":"USDC","network":"eip155:8453"}}]}}}},"servers":[{"url":"https://api.ironflow.sh"}],"x-agentcash-guidance":{"llmsTxtUrl":"https://ironflow.sh/llms.txt"}}