Raviole Labs
Raviole Labs

Hyperliquid funding rate API: funding, OI, predictions

Pull current, historical and predicted funding plus open interest from the Hyperliquid API, with the gotchas on sign and sampling that cost us a day.

hyperliquidapipredmcptradingfunding

If you want funding data out of Hyperliquid, the first thing to know is that there is no dedicated “funding endpoint” with a clean REST path. Everything runs through the info API, a single POST to https://api.hyperliquid.xyz/info where the type field in the JSON body decides what you get back. Learning the hyperliquid funding rate api means learning which type returns funding, how coins are encoded, and where the sign conventions bite. This post walks the shapes, pairs funding with open interest, and shows where a cross-venue read gets interesting.

Which endpoint returns funding

One URL, many payloads. You POST JSON and switch on type. For a snapshot of every perp including its current funding, use:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"metaAndAssetCtxs"}'

The response is a two-element array. Element 0 is meta with the universe (the ordered list of coins and their szDecimals, maxLeverage). Element 1 is the array of asset contexts, index-aligned to universe. Each context carries funding, openInterest, markPx, oraclePx, premium and dayNtlVlm. The alignment matters: there is no coin field inside the context, so you zip universe[i].name with assetCtxs[i]. Get the ordering wrong and you attribute BTC funding to the wrong asset silently.

Coin encoding is simpler than people expect, and that is exactly why it bites. Every entry of the perp universe carries a plain name string (BTC, ETH, SOL); there is nothing to decode. The index is the position in the array, and that position is the only thing tying a coin to its context, so it is the thing you must not lose when you filter or sort. Keep the original index alongside the row, or map before you filter. Spot is a separate universe with @ indices (@1, @107), reached with spotMeta, and it has no funding at all. For funding you stay in the perp universe and you zip by position.

Current vs historical vs predicted funding

The metaAndAssetCtxs call gives you current funding, the rate applied at the next hourly settlement. For history, switch to fundingHistory, which is per coin and time-bounded:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"fundingHistory","coin":"BTC","startTime":1722470400000}'

You get an array of {coin, fundingRate, premium, time}, one row per hourly settlement. Timestamps are epoch milliseconds. Note that fundingHistory is the realized series (what was actually charged), while the funding field in the asset context is the live estimate for the upcoming interval.

Predicted funding is a third shape, predictedFundings, and this is the one most people miss. It returns predicted rates across venues so you can compare Hyperliquid against Binance, Bybit and others for the same coin:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"predictedFundings"}'

The response is not an object keyed by coin. It is an array of pairs, and each pair holds a second array of pairs:

[coin, [[venue, {fundingRate, nextFundingTime, fundingIntervalHours}], ...]]

So the first element looks like ["BTC", [["HlPerp", {...}], ["BinPerp", {...}], ["BybitPerp", null]]]. Three things to handle. The venue payload can be null when that venue does not list the coin, so filter before you touch any field. fundingRate is a string here too. And fundingIntervalHours is optional: when it is absent you have to assume an interval, and that assumption is where cross-venue comparisons quietly go wrong. Hyperliquid settles hourly, most CEXs settle every eight hours, so annualize each venue with its own interval before you subtract. Comparing raw numbers without normalizing to a common period gives you an 8x error in either direction.

Pairing funding with open interest for signal

Funding on its own is noise. Funding times open interest is a positioning read. The openInterest field sits right there in the same asset context, denominated in the coin (multiply by markPx for notional). The pattern worth watching: funding grinding higher while OI expands means crowded longs paying to stay in, a setup that mean-reverts hard on any wick. Funding high while OI falls means the crowd is already unwinding, a weaker signal.

So the minimal loop is one metaAndAssetCtxs call, zip universe to contexts, compute funding * openInterest * markPx per coin, and rank. One trap silently ruins that: every numeric field in the info API comes back as a string ("0.0000125", not 0.0000125). Multiplication coerces, so funding * openInterest happens to give the right answer, but a + concatenates instead of adding, and any comparison or sort goes lexicographic, where "1000" < "9.5" is true. Parse at the boundary, once:

const [meta, assetCtxs] = await post({ type: 'metaAndAssetCtxs' });

const rows = meta.universe.map((asset, i) => {
  const ctx = assetCtxs[i];                 // index-aligned, no coin field inside
  const funding = parseFloat(ctx.funding);       // "0.0000125" -> 0.0000125
  const oi = parseFloat(ctx.openInterest);       // denominated in the coin
  const markPx = parseFloat(ctx.markPx);
  return {
    coin: asset.name,
    funding,
    oiUsd: oi * markPx,
    pressure: funding * oi * markPx,             // hourly $ paid across the book
  };
});

rows.sort((a, b) => Math.abs(b.pressure) - Math.abs(a.pressure));

Same rule for fundingHistory: fundingRate is a string there as well. Sort on the absolute value, otherwise deeply negative funding (shorts paying) falls off the bottom of the leaderboard, and that is often the side worth looking at. What you get is a ranking of where leverage is both expensive and stacked. The cross-venue divergence thesis builds directly on this: the strongest reads come when Hyperliquid positioning disagrees with everyone else.

Cross-venue funding: perp vs prediction market

Here is where it gets more interesting than a single-venue funding scan. A perp funding rate is a continuous cost of leverage. A prediction market price is an implied probability. When the same underlying event trades on both, the two encode the same expectation in different units, and they drift apart. A Hyperliquid HIP-4 outcome market and a Polymarket market on the same question can imply different odds while perp funding tells you which side is paying to hold conviction.

Reading HIP-4 outcome markets is its own path (the builder-deployed data plane, read-only), covered in HIP-4 read paths. Stitching perp funding, HIP-4 odds and Polymarket into one comparable frame is the whole point of the Polymarket + Hyperliquid MCP work: same expectation, three venues, one diff.

Gotchas: sampling windows, sign conventions, call shape

Three things break integrations:

  • Sampling windows. Hyperliquid charges funding every hour, at one eighth of the equivalent eight-hour rate, so the economics line up with a CEX cycle while the settlement lands eight times as often. Practical consequence: if you sample metaAndAssetCtxs on a five-minute cron and sum the funding field, you overcount by 12x. funding is the rate for the interval, not a per-second accrual. Use fundingHistory for realized sums, one row per hour.
  • Sign convention. Positive funding means longs pay shorts. The funding field is the hourly rate as a decimal (0.0000125 is 0.00125 percent per hour). Because of the hourly cadence above, do not read it as annualized and do not read it as a per-eight-hours CEX number. Multiply by 24 for daily, by 24 * 365 for a rough annual.
  • One call, not N. Never loop fundingHistory per coin to build a leaderboard. metaAndAssetCtxs returns every perp in a single response, so poll that once and fan out locally. Keep fundingHistory for the coins you genuinely need history on, cap the fan-out (our own outlier scan restricts the backfill to the top 30 coins by OI notional and runs them through Promise.allSettled, so one bad coin does not sink the batch), and space backfills instead of firing them all at once.

Skip the glue: the same data through one MCP tool

All of the above is a few hundred lines of client code: the POST wrapper, the universe-to-context zip, the interval normalization, the cross-venue join. We already wrote it. PredMCP exposes it as MCP tools your agent calls directly: get_funding_rates and get_top_funding_rates for the ranked leaderboard, get_cross_venue_funding for the Hyperliquid vs Binance vs Bybit predicted-funding spread, already annualized per venue interval, get_oi_history and get_oi_divergence for the positioning side. 47 tools across Polymarket and Hyperliquid perps and HIP-4, cross-venue signals included.

It is free in early access: 100 calls per day per key, no card. The core is MIT, so if you want to see exactly how the universe-to-context zip and the string parsing are done, that code is readable. The signal layer built on top of it is not published. Point your agent at the server and skip the boilerplate, or lift the parsing logic and build your own. Both are fine.