{"openapi":"3.1.0","info":{"title":"FX Seasonality API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/fxseasonality-api","description":"oanor gateway"}],"tags":[{"name":"Seasonality"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/month":{"get":{"operationId":"get_v1_month","tags":["Seasonality"],"summary":"One month's year-by-year history","description":"","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency","schema":{"type":"string"},"example":"GBP"},{"name":"quote","in":"query","required":true,"description":"Quote currency","schema":{"type":"string"},"example":"USD"},{"name":"month","in":"query","required":true,"description":"Month 1-12","schema":{"type":"string"},"example":"12"},{"name":"years","in":"query","required":false,"description":"Years 1-25","schema":{"type":"string"},"example":"10"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/seasonality":{"get":{"operationId":"get_v1_seasonality","tags":["Seasonality"],"summary":"12-month seasonality for a pair","description":"","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency","schema":{"type":"string"},"example":"EUR"},{"name":"quote","in":"query","required":true,"description":"Quote currency","schema":{"type":"string"},"example":"USD"},{"name":"years","in":"query","required":false,"description":"Years 1-25 (default 5)","schema":{"type":"string"},"example":"5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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},{"name":"August","month":8,"years":5,"win_rate_pct":40,"avg_return_pct":0.269},{"name":"September","month":9,"years":5,"win_rate_pct":40,"avg_return_pct":-1.087},{"name":"October","month":10,"years":5,"win_rate_pct":60,"avg_return_pct":-0.104},{"name":"November","month":11,"years":5,"win_rate_pct":60,"avg_return_pct":0.736},{"name":"December","month":12,"years":5,"win_rate_pct":80,"avg_return_pct":0.703}],"best_month":{"name":"November","month":11,"avg_return_pct":0.736},"worst_month":{"name":"September","month":9,"avg_return_pct":-1.087}},"meta":{"timestamp":"2026-06-09T03:03:16.977Z","request_id":"08138909-1018-41f0-a4f7-10cf4fd152f1"},"status":"ok","message":"Seasonality retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Service metadata","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":380,"rps_limit":3,"hard_limit":true},{"slug":"trader","name":"Trader","price_cents_month":900,"monthly_call_quota":9600,"rps_limit":10,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2600,"monthly_call_quota":47500,"rps_limit":25,"hard_limit":true},{"slug":"business","name":"Business","price_cents_month":5900,"monthly_call_quota":238000,"rps_limit":45,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/fxseasonality-api"}