{"openapi":"3.1.0","info":{"title":"Bitcoin Halving API","version":"1.0.0","description":"Live Bitcoin halving countdown and supply schedule as an API, computed from the on-chain block height (mempool.space). Bitcoin's block subsidy halves every 210,000 blocks (~four years); this returns the current subsidy in BTC, the halving epoch, the next halving's block height, how many blocks and roughly how long remain (using the network's recent average block time), and the estimated date. It also computes the circulating supply mined to date from the issuance schedule, the percent of the 21-million cap already mined, the daily and annual new issuance and the inflation rate, plus the full halving schedule. The Bitcoin issuance-and-halving layer for crypto, dashboard and countdown apps. Live, no key, no cache. Distinct from fee and mempool Bitcoin APIs — this is the supply and halving schedule.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/bitcoinhalving-api","description":"oanor gateway"}],"tags":[{"name":"Halving"},{"name":"Supply"},{"name":"Schedule"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/halving":{"get":{"operationId":"get_v1_halving","tags":["Halving"],"summary":"Countdown to the next halving","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"halving_epoch":4,"current_height":952921,"days_remaining":758,"estimated_date":"2028-07-06T02:58:05.025Z","halvings_so_far":4,"blocks_remaining":97079,"next_subsidy_btc":1.5625,"next_halving_block":1050000,"current_subsidy_btc":3.125,"avg_block_time_seconds":675},"meta":{"timestamp":"2026-06-09T03:02:15.440Z","request_id":"36bbc24e-e306-453b-94bd-2fc472cbce30"},"status":"ok","message":"Halving retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/supply":{"get":{"operationId":"get_v1_supply","tags":["Supply"],"summary":"Circulating supply, percent mined, issuance","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"percent_mined":95.43,"current_height":952921,"max_supply_btc":21000000,"daily_issuance_btc":400.23,"inflation_rate_pct":0.73,"annual_issuance_btc":146083.32,"current_subsidy_btc":3.125,"remaining_to_mine_btc":959618.75,"circulating_supply_btc":20040381.25},"meta":{"timestamp":"2026-06-09T03:02:15.558Z","request_id":"e2e5a3c4-6675-4d62-baee-92ec774bd981"},"status":"ok","message":"Supply retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/schedule":{"get":{"operationId":"get_v1_schedule","tags":["Schedule"],"summary":"The full halving schedule","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"schedule":[{"epoch":0,"is_current":false,"approx_year":2009,"start_block":0,"subsidy_btc":50},{"epoch":1,"is_current":false,"approx_year":2013,"start_block":210000,"subsidy_btc":25},{"epoch":2,"is_current":false,"approx_year":2017,"start_block":420000,"subsidy_btc":12.5},{"epoch":3,"is_current":false,"approx_year":2021,"start_block":630000,"subsidy_btc":6.25},{"epoch":4,"is_current":true,"approx_year":2025,"start_block":840000,"subsidy_btc":3.125},{"epoch":5,"is_current":false,"approx_year":2029,"start_block":1050000,"subsidy_btc":1.5625},{"epoch":6,"is_current":false,"approx_year":2033,"start_block":1260000,"subsidy_btc":0.78125},{"epoch":7,"is_current":false,"approx_year":2037,"start_block":1470000,"subsidy_btc":0.390625},{"epoch":8,"is_current":false,"approx_year":2041,"start_block":1680000,"subsidy_btc":0.1953125},{"epoch":9,"is_current":false,"approx_year":2045,"start_block":1890000,"subsidy_btc":0.09765625},{"epoch":10,"is_current":false,"approx_year":2049,"start_block":2100000,"subsidy_btc":0.04882813},{"epoch":11,"is_current":false,"approx_year":2053,"start_block":2310000,"subsidy_btc":0.02441406},{"epoch":12,"is_current":false,"approx_year":2057,"start_block":2520000,"subsidy_btc":0.01220703},{"epoch":13,"is_current":false,"approx_year":2061,"start_block":2730000,"subsidy_btc":0.00610352},{"epoch":14,"is_current":false,"approx_year":2065,"start_block":2940000,"subsidy_btc":0.00305176},{"epoch":15,"is_current":false,"approx_year":2069,"start_block":3150000,"subsidy_btc":0.00152588},{"epoch":16,"is_current":false,"approx_year":2073,"start_block":3360000,"subsidy_btc":0.00076294},{"epoch":17,"is_current":false,"approx_year":2077,"start_block":3570000,"subsidy_btc":0.00038147},{"epoch":18,"is_current":false,"approx_year":2081,"start_block":3780000,"subsidy_btc":0.00019073},{"epoch":19,"is_current":false,"approx_year":2085,"start_block":3990000,"subsidy_btc":9.537e-5},{"epoch":20,"is_current":false,"approx_year":2089,"start_block":4200000,"subsidy_btc":4.768e-5},{"epoch":21,"is_current":false,"approx_year":2093,"start_block":4410000,"subsidy_btc":2.384e-5},{"epoch":22,"is_current":false,"approx_year":2097,"start_block":4620000,"subsidy_btc":1.192e-5},{"epoch":23,"is_current":false,"approx_year":2101,"start_block":4830000,"subsidy_btc":5.96e-6},{"epoch":24,"is_current":false,"approx_year":2105,"start_block":5040000,"subsidy_btc":2.98e-6},{"epoch":25,"is_current":false,"approx_year":2109,"start_block":5250000,"subsidy_btc":1.49e-6},{"epoch":26,"is_current":false,"approx_year":2113,"start_block":5460000,"subsidy_btc":7.5e-7},{"epoch":27,"is_current":false,"approx_year":2117,"start_block":5670000,"subsidy_btc":3.7e-7},{"epoch":28,"is_current":false,"approx_year":2121,"start_block":5880000,"subsidy_btc":1.9e-7},{"epoch":29,"is_current":false,"approx_year":2125,"start_block":6090000,"subsidy_btc":9.0e-8},{"epoch":30,"is_current":false,"approx_year":2129,"start_block":6300000,"subsidy_btc":5.0e-8},{"epoch":31,"is_current":false,"approx_year":2133,"start_block":6510000,"subsidy_btc":2.0e-8},{"epoch":32,"is_current":false,"approx_year":2137,"start_block":6720000,"subsidy_btc":1.0e-8}],"current_epoch":4,"total_halvings":32},"meta":{"timestamp":"2026-06-09T03:02:15.648Z","request_id":"ea13f10e-e9e7-4c82-903d-ee12062050a8"},"status":"ok","message":"Schedule retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Service metadata","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"source":"mempool.space block height + difficulty adjustment (live)","service":"bitcoinhalving-api","constants":{"max_supply_btc":21000000,"initial_subsidy_btc":50,"halving_interval_blocks":210000},"endpoints":{"GET /v1/meta":"This document.","GET /v1/supply":"Circulating supply, percent mined, daily issuance and inflation rate.","GET /v1/halving":"Countdown to the next halving (subsidy, epoch, blocks/days remaining, date).","GET /v1/schedule":"The full halving schedule (epoch, start block, subsidy, approx year)."},"description":"Live Bitcoin halving countdown and supply schedule from the on-chain block height (mempool.space): current block subsidy and halving epoch, the next halving's block height with blocks/time remaining and estimated date (using the network's recent average block time), the circulating supply mined to date, percent of the 21M cap mined, daily/annual new issuance and the inflation rate, plus the full halving schedule. Live, no key. Distinct from fee/mempool Bitcoin APIs — this is the supply and halving layer.","upstream_status":"ok"},"meta":{"timestamp":"2026-06-09T03:02:15.754Z","request_id":"accf0adb-8dcf-41c5-ae4d-36817ee23c15"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":6000,"rps_limit":5,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1200,"monthly_call_quota":85000,"rps_limit":15,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3000,"monthly_call_quota":450000,"rps_limit":40,"hard_limit":true},{"slug":"desk","name":"Desk","price_cents_month":7000,"monthly_call_quota":2400000,"rps_limit":100,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/bitcoinhalving-api"}