Free, no signup, no key

Bitcoin Halving API

Give it a block height, get its halving era, block subsidy, and blocks until the next halving — as JSON. No API key, no account, no rate-limit tracking, no live node behind it. Just the same arithmetic from Chapter 5, served over HTTP.

Try it

GET https://why21million.com/api/halving/850000

Returns:

{ "height": 850000, "era": 5, "rewardBtc": 3.125, "blocksIntoEra": 10000, "blocksUntilNextHalving": 200000, "nextHalvingBlock": 1050000, "source": "https://why21million.com/book/halving-schedule/" }

Swap 850000 for a non-negative block height integer. The metadata route and the calculation route are distinct:

  • GET /api/halving returns 200 with API metadata, usage and field descriptions, not a height calculation. Open the metadata GET example.
  • GET /api/halving/850000 returns 200 with the height calculation shown above. Open the calculation GET example.
  • GET /api/halving/invalid returns 400 with the JSON error below. Omitting the height by requesting /api/halving selects metadata; it is not this invalid-height error.
{ "error": "height must be a non-negative integer", "example": "/api/halving/850000" }

At a halving boundary

Adjacent heights before and at the 840000 boundary
Field839999840000
era45
rewardBtc6.253.125
blocksIntoEra2099990
blocksUntilNextHalving1210000
nextHalvingBlock8400001050000

The boundary block at height 840000 already receives the new subsidy of 3.125 BTC. Its blocksIntoEra resets to zero, but the countdown points to the following boundary at 1050000: blocksUntilNextHalving returns 210000, rather than returning zero. At height 839999, there is still one block until the boundary.

Subsidy precision limitation

The current rewardBtc implementation uses halving division (50 / 2 ** (era - 1)), not integer-satoshi truncation. It can return fractional satoshis and is not consensus-exact for later eras. Do not use this field as an exact consensus subsidy.

At height 6720000 (era 33), the API returns 1.1641532182693481e-8 BTC, while integer-satoshi arithmetic gives 1 satoshi = 0.00000001 BTC. For integer-satoshi reproduction, see the Bitcoin subsidy schedule and reproducible calculation. This documentation caveat does not change the API arithmetic.

After the subsidy reaches zero

At height 6930000, rewardBtc reaches zero. The fields nextHalvingBlock and blocksUntilNextHalving continue to identify 210000-block arithmetic boundaries, not further positive subsidy reductions. A nonzero countdown does not mean new bitcoin will be issued.

GET /api/halving/6930000 returns 200 with the zero-subsidy calculation below. Open the zero-subsidy GET example.

{ "height": 6930000, "era": 34, "rewardBtc": 0, "blocksIntoEra": 0, "blocksUntilNextHalving": 210000, "nextHalvingBlock": 7140000, "source": "https://why21million.com/book/halving-schedule/" }

Fields

FieldMeaning
heightThe block height you requested, echoed back.
era1-indexed halving era that height belongs to.
rewardBtcHalving-division subsidy in BTC during that era; not consensus-exact for later eras because it omits integer-satoshi truncation (see the precision limitation above) — 0 once issuance ends (era > 33, around the year 2140).
blocksIntoEraHow many blocks into the era this height is (0-indexed).
blocksUntilNextHalvingBlocks remaining until the next 210000-block arithmetic boundary, counted from this height. After the subsidy reaches zero, this is not a countdown to another positive subsidy reduction.
nextHalvingBlockThe height of the next 210000-block arithmetic boundary. After the subsidy reaches zero, this does not mark another positive subsidy reduction.

What this is not

This isn't a blockchain explorer or a live node — it doesn't know the current block height, and it never phones out to check. It calculates fixed 210000-block era boundaries, but its rewardBtc halving division is not an exact reproduction of the protocol's integer-satoshi subsidy schedule. For schedule background, see Chapter 1 and Chapter 5. If you need the current tip height, pair this with any block explorer's API and feed the result in here.

Details for integrators

  • CORS: Access-Control-Allow-Origin: * — call it directly from a browser, no proxy needed.
  • Caching: responses are cacheable for 24 hours (Cache-Control: public, max-age=86400) — the answer for a given height never changes, so cache it aggressively on your end too.
  • No rate limits enforced as of this writing, but be reasonable — this runs on Cloudflare Pages Functions, not a dedicated backend.
  • Uptime: best-effort, no SLA. It's a free static-adjacent endpoint on a hobby project, not a paid service.
Prefer to run the arithmetic yourself instead of calling out over the network? The same logic is a small, tested, MIT-licensed JS library: halving-math on GitHub.