API Documentation

Authentication

All API endpoints require authentication using an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Contact the administrator to obtain your API key.

Base URL

https://ivapi.financialsource.co/api/

Data Updates & Polling Strategy

Update Frequency

Data is updated once daily by 7:00 AM London Time

Since our API uses GET endpoints (pull-based), you'll need to poll for updates.

Recommended Polling Strategy:

Daily polling: Check for updates once per day after 7:30 AM London Time
For real-time systems: Poll every 15 minutes after the initial 7:30 AM check if immediate updates are critical

Response Format

All responses are in JSON format. Successful responses return data with HTTP 200 status. Errors return appropriate HTTP status codes with error messages.

Standard Volatility Data Object:

{
  "symbol": "EURUSD",
  "date": "2025-01-15",
  "iv_high": 0.34,
  "iv_low": 0.22,
  "iv_mean": 0.28,
  "iv_percentile": 75.5,
  "uploaded_at": "2025-01-15T10:30:00"
}

Endpoints

GET /api/symbols

Description: Get list of all available symbols

Parameters: None

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ivapi.financialsource.co/api/symbols

Example Response:

{
  "symbols": ["AAPL", "MSFT", "GOOGL", "TSLA"],
  "count": 4
}

GET /api/latest/{symbol}

Description: Get the most recent volatility data for a symbol

Parameters:

symbol (path) - Stock symbol (e.g., AAPL)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ivapi.financialsource.co/api/latest/AAPL

Example Response:

{
  "symbol": "AAPL",
  "date": "2025-01-15",
  "iv_high": 0.34,
  "iv_low": 0.22,
  "iv_mean": 0.28,
  "iv_percentile": 75.5,
  "uploaded_at": "2025-01-15T10:30:00"
}

GET /api/date/{symbol}/{date}

Description: Get volatility data for a specific symbol and date

Parameters:

symbol (path) - Financial instrument symbol (e.g., EURUSD, XAUUSD, NAS)
date (path) - Date in YYYY-MM-DD format

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ivapi.financialsource.co/api/date/EURUSD/2025-01-15

Example Response:

{
  "symbol": "EURUSD",
  "date": "2025-01-15",
  "iv_high": 0.34,
  "iv_low": 0.22,
  "iv_mean": 0.28,
  "iv_percentile": 75.5,
  "uploaded_at": "2025-01-15T10:30:00"
}

GET /api/history/{symbol}

Description: Get historical volatility data for a symbol

Parameters:

symbol (path) - Financial instrument symbol (e.g., EURUSD, XAUUSD, NAS)
days (query, optional) - Number of days to retrieve (default: 30, max: 365)
limit (query, optional) - Maximum number of records (default: 100, max: 1000)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/history/XAUUSD?days=7&limit=50"

Example Response:

{
  "symbol": "XAUUSD",
  "records": 7,
  "data": [
    {
      "symbol": "XAUUSD",
      "date": "2025-01-15",
      "iv_high": 0.34,
      "iv_low": 0.22,
      "iv_mean": 0.28,
      "iv_percentile": 75.5,
      "uploaded_at": "2025-01-15T10:30:00"
    },
    ...
  ]
}

GET /api/compare/{symbols}

Description: Compare latest volatility data across multiple symbols

Parameters:

symbols (path) - Comma-separated list of symbols (max 10)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ivapi.financialsource.co/api/compare/EURUSD,XAUUSD,NAS

Example Response:

{
  "symbols_requested": ["EURUSD", "XAUUSD", "NAS"],
  "symbols_found": 3,
  "data": [
    {
      "symbol": "EURUSD",
      "date": "2025-01-15",
      "iv_high": 0.34,
      "iv_low": 0.22,
      "iv_mean": 0.28
    },
    ...
  ]
}

GET /api/range/{symbol}/{start_date}/{end_date}

Description: Get volatility data for a symbol within a date range

Parameters:

symbol (path) - Financial instrument symbol (e.g., EURUSD, XAUUSD, NAS)
start_date (path) - Start date (YYYY-MM-DD)
end_date (path) - End date (YYYY-MM-DD, max 365 days range)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://ivapi.financialsource.co/api/range/EURUSD/2025-01-01/2025-01-31

GET /api/stats/{symbol}

Description: Get statistical summary for a symbol

Parameters:

symbol (path) - Financial instrument symbol (e.g., EURUSD, XAUUSD, NAS)
days (query, optional) - Period in days (default: 30, max: 365)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/stats/XAUUSD?days=90"

Example Response:

{
  "symbol": "XAUUSD",
  "period_days": 90,
  "records_count": 65,
  "iv_high": {
    "min": 0.18,
    "max": 0.42,
    "avg": 0.28
  },
  "iv_mean": {
    "min": 0.15,
    "max": 0.35,
    "avg": 0.24
  }
}

GET /api/v3/percentiles/{symbol}

Description: Get volatility percentile ranking for a symbol

Parameters:

symbol (path) - Financial instrument symbol (e.g., EURUSD, XAUUSD, NAS)
lookback_days (query, optional) - Historical period (default: 252, max: 1000)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/v3/percentiles/EURUSD?lookback_days=252"

Example Response:

{
  "symbol": "EURUSD",
  "current_percentile": 85.2,
  "trading_signals": [
    {
      "signal": "SELL_VOLATILITY",
      "strength": "HIGH",
      "reason": "IV at extreme high levels - expect mean reversion"
    }
  ],
  "alpha_insights": {
    "regime": "HIGH_VOL",
    "mean_reversion_probability": 70.4
  }
}

GET /api/v3/breakout-signals/{symbol}

Description: Get volatility breakout signals for a symbol

Parameters:

symbol (path) - Financial instrument symbol
lookback_period (query, optional) - Analysis window (default: 60, max: 250)

Example Request:

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/v3/breakout-signals/EURUSD"

Example Response:

{
  "symbol": "EURUSD",
  "breakout_signals": [
    {
      "signal": "VOLATILITY_COMPRESSION",
      "probability": 75.2,
      "time_horizon": "5-15 days",
      "trade_setup": "Long straddles/strangles"
    }
  ]
}

GET /api/v3/correlations/volatility

Description: Get cross-asset volatility correlations

Parameters:

symbols (query, required) - Comma-separated symbols (2-10 symbols)
rolling_window (query, optional) - Correlation window (default: 30, max: 90)

Example Request:

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/v3/correlations/volatility?symbols=EURUSD,GBPUSD,GOLD"

Example Response:

{
  "correlation_matrix": [
    {
      "pair": "EURUSD/GBPUSD",
      "correlation": 0.7234,
      "strength": "STRONG"
    }
  ],
  "arbitrage_opportunities": [
    {
      "pair": "EURUSD/GBPUSD",
      "signal": "CONVERGENCE_TRADE",
      "z_score": 2.15,
      "trade_direction": "SELL EURUSD, BUY GBPUSD"
    }
  ]
}

GET /api/search

Description: Search for symbols by pattern

Parameters:

q (query) - Search query (minimum 1 character)

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://ivapi.financialsource.co/api/search?q=EUR"

Example Response:

{
  "query": "EUR",
  "symbols": ["EURAUD", "EURCAD", "EURCHF", "EURGBP", "EURJPY", "EURMXN", "EURNOK", "EURNZD", "EURSEK", "EURUSD"],
  "count": 10
}

Error Codes

Status Code	Description	Example Response
400	Bad Request	`{"error": "Invalid date format. Use YYYY-MM-DD"}`
401	Unauthorized	`{"error": "Invalid API key"}`
403	Forbidden	`{"error": "Admin access required"}`
404	Not Found	`{"error": "No data found for symbol EURUSD"}`
429	Rate Limited	`{"error": "Daily request limit exceeded"}`
500	Server Error	`{"error": "Internal server error"}`

Rate Limiting

API requests are limited based on your tier. Limits are designed for realistic daily volatility data usage:

Tier	Daily Limit	Monthly Limit	Best For
Professional	250 requests	6,000 requests	Professional trading systems, multiple apps
Enterprise	1,000 requests	25,000 requests	Institutional use, high-volume applications

Why these limits? Since volatility data updates once daily, most applications need only 10-100 requests per day. These tiers accommodate realistic usage patterns from individual traders to institutional platforms.

Rate limiting is enforced on both daily and monthly basis. Limits reset at midnight UTC daily and on the 1st of each month.

View Pricing & Request Access

Code Examples

Python Example:

import requests

api_key = "YOUR_API_KEY"
base_url = "https://ivapi.financialsource.co/api"

headers = {
    "Authorization": f"Bearer {api_key}"
}

# Get latest data for EURUSD
response = requests.get(
    f"{base_url}/latest/EURUSD",
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"EURUSD IV Mean: {data['iv_mean']}")
else:
    print(f"Error: {response.json()['error']}")

JavaScript Example:

const apiKey = "YOUR_API_KEY";
const baseUrl = "https://ivapi.financialsource.co/api";

async function getLatestData(symbol) {
    try {
        const response = await fetch(
            `${baseUrl}/latest/${symbol}`,
            {
                headers: {
                    "Authorization": `Bearer ${apiKey}`
                }
            }
        );
        
        if (response.ok) {
            const data = await response.json();
            console.log(`${symbol} IV Mean:`, data.iv_mean);
            return data;
        } else {
            const error = await response.json();
            console.error("Error:", error.error);
        }
    } catch (error) {
        console.error("Network error:", error);
    }
}

getLatestData("EURUSD");