# FX Seasonality API
> A live forex analytic that reveals the calendar-month patterns in a currency pair, computed from years of European Central Bank daily reference rates. For any pair it returns the average return in each calendar month over the chosen number of years, plus the win rate (how often that month was historically positive) and the best and worst months — the seasonal tendencies traders lean on. Get a pair's full 12-month seasonality, or zoom into one month's year-by-year history. Built for forex, trading and research apps. Live, no key. Past patterns are not a forecast. Distinct from rate, strength, volatility, correlation, signal and range APIs.

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

## Pricing
- **Free** (Free) — 380 calls/Mo, 3 req/s
- **Trader** ($9/Mo) — 9,600 calls/Mo, 10 req/s
- **Pro** ($26/Mo) — 47,500 calls/Mo, 25 req/s
- **Business** ($59/Mo) — 238,000 calls/Mo, 45 req/s

## Endpoints

### Seasonality

#### `GET /v1/month` — One month's year-by-year history

**Parameters:**
- `base` (query, required, string) — Base currency Example: `GBP`
- `quote` (query, required, string) — Quote currency Example: `USD`
- `month` (query, required, string) — Month 1-12 Example: `12`
- `years` (query, optional, string) — Years 1-25 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fxseasonality-api/v1/month?base=GBP&quote=USD&month=12&years=10"
```

**Response:**
```json
{
    "data": {
        "base": "GBP",
        "name": "December",
        "pair": "GBPUSD",
        "month": 12,
        "quote": "USD",
        "years": 10,
        "history": [
            {
                "year": 2016,
                "return_pct": -2.57
            },
            {
                "year": 2017,
                "return_pct": 0.217
            },
            {
                "year": 2018,
                "return_pct": 0.699
            },
            {
                "year": 2019,
                "return_pct": 2.079
            },
            {
                "year": 2020,
                "return_pct": 2.412
            },
            {
                "year": 2021,
                "return_pct": 1.264
            },
            {
                "year": 2022,
                "return_pct": -1.398
            },
            {
                "year": 2023,
                "return_pct": 0.604
            },
            {
                "year": 2024,
                "return_pct": -1.147
            },
            {
                "year": 2025,
                "return_pct": 1.494
            }
        ],
        "win_rate_pct": 70,
        "avg_return_pct": 0.365
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:13.051Z",
        "request_id": "7a9a0101-9e5a-4f54-9b4d-41b1993e67af"
    },
    "status": "ok",
    "message": "Month history retrieved successfully",
    "success": true
}
```

#### `GET /v1/seasonality` — 12-month seasonality for a pair

**Parameters:**
- `base` (query, required, string) — Base currency Example: `EUR`
- `quote` (query, required, string) — Quote currency Example: `USD`
- `years` (query, optional, string) — Years 1-25 (default 5) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fxseasonality-api/v1/seasonality?base=EUR&quote=USD&years=5"
```

**Response:**
```json
{
    "data": {
        "base": "EUR",
        "pair": "EURUSD",
        "quote": "USD",
        "years": 5,
        "months": [
            {
                "name": "January",
                "month": 1,
                "years": 5,
                "win_rate_pct": 60,
                "avg_return_pct": 0.19
            },
            {
                "name": "February",
                "month": 2,
                "years": 5,
                "win_rate_pct": 40,
                "avg_return_pct": -0.383
            },
            {
                "name": "March",
                "month": 3,
                "years": 5,
                "win_rate_pct": 40,
                "avg_return_pct": 0.572
            },
            {
                "name": "April",
                "month": 4,
                "years": 5,
                "win_rate_pct": 60,
                "avg_return_pct": 0.472
            },
            {
                "name": "May",
                "month": 5,
                "years": 5,
                "win_rate_pct": 40,
                "avg_return_pct": 0.03
            },
            {
                "name": "June",
                "month": 6,
                "years": 6,
                "win_rate_pct": 33.333,
                "avg_return_pct": -0.59
            },
            {
                "name": "July",
                "month": 7,
                "years": 5,
                "win_rate_pct": 60,
                "avg_return_pct": -0.658
            },
        
…(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/fxseasonality-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "ECB daily reference rates via Frankfurter (live)",
        "service": "fxseasonality-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/month": "One month's year-by-year history (base, quote, month=1-12, years).",
            "GET /v1/seasonality": "12-month seasonality for a pair (base=EUR&quote=USD, years=5)."
        },
        "description": "Live FX seasonality analytic from ECB reference rates (Frankfurter): for any currency pair, the average return in each calendar month over N years, the win rate (how often that month was positive), and the best/worst months. Get full 12-month seasonality or one month's year-by-year history. Live, no key. Past patterns are not a forecast. Distinct from rate, strength, volatility, correlation, signal and range APIs.",
        "years_range": "1-25 (default 5)"
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:17.078Z",
        "request_id": "67f3448c-386b-4649-b617-b5ec627d3880"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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