# Reaction Stoichiometry API
> Chemical reaction-stoichiometry maths as an API, computed locally and deterministically. The limiting-reagent endpoint takes two reactants with their amounts in moles and their balanced-equation coefficients and finds which one runs out first — the limiting reagent — by comparing the moles/coefficient ratio (the reaction extent), and returns how much of the excess reagent is left over. The yield endpoint computes the theoretical yield of a product, in moles and grams, from the limiting reagent and the product's stoichiometric coefficient and molar mass, n_product = n_limiting·(coeff_product/coeff_limiting), and — given the actual yield — the percent yield. The mole-mass endpoint converts between moles, mass and the number of particles for a given molar mass, using moles = mass / molar_mass and N = moles · Avogadro's number (6.02214076e23). Amounts are in moles, masses in grams and molar masses in g/mol. Everything is computed locally and deterministically, so it is instant and private. Ideal for chemistry-education, lab, pharmaceutical and chemical-engineering app developers, reaction-planning and yield tools, and STEM teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is reaction stoichiometry; for a compound's molar mass from its formula use a molar-mass API and for solution concentrations a dilution 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/stoichiometry-api/..."
```

## Pricing
- **Free** (Free) — 3,500 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 42,000 calls/Mo, 6 req/s
- **Pro** ($16/Mo) — 240,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,400,000 calls/Mo, 40 req/s

## Endpoints

### Stoichiometry

#### `GET /v1/limiting-reagent` — Limiting reagent

**Parameters:**
- `moles_a` (query, required, string) — Moles of reactant A Example: `4`
- `coefficient_a` (query, optional, string) — Coefficient of A Example: `2`
- `moles_b` (query, required, string) — Moles of reactant B Example: `1`
- `coefficient_b` (query, optional, string) — Coefficient of B Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/stoichiometry-api/v1/limiting-reagent?moles_a=4&coefficient_a=2&moles_b=1&coefficient_b=1"
```

**Response:**
```json
{
    "data": {
        "note": "The limiting reagent has the smallest moles/coefficient ratio (reaction extent). The reaction stops when it runs out; the other reagent is left in excess.",
        "inputs": {
            "moles_a": 4,
            "moles_b": 1,
            "coefficient_a": 2,
            "coefficient_b": 1
        },
        "excess_reagent": "a",
        "reaction_extent": 1,
        "limiting_reagent": "b",
        "excess_remaining_moles": 2
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:39.062Z",
        "request_id": "2f6f1591-a075-4aa0-9d0d-8a6a92adbfa8"
    },
    "status": "ok",
    "message": "Limiting reagent",
    "success": true
}
```

#### `GET /v1/mole-mass` — Mole-mass-particle conversion

**Parameters:**
- `molar_mass` (query, required, string) — Molar mass (g/mol) Example: `18.015`
- `moles` (query, optional, string) — Moles Example: `2`
- `mass` (query, optional, string) — Or mass (g)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/stoichiometry-api/v1/mole-mass?molar_mass=18.015&moles=2"
```

**Response:**
```json
{
    "data": {
        "note": "moles = mass / molar_mass; particles = moles · Nₐ (6.02214076e23). Give moles OR mass and the molar mass to get the rest.",
        "moles": 2,
        "inputs": {
            "mass": null,
            "moles": 2,
            "molar_mass": 18.015
        },
        "mass_g": 36.03,
        "particles": 1.204428152e+24,
        "avogadro_constant": 6.02214076e+23
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:39.164Z",
        "request_id": "e9cb875d-49c4-40bc-abfa-18da518412f0"
    },
    "status": "ok",
    "message": "Mole-mass conversion",
    "success": true
}
```

#### `GET /v1/yield` — Theoretical & percent yield

**Parameters:**
- `limiting_moles` (query, required, string) — Moles of limiting reagent Example: `1`
- `limiting_coefficient` (query, optional, string) — Coefficient of limiting reagent Example: `1`
- `product_coefficient` (query, optional, string) — Coefficient of product Example: `2`
- `product_molar_mass` (query, required, string) — Product molar mass (g/mol) Example: `18.015`
- `actual_yield` (query, optional, string) — Actual yield (g) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/stoichiometry-api/v1/yield?limiting_moles=1&limiting_coefficient=1&product_coefficient=2&product_molar_mass=18.015&actual_yield=30"
```

**Response:**
```json
{
    "data": {
        "note": "Theoretical yield: n_product = n_limiting · (coeff_product / coeff_limiting); mass = n · M. Percent yield = actual / theoretical · 100.",
        "inputs": {
            "limiting_moles": 1,
            "product_molar_mass": 18.015,
            "product_coefficient": 2,
            "limiting_coefficient": 1
        },
        "percent_yield": 83.2639,
        "actual_yield_g": 30,
        "theoretical_moles": 2,
        "theoretical_mass_g": 36.03
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:39.244Z",
        "request_id": "c32c23fe-a96f-449d-9415-928c7acc412a"
    },
    "status": "ok",
    "message": "Yield",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Amounts in mol, masses in g, molar masses in g/mol. Coefficients are the balanced-equation stoichiometric numbers (default 1).",
        "service": "stoichiometry-api",
        "formulae": {
            "limiting": "extent_i = moles_i / coeff_i ; smallest limits",
            "particles": "N = moles · Nₐ",
            "percent_yield": "actual / theoretical · 100",
            "theoretical_yield": "n_product = n_limiting · (coeff_product / coeff_limiting)"
        },
        "constants": {
            "avogadro_per_mol": 6.02214076e+23
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/yield": "Theoretical yield (moles & mass) and percent yield from the limiting reagent.",
            "GET /v1/mole-mass": "Convert between moles, mass and particle count for a given molar mass.",
            "GET /v1/limiting-reagent": "Limiting reagent, reaction extent and excess remaining from two reactants and their coefficients."
        },
        "description": "Reaction stoichiometry calculator: limiting reagent and excess, theoretical and percent yield, and mole–mass–particle conversions via Avogadro's number."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:39.340Z",
        "request_id": "50999c86-cc3f-46a0-bf87-c0219cec34b1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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