# Half-Life Decay API
> Radioactive (exponential) decay maths as an API, computed locally and deterministically. The decay endpoint computes how much of a substance remains after a given time, N(t) = N0·(1/2)^(t/T½) = N0·e^(−λt): from a half-life (or a decay constant or mean lifetime), an elapsed time and an optional initial amount, it returns the fraction and percent remaining, the remaining and decayed amounts, the number of half-lives elapsed, and — if you give an initial activity — the remaining activity, which decays by the same factor. The constant endpoint converts freely between the half-life T½, the decay constant λ = ln2/T½ and the mean lifetime τ = 1/λ = T½/ln2. The age endpoint reverses the decay to find the elapsed time from the fraction remaining, t = T½·log₂(1/fraction) — the basis of radiometric (carbon-14) dating — and accepts either a fraction or a remaining and initial amount. Time and half-life share one unit, and the results come out in that unit. Everything is computed locally and deterministically, so it is instant and private. Ideal for physics and chemistry education, nuclear-medicine and dosimetry tools, archaeology and geology dating, and pharmacokinetics and science apps. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is exponential decay; for the ideal gas law use a gas-law API and for the chemical elements use an elements API.

## 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/halflife-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,547,000 calls/Mo, 40 req/s

## Endpoints

### Decay

#### `GET /v1/age` — Age from remaining fraction

**Parameters:**
- `half_life` (query, optional, string) — Half-life T½ (or decay_constant) Example: `5730`
- `decay_constant` (query, optional, string) — Or decay constant λ
- `fraction_remaining` (query, optional, string) — Fraction remaining (0-1) Example: `0.25`
- `remaining` (query, optional, string) — Or remaining amount (with initial)
- `initial` (query, optional, string) — Initial amount

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/halflife-api/v1/age?half_life=5730&fraction_remaining=0.25"
```

**Response:**
```json
{
    "data": {
        "age": 11460,
        "note": "Age comes out in the same time unit as the half-life. Basis of radiometric (e.g. carbon-14) dating.",
        "formula": "t = T½ · log₂(1/fraction) = −ln(fraction) / λ.",
        "half_life": 5730,
        "decay_constant": 0.0001209681,
        "percent_remaining": 25,
        "fraction_remaining": 0.25,
        "half_lives_elapsed": 2
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.303Z",
        "request_id": "4f560efd-4936-43e7-8a3d-0ef2b79c0b66"
    },
    "status": "ok",
    "message": "Age from remaining fraction",
    "success": true
}
```

#### `GET /v1/constant` — Half-life / decay constant / lifetime

**Parameters:**
- `half_life` (query, optional, string) — Half-life T½ Example: `5730`
- `decay_constant` (query, optional, string) — Or decay constant λ
- `mean_lifetime` (query, optional, string) — Or mean lifetime τ

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/halflife-api/v1/constant?half_life=5730"
```

**Response:**
```json
{
    "data": {
        "note": "λ = ln2 / T½; mean lifetime τ = 1/λ = T½/ln2 ≈ 1.4427·T½.",
        "source": "half_life",
        "half_life": 5730,
        "mean_lifetime": 8266.64258429,
        "decay_constant": 0.0001209681
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.398Z",
        "request_id": "cbeb1f43-a9dd-43e4-b8b6-3175b2e0c91e"
    },
    "status": "ok",
    "message": "Half-life / decay constant / lifetime",
    "success": true
}
```

#### `GET /v1/decay` — Remaining amount after time

**Parameters:**
- `half_life` (query, optional, string) — Half-life T½ (or decay_constant) Example: `5730`
- `decay_constant` (query, optional, string) — Or decay constant λ
- `mean_lifetime` (query, optional, string) — Or mean lifetime τ
- `time` (query, required, string) — Elapsed time (same unit as T½) Example: `11460`
- `initial` (query, optional, string) — Initial amount N0 (default 1) Example: `100`
- `initial_activity` (query, optional, string) — Initial activity (optional)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/halflife-api/v1/decay?half_life=5730&time=11460&initial=100"
```

**Response:**
```json
{
    "data": {
        "note": "Fraction remaining depends only on time/half-life. Activity decays by the same factor.",
        "time": 11460,
        "formula": "N(t) = N0 · (1/2)^(t/T½) = N0 · e^(−λt).",
        "half_life": 5730,
        "decay_constant": 0.0001209681,
        "decayed_amount": 75,
        "initial_amount": 100,
        "remaining_amount": 25,
        "percent_remaining": 25,
        "fraction_remaining": 0.25,
        "half_lives_elapsed": 2
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.497Z",
        "request_id": "8fee1bc5-317e-4714-a774-8951cab143cd"
    },
    "status": "ok",
    "message": "Remaining amount after time",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

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

**Response:**
```json
{
    "data": {
        "api": "halflife",
        "note": "Radioactive (exponential) decay maths — computed locally and deterministically, no key, no third-party service. Time and half-life share a unit.",
        "endpoints": [
            "/v1/decay",
            "/v1/constant",
            "/v1/age",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.580Z",
        "request_id": "7665ad41-0fab-4a99-89a9-c2b674c8060a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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