# Monte Carlo API
> Live Monte-Carlo simulation for price and portfolio forecasting that quants, traders and planners run to model uncertainty — computed on demand and reproducibly, no key, nothing cached. Run a geometric-Brownian-motion simulation of an asset and get the terminal-price distribution (percentiles, mean, probability of a gain); get the modelled chance of reaching a target price; project wealth over many years with periodic contributions (a retirement / savings projection); and return one sample price path for charting. Every run is seeded, so the same inputs always give the same numbers. A forward-looking simulation engine, distinct from historical-statistics and option-pricing tools — it turns a drift and volatility into a distribution of outcomes.

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

## Pricing
- **Free** (Free) — 4,650 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 106,000 calls/Mo, 10 req/s
- **Pro** ($19/Mo) — 520,000 calls/Mo, 25 req/s
- **Business** ($45/Mo) — 3,180,000 calls/Mo, 55 req/s

## Endpoints

### Monte Carlo

#### `GET /v1/meta` — Service metadata and endpoint list

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

**Response:**
```json
{
    "data": {
        "note": "Drift/volatility/expected_return are annual decimals (0.07 = 7%). horizon in years. Runs are deterministic per seed (default 12345).",
        "source": "Computed in-process (seeded mulberry32 PRNG + Box-Muller normals)",
        "service": "montecarlo-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/path": "One sample price path (spot=100, drift=0.07, volatility=0.2, horizon=1, steps=50).",
            "GET /v1/simulate": "Terminal-price distribution of an asset (spot=100, drift=0.07, volatility=0.2, horizon=1, paths=10000).",
            "GET /v1/portfolio": "Wealth projection with contributions (initial=10000, annual_contribution=6000, years=30, expected_return=0.07, volatility=0.15, goal=1000000).",
            "GET /v1/probability": "Modelled chance of reaching a target price (spot=100, target=120, drift=0.07, volatility=0.2, horizon=1)."
        },
        "description": "Live Monte-Carlo simulation for price and portfolio forecasting, computed on demand and reproducibly. The simulate endpoint runs a geometric-Brownian-motion simulation of an asset and returns the terminal-price distribution (percentiles, mean, probability of a gain); the probability endpoint returns the modelled chance of reaching a target price; the portfolio endpoint projects wealth over many years with periodic contributions (a retirement/savings projection); the path endpoint returns one sample price path. Every run is 
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/path` — One sample price path

**Parameters:**
- `spot` (query, required, string) — Current price Example: `100`
- `volatility` (query, required, string) — Annual volatility (decimal) Example: `0.2`
- `horizon` (query, optional, string) — Years (default 1) Example: `1`
- `drift` (query, optional, string) — Annual drift (default 0.05) Example: `0.07`
- `steps` (query, optional, string) — Steps 2-1000 (default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/montecarlo-api/v1/path?spot=100&volatility=0.2&horizon=1&drift=0.07&steps=50"
```

**Response:**
```json
{
    "data": {
        "path": [
            {
                "t": 0,
                "step": 0,
                "price": 100
            },
            {
                "t": 0.02,
                "step": 1,
                "price": 99.900227
            },
            {
                "t": 0.04,
                "step": 2,
                "price": 101.420445
            },
            {
                "t": 0.06,
                "step": 3,
                "price": 99.622727
            },
            {
                "t": 0.08,
                "step": 4,
                "price": 100.386947
            },
            {
                "t": 0.1,
                "step": 5,
                "price": 100.590347
            },
            {
                "t": 0.12,
                "step": 6,
                "price": 104.093203
            },
            {
                "t": 0.14,
                "step": 7,
                "price": 105.598976
            },
            {
                "t": 0.16,
                "step": 8,
                "price": 105.725921
            },
            {
                "t": 0.18,
                "step": 9,
                "price": 104.597829
            },
            {
                "t": 0.2,
                "step": 10,
                "price": 106.121182
            },
            {
                "t": 0.22,
                "step": 11,
                "price": 106.757136
            },
            {
                "t": 0.24,
         
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/portfolio` — Wealth projection with periodic contributions

**Parameters:**
- `volatility` (query, required, string) — Annual volatility (decimal) Example: `0.15`
- `initial` (query, optional, string) — Initial balance Example: `10000`
- `annual_contribution` (query, optional, string) — Yearly contribution Example: `6000`
- `years` (query, optional, string) — Years (default 30) Example: `30`
- `expected_return` (query, optional, string) — Annual return (default 0.07) Example: `0.07`
- `goal` (query, optional, string) — Optional target wealth Example: `1000000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/montecarlo-api/v1/portfolio?volatility=0.15&initial=10000&annual_contribution=6000&years=30&expected_return=0.07&goal=1000000"
```

**Response:**
```json
{
    "data": {
        "goal": 1000000,
        "seed": 12345,
        "paths": 10000,
        "years": 30,
        "source": "MONTECARLO",
        "initial": 10000,
        "volatility": 0.15,
        "expected_return": 0.07,
        "prob_reach_goal": 0.1376,
        "terminal_wealth": {
            "mean": 640695.34,
            "median": 547051.42,
            "percentiles": {
                "p5": 225605.59785,
                "p10": 274677.065911,
                "p25": 374954.09741,
                "p50": 547051.419783,
                "p75": 791395.252508,
                "p90": 1103548.851129,
                "p95": 1361315.679122
            }
        },
        "total_contributed": 190000,
        "annual_contribution": 6000
    },
    "meta": {
        "timestamp": "2026-06-10T22:56:13.698Z",
        "request_id": "cf57734a-58bd-47f2-8c83-7742e79d1835"
    },
    "status": "ok",
    "message": "Portfolio projection computed",
    "success": true
}
```

#### `GET /v1/probability` — Modelled chance of reaching a target price

**Parameters:**
- `spot` (query, required, string) — Current price Example: `100`
- `target` (query, required, string) — Target price Example: `120`
- `volatility` (query, required, string) — Annual volatility (decimal) Example: `0.2`
- `horizon` (query, optional, string) — Years (default 1) Example: `1`
- `drift` (query, optional, string) — Annual drift (default 0.05) Example: `0.07`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/montecarlo-api/v1/probability?spot=100&target=120&volatility=0.2&horizon=1&drift=0.07"
```

**Response:**
```json
{
    "data": {
        "seed": 12345,
        "spot": 100,
        "drift": 0.07,
        "model": "GBM",
        "paths": 10000,
        "source": "MONTECARLO",
        "target": 120,
        "prob_below": 0.7447,
        "volatility": 0.2,
        "horizon_years": 1,
        "prob_at_or_above": 0.2553,
        "expected_terminal": 107.42775,
        "expected_if_above_target": 136.156639
    },
    "meta": {
        "timestamp": "2026-06-10T22:56:13.802Z",
        "request_id": "6c1af5a6-5719-4c69-8595-5d9e3ee1dac7"
    },
    "status": "ok",
    "message": "Probability computed",
    "success": true
}
```

#### `GET /v1/simulate` — Terminal-price distribution of an asset (GBM)

**Parameters:**
- `spot` (query, required, string) — Current price Example: `100`
- `volatility` (query, required, string) — Annual volatility (decimal) Example: `0.2`
- `horizon` (query, optional, string) — Years (default 1) Example: `1`
- `drift` (query, optional, string) — Annual drift (decimal, default 0.05) Example: `0.07`
- `paths` (query, optional, string) — Simulations 100-200000 (default 10000) Example: `10000`
- `seed` (query, optional, string) — PRNG seed (default 12345) Example: `12345`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/montecarlo-api/v1/simulate?spot=100&volatility=0.2&horizon=1&drift=0.07&paths=10000&seed=12345"
```

**Response:**
```json
{
    "data": {
        "seed": 12345,
        "spot": 100,
        "drift": 0.07,
        "model": "GBM",
        "paths": 10000,
        "source": "MONTECARLO",
        "terminal": {
            "max": 212.854518,
            "min": 52.286649,
            "mean": 107.42775,
            "stdev": 21.652227,
            "median": 105.211517,
            "percentiles": {
                "p5": 76.178028,
                "p10": 81.864015,
                "p25": 91.700115,
                "p50": 105.211517,
                "p75": 120.332733,
                "p90": 136.098108,
                "p95": 145.833838
            }
        },
        "volatility": 0.2,
        "horizon_years": 1,
        "probability_gain": 0.5981,
        "expected_return_pct": 7.4277
    },
    "meta": {
        "timestamp": "2026-06-10T22:56:13.916Z",
        "request_id": "baf179a2-538f-4934-a640-b1dfbcc8f92b"
    },
    "status": "ok",
    "message": "Simulation computed",
    "success": true
}
```


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