A deterministic, transparent framework for Bitcoin portfolio allocation.
Given just a date and today's BTC price, this model tells you what percentage of a portfolio "should" be in Bitcoin. No database. No historical feed. No machine learning. Just a power law, Kleiber's Law, and a heartbeat.
This repo is the canonical, app-independent home of the research, the math, the code, and the rationale. It is designed to be adopted by any application, bot, or research environment.
Three references, calculated deterministically from the date alone:
FLOOR = 10^(-17) × days_since_genesis^5.73 ← Power-law equilibrium (~40%/yr growth)
CEILING = FLOOR × Spike(cycle) ← Speculative peak envelope (Kleiber decay)
MODEL = FLOOR + (CEILING - FLOOR) × Heartbeat ← Where price "should" be in this cycle
Price lives somewhere between floor and ceiling. The position in band plus the phase of the halving cycle determine your allocation:
- Near the floor → buy aggressively
- Near the ceiling → protect capital
- In the post-peak cooldown zone → don't catch falling knives
Historical finding (2014–2026 backtest): a 22% rebalance threshold converts this signal into 2.55× vs HODL with just ~8 trades per year.
Loose rebalancing is the profit driver. ~8 trades a year beats HODL. 1,000 trades a year loses to HODL.
The strategy works because it trades rarely, absorbs big chunks of value during each cycle, and leaves the position alone in between. Every tighter threshold that has been backtested — 1%, 5%, 10%, 15% — produces worse returns, because fees, slippage, and tax drag eat the edge faster than noise-chasing can generate it. See docs/REBALANCER.md.
See docs/MODEL.md for the full math and docs/THESIS.md for why this is worth doing.
The static image above is generated by scripts/generate_chart.py. For a live, interactive version open chart/index.html in any browser — it fetches current BTC history, plots floor/ceiling/fair-value against actual price, marks halvings, and shows today's allocation signal.
A narrower ±5-year zoom is available as chart/model_zoom.png.
from datetime import datetime
from power_law import get_daily_signal
signal = get_daily_signal(datetime.now(), btc_price=95_000)
print(signal["allocation_pct"]) # e.g. 42.0
print(signal["tagline"])
# Cycle 5 | 28% through cycle | Pre Peak Build Up | Price at 35% of range
# (undervalued) | Favorable accumulation: 62% BTCfrom power_law.rebalancer import Rebalancer, RebalancerConfig, PaperVenue
venue = PaperVenue(btc=0.0, usd=10_000, _price=95_000)
r = Rebalancer(venue, RebalancerConfig(threshold_pct=0.22))
r.tick() # call on a scheduleRun the full example:
pip install -r requirements.txt
python examples/quickstart.pypower-law-allocation/
├── README.md ← You are here
├── LICENSE ← MIT
├── requirements.txt ← numpy, pandas
│
├── docs/
│ ├── THESIS.md ← Why this model — the investing philosophy
│ ├── MODEL.md ← Full math: floor, ceiling, heartbeat, allocation
│ ├── REBALANCER.md ← Rebalancing policy, threshold research, tradeoffs
│ ├── VENUES.md ← Where to execute: why we like SaucerSwap, and the LP angle
│ ├── BACKTEST.md ← Results: 2014–2026, fee sensitivity, walk-forward
│ └── CONSTANTS.md ← The locked calibration — what each constant means
│
├── src/power_law/
│ ├── model.py ← THE CORE MODEL — 400 lines, stateless, no I/O
│ └── rebalancer.py ← Venue-agnostic reference rebalancer + paper-trade venue
│
├── examples/
│ └── quickstart.py ← End-to-end example (signal + projection + paper trade)
│
├── chart/
│ └── index.html ← Interactive Plotly chart (open in any browser)
│
└── papers/
├── thermal_stability.md ← The formal working paper (v2.0, peer-review quality)
├── heartbeat_v3_paper.md ← Earlier internal paper (V3 development)
└── heartbeat_v3.2_paper.md ← Earlier internal paper (V3.2 refinement)
from power_law import (
get_daily_signal, # full signal dict for (date, price)
allocation_signal, # just the 0.0–1.0 allocation number
floor_price, # power-law floor at a date
ceiling_price, # cycle ceiling at a date
model_price, # fair-value midpoint
position_score, # 0 (floor) → 1 (ceiling) for a given price
get_future_projections, # 1M–36M forward view
backtest, # run the strategy on a DataFrame of prices
)A single signal call returns everything a bot or UI needs:
{
"date": "2026-04-17",
"price": 95000,
"allocation_pct": 62.0,
"floor": 48200,
"ceiling": 285000,
"model_price": 91400,
"position_in_band_pct": 35,
"cycle": 5,
"cycle_progress_pct": 28,
"phase": "pre_peak_build_up",
"valuation": "undervalued",
"stance": "accumulate",
"tagline": "Cycle 5 | 28% through cycle | ..."
}- Deterministic. Same date + price → same signal. No random seeds, no drift.
- Stateless. No databases, no warm-up period. Works in a Lambda, a notebook, a phone.
- Transparent. All constants and equations are public and documented.
- Venue-agnostic. The model emits a target %. The rebalancer is an interface. Bind it to whatever execution venue you like.
- Locked calibration. The five constants at the heart of the model are fixed. Tuning them defeats the point.
This is a worldview, not financial advice. Nothing in this repo is a recommendation to buy, sell, or hold any asset. What follows is a description of what the model is designed for — you decide whether that design matches your own view of the world.
The model is built for a wallet that holds both a USD-equivalent stablecoin and BTC, and lets the power-law signal decide the mix. You contribute cash on whatever cadence works for you. The model sets the target allocation. The rebalancer executes. You never touch the trade button.
In that usage pattern, the wallet behaves like a long-duration savings vehicle — the kind of thing a bank deposit account used to be, before real yields went negative. But with three deliberate differences:
- The store of value is BTC, not cash. The worldview behind the model is that fiat currencies debase over long horizons and Bitcoin, for now, does not. If you don't share that view, the model is not for you.
- The allocation is dynamic, never 100%. You don't sit fully in BTC and ride out 80% drawdowns. When the model reads "euphoria," it cashes you out into stablecoin automatically. When it reads "deep value," it puts you back in. You get cycle-aware exposure without timing anything.
- Volatility is dampened by design. A pure BTC holding has 80%+ historical max drawdowns. This strategy, in backtest, roughly halves that — because the allocation shrinks before the crash and grows before the recovery.
- The urge to time the market. The model runs on a schedule, not on your mood. The answer to "should I be buying right now?" is whatever the signal says, and you find out on the next tick.
- The fear of the exit. You don't need to pick a top. The model trims on the way up and fully de-risks at the ceiling. If you hate missing the peak, this strategy will sometimes frustrate you. If you hate round-tripping gains, it won't.
- The fear of the entry. You don't need to pick a bottom. The model accumulates mechanically as price approaches the floor, and the phase penalty keeps you out during the post-peak washout.
- Guarantee a return. There are no return guarantees in crypto, or anywhere else.
- Protect against Bitcoin failing. If the underlying thesis is wrong and BTC goes to zero, the wallet goes with it.
- Replace professional advice. If you are deciding what to do with real money, talk to a real advisor. This repo is a research and information system, not a fiduciary.
The pattern this model supports is simple:
Hold a balanced USD/BTC wallet. Contribute to it when you have savings. Let the model manage the split based on where Bitcoin sits relative to its long-run structure. Withdraw when you need the money. Don't check it more than once a week.
That is the intended shape of the thing. Whether it makes sense for any given person depends on their views on Bitcoin, their tax jurisdiction, their time horizon, and their tolerance for a framework that will eventually be wrong (see THESIS.md on expected lifespan).
None of those are questions this repo can answer for you.
The power-law framework assumes Bitcoin is still in its volatile, cycle- dominated youth. It will not last forever.
Every mature asset class — gold, equities, sovereign debt — eventually trades in an exponential growth regime, not a power-law one. Volatility compresses. Cycles smooth out. Price becomes a function of money supply and a modest real return.
We expect Bitcoin to make the same transition once it has absorbed a critical mass of global wealth — acting as a slow anchoring system that either recapitalises the USD or replaces it as a reserve. At that point, the four-year halving rhythm stops mattering, the ceiling stops constraining, and a constant 80–100% allocation becomes the right answer.
Our horizon for this framework:
- 5 years minimum — through ~2030. Cycle 5 should behave like prior cycles, with visibly compressed amplitude consistent with Kleiber decay.
- 5–10 years — cycle amplitude keeps compressing. The model still wins, by a smaller margin.
- Beyond 10 years — probabilistically the cycle structure breaks. A successor framework retires this one.
See docs/THESIS.md for the full expected-lifespan and endgame analysis.
Research framework, v1.0. Public under MIT.
This is not financial advice. The model makes a claim about Bitcoin's long-run structure; that claim may be wrong. See docs/THESIS.md for the full list of failure modes.
— Chris Imgraben