Try it
Returns:
Swap 850000 for a non-negative block height integer. The metadata route and the calculation route are distinct:
GET /api/halvingreturns200with API metadata, usage and field descriptions, not a height calculation. Open the metadata GET example.GET /api/halving/850000returns200with the height calculation shown above. Open the calculation GET example.GET /api/halving/invalidreturns400with the JSON error below. Omitting the height by requesting/api/halvingselects metadata; it is not this invalid-height error.
At a halving boundary
| Field | 839999 | 840000 |
|---|---|---|
| era | 4 | 5 |
| rewardBtc | 6.25 | 3.125 |
| blocksIntoEra | 209999 | 0 |
| blocksUntilNextHalving | 1 | 210000 |
| nextHalvingBlock | 840000 | 1050000 |
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.
Fields
| Field | Meaning |
|---|---|
| height | The block height you requested, echoed back. |
| era | 1-indexed halving era that height belongs to. |
| rewardBtc | Halving-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). |
| blocksIntoEra | How many blocks into the era this height is (0-indexed). |
| blocksUntilNextHalving | Blocks 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. |
| nextHalvingBlock | The 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.