# Bitcoin Halving API
> 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.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/bitcoinhalving-api/..."
```

## Pricing
- **Free** (Free) — 6,000 calls/Mo, 5 req/s
- **Starter** ($12/Mo) — 85,000 calls/Mo, 15 req/s
- **Pro** ($30/Mo) — 450,000 calls/Mo, 40 req/s
- **Desk** ($70/Mo) — 2,400,000 calls/Mo, 100 req/s

## Endpoints

### Halving

#### `GET /v1/halving` — Countdown to the next halving

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bitcoinhalving-api/v1/halving"
```

**Response:**
```json
{
    "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
}
```

### Supply

#### `GET /v1/supply` — Circulating supply, percent mined, issuance

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bitcoinhalving-api/v1/supply"
```

**Response:**
```json
{
    "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
}
```

### Schedule

#### `GET /v1/schedule` — The full halving schedule

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bitcoinhalving-api/v1/schedule"
```

**Response:**
```json
{
    "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
            },
            {
        
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bitcoinhalving-api/v1/meta"
```

**Response:**
```json
{
    "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
}
```


---
Marketplace page: https://www.oanor.com/api/bitcoinhalving-api
OpenAPI spec: https://www.oanor.com/api/bitcoinhalving-api/openapi.json