Bulk API

import pandas as pd

url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/relation?token=demo"
correlation_matrix = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split')
print(correlation_matrix)

• Please see the FAQ for a detailed introduction to basic concepts.
• API provides bulk access to pre-calculated tables representing pairwise relationships (correlation, cointegration, hurst exponent, etc.) between a universe of approximately 3,500¹ liquid US stocks and ETFs for a specific historical date.
• Each table (except for the instruments endpoint) is provided as a square matrix in JSON format, designed for straightforward import into a Pandas DataFrame.
• This guide provides instructions for accessing the CorrGrid API endpoints. While the underlying data is provided as gzipped JSON files (suitable for loading from any client), this guide focuses on retrieving bulk data directly into Python Pandas DataFrames.  

API Base URL: https://api.corrgrid.com/v2

Path Template:

.../v2/YYYY-MM-DD/{ corr coi }/{ raw ex_spy ex_etf }/{ relation beta hurst hedge_ratio half_life ... }?token={access_token}

For evaluation, use the provided demo token by appending ?token=demo to the API endpoint URL.

For production use, it is strongly recommended to pass your API key via the X-API-TOKEN header.

• Rate Limiting: Demo access is rate-limited. Exceeding the limit may result in a 429 Too Many Requests error or a response containing an error message.
• Limitation: Demo access is strictly limited to the fixed date: 2025-02-26. Requests for other dates using ?token=demo will return an error.

We will refer to the combination of two financial instruments (’legs’), where a long position in one is hedged by a short position in the other (scaled by β), as a spread or synthetic instrument (more common) or two-legged (hedged) position. Its value is calculated as:

• The row index represents ‘Leg A’, and the column index (or labels) represent ‘Leg B’.
• The key identifier for instruments within these tables (rows, columns) is the PIT-Symbol (Point-In-Time Symbol), ensuring consistency regardless of market ticker changes over time. See more.
• In raw mode, both Leg A and Leg B refer to specific stock or ETF instruments identified by their unique PIT-Symbols ( Point-In-Time Symbols ).
• In ex_spy mode, Leg A and Leg B effectively represent the instruments from ‘raw’ mode but adjusted to remove the broad market influence (proxied by SPY), thereby filtering out this source of systematic noise. See What are ex-SPY and ex-ETF?
• In ex_etf mode, Leg A and Leg B effectively represent the instruments from ‘raw’ mode but adjusted to remove sector-specific influence (‘sector noise’), using each instrument’s most relevant sector ETF as the proxy. See How is the ETF selected for ex-ETF calculations?
• The mapping from PIT-Symbols to the date-specific market ticker is available via the /instruments endpoint (described below).

To optimize data transfer, the API returns integer values for most tables. You must divide these integers by the specified multiplier (e.g., 100.0 or 1000.0) to obtain the actual floating-point metric values. Multipliers are listed below for each metric.

Examples for Correlations (.../corr/raw/...)

Let’s assume we have the symbols for MSFT and CSCO for the demo date (2025-02-26).

import pandas as pd
symbol_leg_A='MSFT...'
symbol_leg_B='CSCO...'
url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/relation?token=demo"
# Divide by multiplier (100.0 for correlations)
corr_matrix = pd.read_json(url,
          storage_options = {"User-Agent": "api"}, 
          orient='split') / 100.0
print('MSFT vs CSCO correlation: ',corr_matrix.loc[symbol_leg_A,symbol_leg_B])

This β is used to construct the two-legged position (spread): MSFT − β × CSCO.

url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/beta?token=demo"
# Divide by multiplier (100.0 for beta)
betas = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split') / 100.0
print('Beta in MSFT - beta*CSCO. Beta:',betas.loc[symbol_leg_A,symbol_leg_B])

This shows the percentage reduction in volatility for MSFT − β × CSCO compared to an unhedged MSFT position.

url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/R2?token=demo"
R2s = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split')
print('R2:',R2s.loc[symbol_leg_A,symbol_leg_B])

This beta (denoted as β*) is for the position: CSCO − β* × MSFT.

# Get the beta for hedging Leg B (CSCO) with Leg A (MSFT)
# Note the order: index=Leg B, column=Leg A
url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/beta?token=demo"
betas = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split') / 100.0
print('Beta for CSCO - β* * MSFT. β*:', betas.loc[symbol_leg_B, symbol_leg_A])
# Note: Beta(A, B) is generally NOT equal to 1 / Beta(B, A) in the correlation context.

This indicates the tendency towards Mean Reversion ( H < 0.5 ) or Trending behavior ( H > 0.5 ) for the spread between the two assets based on the calculated β-hedge.

url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/hurst?token=demo"
hurst_exponents = pd.read_json(url,
                    storage_options = {"User-Agent": "api"},
                    orient='split') / 100.0
print('Hurst Exponent:', hurst_exponents.loc[symbol_leg_A,symbol_leg_B])

This estimates the typical bid-ask spread if the two-legged hedged position MSFT − β × CSCO were treated as a single synthetic instrument.

url = "https://api.corrgrid.com/v2/2025-02-26/corr/raw/bidask_spread?token=demo"
bidask_spreads = pd.read_json(url,
                    storage_options = {"User-Agent": "api"},
                    orient='split') / 1000.0
print('Effective Bid-Ask Spread:', bidask_spreads.loc[symbol_leg_A,symbol_leg_B])

Available Tables² ( …/corr/…):

Examples for Cointegrations (.../coi/raw/...)

import pandas as pd
symbol_leg_A='BRK.A...'
symbol_leg_B='BRK.B...'
url = "https://api.corrgrid.com/v2/2025-02-26/coi/raw/relation?token=demo"
# Divide by multiplier (100.0 for coi relations)
cointegration_matrix = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split') / 100.0
# The resulting `cointegration_matrix` DataFrame contains the 'Cointegration Strength' (from Johansen test max eigenvalue).
# A value of 0 indicates that cointegration was not detected or was statistically insignificant.
print('BRK.A ~ BRK.B cointegration: ',cointegration_matrix.loc[symbol_leg_A,symbol_leg_B])

This hr is derived from the Johansen test and is used to form the stationary spread: BRK.A − hr × BRK.B.

import pandas as pd
symbol_leg_A='BRK.A...'
symbol_leg_B='BRK.B...'
url = "https://api.corrgrid.com/v2/2025-02-26/coi/raw/hedge_ratio?token=demo"
# Divide by multiplier (100.0 for coi hedge ratios)
hedge_ratios = pd.read_json(url, storage_options = {"User-Agent": "api"}, orient='split') / 100.0
print('BRK.A - hr * BRK.B hedge ratio. hr =: ',hedge_ratios.loc[symbol_leg_A,symbol_leg_B])
# Note: If cointegration strength is 0, this hedge ratio is set to 0.

Available Tables² (.../coi/...):

import pandas as pd

url = "https://api.corrgrid.com/v2/2025-02-26/instruments?token=demo"

instruments = pd.read_json(url,  storage_options = {"User-Agent": "api"})
symbol_to_PITSymbol = instruments.set_index('symbol')['PITsymbol'].to_dict()
symbol_leg_A = symbol_to_PITSymbol['MSFT']
symbol_leg_B = symbol_to_PITSymbol['CSCO']
print('PITSymbol for MSFT as of 2025-02-26', symbol_leg_A)
print('PITSymbol for CSCO as of 2025-02-26', symbol_leg_B)