On Hyperliquid, funding is the periodic transfer between longs and shorts that pulls a perpetual's mark toward its underlying index, and it accrues on an hourly schedule with the rate expressed per hour. The /info endpoint exposes two distinct objects: predictedFundings, a forward-looking estimate for each venue/asset pair that changes during the interval, and fundingHistory, the realised per-hour rates already accrued over a bounded window. Neither is the user's actual payment; you compute that from position notional, the realised rate, and hours held, then reconcile it against account value history. This guide explains the mechanism, the read surfaces, the arithmetic, and the common bugs such as annualising with an eight-hour convention or comparing a HIP-3 venue quote against a main-perp number.
Why a perpetual needs funding at all
A perpetual future has no expiry, so nothing forces its price back toward the underlying spot or index the way settlement does on a dated contract. Funding replaces that missing settlement: it is a recurring cash transfer between the long and short sides of the book that creates an incentive to hold the side trading at a discount and to reduce the side trading at a premium. When the perp trades above the index, longs pay shorts; when it trades below, shorts pay longs. The mechanism is described on the official Hyperliquid Funding documentation, which is the authoritative primary source for the schedule and parameters.
The practical consequence for anyone building a dashboard or bot is that funding is not a fee the exchange charges you in isolation. It is a peer-to-peer transfer whose sign depends on your side and whose magnitude depends on the perp-versus-index spread. If you are long and the rate is positive, your position bleeds funding; if you are short, you receive it. Getting the sign convention wrong is the single most common source of incorrect PnL attribution.
- Perpetual = no expiry, so funding substitutes for settlement pressure.
- Positive rate: longs pay shorts. Negative rate: shorts pay longs.
- The rate responds to the perp-versus-oracle spread, not to spot trading volume.
The hourly accrual convention and why 'multiply by three' is a bug
On Hyperliquid, funding accrues on an hourly schedule and the published rate is expressed per hour. Many older venues quote an eight-hour rate, so a developer who carries over a habit of multiplying a quoted rate by three to get a daily figure will overstate Hyperliquid funding by a factor of three. The correct daily figure is the hourly rate multiplied by 24, and the correct annualised figure depends on the compounding assumption you state explicitly. The exact clamping bounds, the interval, and the precision of the returned rate are documented values; treat them as 'documented / varies' and confirm them against the current docs rather than hard-coding a constant into your bot.
The payment for a position is straightforward once the interval is right: payment = position notional x funding rate x hours held, with the sign taken from the perspective of the position. A long position with a positive rate has a negative payment (it pays); a short position with a positive rate has a positive payment (it receives). Because the rate is per hour, a position held for a fraction of an hour is not charged a full hour under the documented schedule, but you should verify the exact accrual boundary against the docs before relying on sub-hour precision.
- Hyperliquid rate is per hour; do not reuse an eight-hour convention.
- Daily = hourly x 24. Annualised requires a stated compounding assumption.
- Payment = notional x rate x hours, signed from the position's perspective.
predictedFundings: a forward-looking estimate, not a payment
predictedFundings returns the current predicted funding for each venue/asset pair. It is a forward-looking estimate that changes during the interval, and it is the correct input for a decision: should I open, hold, or close a position given where funding is heading? It is not the rate you will actually pay, because the realised rate is set at accrual time. Treat the predicted value as a signal, not as an accounting figure.
The venue split matters here. Hyperliquid supports multiple venues, including HIP-3 dexes and perp-and-spot pairs, and predictedFundings returns entries per venue/asset pair. Comparing a HIP-3 dex quote against a main-perp number is a category error that will silently corrupt an arbitrage screen. Always key your lookup by both venue and asset, and confirm the request and response shape against the official Hyperliquid info endpoint reference before you parse it.
- predictedFundings = forward-looking estimate, changes during the interval.
- Use it to decide, not to account.
- Key by venue AND asset; never compare across venues blindly.
fundingHistory: realised per-hour rates over a bounded window
fundingHistory returns the realised per-hour rates already accrued over a bounded window. This is the input for accounting, PnL attribution, and backtests, because these rates actually happened. The window is bounded, so assuming it is unbounded is a real failure mode: if you request more history than the endpoint returns, you will silently get a truncated series and your backtest will start at the wrong place. The length and time window behave as documented; confirm the current bounds rather than assuming a fixed count.
A funding snapshot and a funding payment are different objects. fundingHistory gives you rates; it does not give you the dollar amount your account paid. To get the payment you must combine the realised rate series with your position notional and holding period. This distinction is the core of reading funding correctly, and it is why a dashboard that plots fundingHistory alone can look correct while reporting the wrong PnL.
- fundingHistory = realised rates, bounded window, for accounting and backtests.
- A rate is not a payment; you must combine it with notional and hours.
- Do not assume the window is unbounded.
Computing realised funding from perp account state
To compute an account's realised funding, read the perp account state via clearinghouseState for the position, its entry notional, and its margin, then combine that with the realised hourly rate series from fundingHistory. The position notional times each realised hourly rate, summed over the hours held, gives the funding component of PnL. Reconcile the result against the account's own value history to catch sign errors: if your computed funding moves account value in the opposite direction to the observed change, your sign convention is inverted.
This is a verification method, not a measured result. Fill in the results table below with your own endpoint and account so the numbers are reproducible by you. Our guide to Hyperliquid historical and market data APIs covers the retrieval side of these series; this page covers the mechanism and the arithmetic.
- Read clearinghouseState for position, entry notional, margin.
- Combine with the realised hourly rate series from fundingHistory.
- Reconcile against account value history to catch sign errors.
Runnable Node script: predicted rate, realised series, annualised figure, payment
The script below fetches predictedFundings and fundingHistory for one coin, prints the current predicted hourly rate, the last N realised rates, an annualised figure with the compounding assumption stated explicitly, and the computed funding payment for a given position size over a given number of hours. Replace the endpoint with your own provider URL and adjust the coin and position parameters. It uses only the native /info API and Node's built-in fetch.
Note that the annualised figure here uses simple multiplication by 24 x 365 with no compounding, and the script prints that assumption so you cannot mistake it for a compounded yield. If you prefer compounding, state it and change the formula; the point is that the assumption is explicit, not hidden.
// funding.js — Node 18+ (built-in fetch)
const ENDPOINT = process.env.HL_INFO_URL || 'https://api.hyperliquid.xyz/info';
const COIN = process.env.COIN || 'BTC';
const POSITION_NOTIONAL = Number(process.env.NOTIONAL || 10000); // USD
const HOURS_HELD = Number(process.env.HOURS || 24);
const LAST_N = Number(process.env.LAST_N || 24);
async function post(body) {
const res = await fetch(ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
return res.json();
}
function annualiseSimple(hourlyRate) {
// Simple (non-compounded) annualisation: hourly * 24 * 365
return hourlyRate * 24 * 365;
}
(async () => {
// 1) Current predicted funding for each venue/asset pair
const predicted = await post({ type: 'predictedFundings' });
const match = (predicted || []).find(
(row) => JSON.stringify(row).includes(COIN)
);
console.log('predictedFundings match:', JSON.stringify(match, null, 2));
// 2) Realised per-hour rates over a bounded window
const history = await post({
type: 'fundingHistory',
coin: COIN,
startTime: Date.now() - 1000 * 60 * 60 * 24 * 7,
});
const rates = (history || []).map((r) => Number(r.fundingRate));
const lastN = rates.slice(-LAST_N);
console.log(`last ${lastN.length} realised hourly rates:`, lastN);
const latestRealised = lastN[lastN.length - 1] ?? 0;
console.log('latest realised hourly rate:', latestRealised);
console.log(
'annualised (simple, x24x365, no compounding):',
annualiseSimple(latestRealised)
);
// 3) Funding payment for a position over N hours
// payment = notional * rate * hours, signed from the position's perspective.
// Positive rate => longs pay shorts. Flip sign for a short position.
const isLong = true;
const sign = isLong ? -1 : 1;
const payment = sign * POSITION_NOTIONAL * latestRealised * HOURS_HELD;
console.log(
`funding payment for ${isLong ? 'long' : 'short'} ` +
`${POSITION_NOTIONAL} USD over ${HOURS_HELD}h: ${payment.toFixed(4)} USD`
);
})().catch((e) => {
console.error('funding script failed:', e.message);
process.exit(1);
});Results table: measure funding against your own endpoint
Use the table below to record what your endpoint actually returns. Do not treat any row as an OnFinality-specific measurement; these are fields for you to fill from your own provider and account. Run the script above, then reconcile the computed payment against the account value change you observe over the same window.
If the computed payment and the observed account value change disagree in sign, your position side or rate sign is inverted. If they disagree in magnitude, check whether you used the realised rate or the predicted rate, and whether your hours-held figure matches the accrual boundary.
- Coin / venue: the exact asset and venue pair you queried.
- Predicted hourly rate: value from predictedFundings at query time.
- Latest realised hourly rate: last entry from fundingHistory.
- Annualised (simple, x24x365): stated assumption, no compounding.
- Position notional and hours held: your inputs.
- Computed funding payment: notional x rate x hours, signed.
- Observed account value change: from your own value history.
- Sign match? Magnitude match? Note any discrepancy.
Common failures when reading Hyperliquid funding
The failures below are the ones that most often corrupt a funding dashboard or arbitrage bot. Each is a mechanism misunderstanding rather than an API bug, which is why they survive code review. For request-level problems such as malformed bodies or rejected orders, see Hyperliquid API error handling and order rejections.
Reading predicted as realised is the most damaging: it makes your accounting depend on a value that changes during the interval. Annualising with the wrong interval overstates or understates by a fixed factor. Assuming the funding window is unbounded truncates backtests silently. Ignoring the venue split corrupts cross-venue comparisons. Mixing unrealised PnL with funding conflates two different PnL components. Assuming precision or rounding the API does not promise produces drift that compounds over many hours.
- Reading predicted as realised.
- Annualising with an eight-hour convention instead of hourly.
- Assuming the funding window is unbounded.
- Ignoring the venue split (HIP-3 dex vs main perp).
- Mixing unrealised PnL with funding.
- Assuming precision or rounding the API does not promise.
Troubleshooting checklist
Work through this checklist in order when a funding figure looks wrong. It moves from the cheapest check (sign) to the most expensive (reconciliation against account history). If you are debugging connectivity or subscription behaviour rather than arithmetic, our Hyperliquid WebSocket subscriptions guide covers the streaming side.
Keep the checklist with your code so the next person who touches the funding module has a defined path. Most funding bugs are caught at step one or two.
- Confirm the rate is per hour, not per eight hours.
- Confirm you used realised (fundingHistory), not predicted, for accounting.
- Confirm the sign matches your position side.
- Confirm the venue/asset key matches the position's actual venue.
- Confirm the history window was not truncated.
- Reconcile computed payment against account value history.
- Confirm no hard-coded clamping or precision constant has drifted from the docs.
Limitations and assumptions
This guide describes documented mechanism and API shape; it does not assert any OnFinality-specific rate, latency, or limit. All caps, windows, and precision are 'documented / varies' and should be confirmed against the current Hyperliquid docs and your provider's documentation. The annualised figure in the script uses simple multiplication with no compounding, and that assumption is printed rather than hidden.
The reconciliation method assumes you can read your own account value history over the same window as the funding series. If your value history granularity is coarser than the hourly accrual, expect small residuals and treat them as measurement noise rather than as a bug. For provider selection and endpoint behaviour, see Hyperliquid RPC endpoints and providers.
- No OnFinality-specific rate, latency, or limit is asserted.
- Caps, windows, precision: documented / varies.
- Annualisation assumption is simple, non-compounded, and stated.
- Reconciliation residuals may reflect value-history granularity.
Next steps
Start by running the script against your own endpoint and filling in the results table. Then wire the realised series into your PnL attribution so funding is a first-class component rather than a residual. If you are building an arbitrage screen, key every comparison by venue and asset before you rank opportunities.
For the retrieval side of trades, OHLCV, and funding history, read Hyperliquid historical and market data APIs. For the oracle price that anchors the premium, read Hyperliquid oracle prices and the builder auction. To choose an endpoint, start from Hyperliquid RPC endpoints and providers, and for plans and throughput see RPC pricing and the API service. Browse more mechanism guides on the OnFinality Learn hub and the Hyperliquid network page.
- Run the script, fill the results table, reconcile against account history.
- Make funding a first-class PnL component.
- Key arbitrage comparisons by venue and asset.
- Confirm all caps and windows against current docs before hard-coding.
Ethereum
Solana
Polygon
Base
Arbitrum
BNB Chain
Polkadot
Optimism
