# FX Z-Score & Mean-Reversion API
> How statistically stretched each currency pair is right now versus its own recent average — the z-score mean-reversion gauge — computed live from Yahoo Finance daily rates (no key, nothing stored). A price alone tells you nothing about whether a pair is cheap or dear; the z-score does: it measures how many standard deviations the current rate sits above or below its rolling mean. A pair two standard deviations above its average is statistically overbought and prone to snap back; two below is oversold. The zscore endpoint returns, for a pair, the current rate, its rolling mean and standard deviation, the z-score, the percent distance from the mean and a plain overbought / oversold label. The screener endpoint scans the major and cross pairs and ranks them by how stretched they are — the most overbought and most oversold at a glance, the mean-reversion opportunity scan. The pairs endpoint lists what is covered. The statistical-stretch / mean-reversion cut for FX — distinct from the FX range, pivot-point, volatility and signals APIs. It answers how far from normal a pair is, not where its support sits or how fast it moves.

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

## Pricing
- **Free** (Free) — 900 calls/Mo, 2 req/s
- **Starter** ($10/Mo) — 22,500 calls/Mo, 6 req/s
- **Pro** ($29/Mo) — 110,000 calls/Mo, 18 req/s
- **Business** ($71/Mo) — 560,000 calls/Mo, 45 req/s

## Endpoints

### Z-Score

#### `GET /v1/zscore` — Z-score, mean, std-dev and overbought/oversold label for one pair

**Parameters:**
- `pair` (query, required, string) — FX pair (see /v1/pairs) Example: `EURUSD`
- `window` (query, optional, string) — Rolling window in trading days (20-250) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fxzscore-api/v1/zscore?pair=EURUSD&window=100"
```

### Screener

#### `GET /v1/screener` — Major/cross pairs ranked by absolute z-score

**Parameters:**
- `window` (query, optional, string) — Rolling window (20-250) Example: `100`
- `pairs` (query, optional, string) — Optional comma list to restrict scan Example: `EURUSD,USDCAD,GBPJPY`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fxzscore-api/v1/screener?window=100&pairs=EURUSD%2CUSDCAD%2CGBPJPY"
```

### Pairs

#### `GET /v1/pairs` — Supported FX pairs

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

### Meta

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

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


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