funding-forecaster: Full Guide to the Free Polymarket Perps Funding CLI

Ais Fang· tools · Updated October 2026

The funding-forecaster answers one question before you open a perps position: what will holding this cost me? This is the author’s full guide — every output line decoded, the assumptions stated honestly, and the automation pattern for positions you already hold. (The quick intro lives in the tools overview.)

What does funding-forecaster actually compute?

Three numbers from the live book. Premium estimate: the perp midpoint minus the underlying outcome price — the market’s crowding measure, positive when perp trades above fair value. Hourly funding drag: the premium converted to a rate at your leverage — the |premium|, with the sign deciding whether you pay or receive, and leverage multiplying it against your margin (the protocol formula behind this is in funding mechanics). Projection: drag × hours × margin — the total bill your hold will likely produce. The math mirrors the protocol’s structure (5-second book-walk samples, hourly windows, the ±4% cap) at snapshot fidelity — it’s an estimate from now, not a prophecy (limits below).

Reading the output, line by line

Market       : Will the Fed cut rates in December?
Premium est. : +0.420%  (perp vs underlying mid)
Funding rate : 0.420% per hour (cap 4%)
Side         : LONG @ 5x → you pay
Drag         : 2.10% of margin/hour
Projection   : 50.40% over 24h ≈ $252.00 on $500 margin

Premium est. — positive means longs pay, shorts receive. The bigger the magnitude, the more crowded one side is (see the two reads).
Funding rate — the snapshot hourly rate; the cap line reminds you where saturation sits.
Side → you pay/receive — the sign decision for your direction.
Drag — your leverage-adjusted cost per hour as a % of margin. Anything above ~0.5%/hour deserves a hard second look at 5x+.
Projection — the number to compare against your thesis’s expected profit. If the projection eats your expected edge, the trade is a donation — see the cost-stack context.

The assumptions (what it can’t know)

Static premium. Live premiums move — news windows can hit the cap; a 24h projection at snapshot premium is a central estimate, not a bound (trend-reading in funding data tightens it).
Thin-book noise. Sub-tick midpoints on illiquid books produce noisy premiums — treat tiny outputs as ranges.
No exit modeling. It projects the hold; your exit timing changes reality (closing between windows, flipping sides — see shorting mechanics).
The cap interaction with liquidation. Drag erodes the margin buffer that liquidation math depends on — run both numbers for held positions.

Automating it for held positions

The tool is read-only and standard-library — a cron line per morning:

0 8 * * * cd ~/funding-forecaster && python3 funding_forecaster.py \
  --market your-market --side long --leverage 5 --hours 24 \
  --margin 500 >> ~/funding_log.txt

A daily log of projections becomes a trend record (does the drag grow or decay?) — the cheap version of the funding-history reads. Pair it with the weekly review discipline: funding is a cost line worth its own column.

FAQ

Is funding-forecaster free? Yes — MIT licensed, standard library only, no keys, no sign-in. Clone, run, read: see the repo for install.

How accurate is the funding projection? It’s a snapshot-fidelity estimate of a moving target — accurate for calm books, conservative during saturation (the cap truncates spikes the snapshot may miss). Re-run daily on held positions; the mechanics guide explains what the protocol actually charges.

Does the tool need my API keys or wallet? No — it reads public market data only. No keys, no wallet, no sign-in; nothing to leak.

Can it predict funding flips? It shows the current sign and magnitude; flips follow crowd rotations (see odds and flows) — daily cron logs give you the trend, which is the practical flip signal.

What’s the difference between this and the in-app funding display? The app shows protocol state; the forecaster converts it to your decision numbers — drag at your leverage and margin, projected over your horizon. The decision framing is in the cost guide.

Educational tool guide, not financial advice. Not affiliated with Polymarket. Last updated October 2026.