Vault data#
This document describes the vault data format available over Trading Strategy API.
Vault datasets are
Vault metadata and real-time summaries
Historical returns data
Access plans and files#
See the Trading Strategy vault data pricing page for the current Free and Pro plan terms.
The downloadable dataset files are listed on the Vault datasets page.
File |
Plan |
Format |
Description |
|---|---|---|---|
|
Free |
JSON |
Limited sample of vault metadata covering only Ethereum vaults. Uses the same vault metadata schema as the Pro file. |
|
Free |
Parquet |
Limited sample of historical price/TVL data covering only Ethereum vaults. Uses the same historical schema as the Pro file. |
|
Professional / Pro |
JSON |
Full tracked vault metadata and metric summary file for paid subscribers. |
|
Professional / Pro |
Parquet |
Full tracked vault historical share price, TVL and state file for paid subscribers. |
The schema descriptions below apply to both Free sample files and Professional / Pro full files. The difference is dataset coverage and access control, not the column or field meaning.
How to download#
Download links and curl examples are available on the
Vault datasets download page.
Professional / Pro downloads require an API key. Free sample files can be downloaded from the same dataset catalogue.
Example data analysis#
This section is intended for LLMs and automation agents as a set of concrete examples for extracting vault data from the downloaded files. The examples assume only basic Python packages are installed: Pandas with Parquet reading support, plus Python’s standard library.
Use vault-metadata.json and vault-historical.parquet for Professional / Pro
analysis. For the Free plan, use vault-metadata.sample.json and
vault-historical.sample.parquet; the code is the same, but the sample files only
cover Ethereum vaults.
Load the files#
import json
from pathlib import Path
import pandas as pd
data_dir = Path(".")
metadata_path = data_dir / "vault-metadata.json"
historical_path = data_dir / "vault-historical.parquet"
with metadata_path.open("r", encoding="utf-8") as f:
metadata = json.load(f)
vaults = pd.DataFrame(metadata["vaults"])
prices = pd.read_parquet(historical_path)
if "timestamp" in prices.columns:
prices["timestamp"] = pd.to_datetime(prices["timestamp"])
Get all USDC-denominated vaults#
Use normalised_denomination for token-symbol filtering, because wrapped or
bridged token symbols may be normalised to a canonical symbol.
usdc_vaults = vaults[
vaults["normalised_denomination"].str.upper().eq("USDC")
].copy()
cols = [
"name",
"chain",
"protocol",
"curator_name",
"current_nav",
"three_months_cagr",
"trading_strategy_link",
]
usdc_vaults = usdc_vaults.sort_values("current_nav", ascending=False)
print(usdc_vaults[cols].head(25).to_string(index=False))
Chart historical returns for a Spark vault#
This example finds the largest Spark vault by current TVL, loads its historical share price series, converts it to cumulative returns, and displays it as a chart.
spark_vaults = vaults[
vaults["protocol"].str.contains("Spark", case=False, na=False)
| vaults["name"].str.contains("Spark", case=False, na=False)
].copy()
spark_vaults = spark_vaults.sort_values("current_nav", ascending=False)
spark = spark_vaults.iloc[0]
spark_prices = prices[prices["id"].eq(spark["id"])].copy()
spark_prices = spark_prices.sort_values("timestamp")
spark_prices["returns"] = (
spark_prices["share_price"] / spark_prices["share_price"].iloc[0] - 1.0
)
ax = spark_prices.plot(
x="timestamp",
y="returns",
title=f"{spark['name']} cumulative return",
grid=True,
)
ax.set_ylabel("Return")
Get all Gauntlet-curated vaults#
This example lists vaults curated by Gauntlet, sorted by 3-month annualised return.
trading_strategy_link is the Trading Strategy vault page URL.
gauntlet = vaults[
vaults["curator_slug"].eq("gauntlet")
| vaults["curator_name"].str.contains("Gauntlet", case=False, na=False)
].copy()
table = gauntlet[
[
"name",
"chain",
"trading_strategy_link",
"current_nav",
"three_months_cagr",
]
].rename(
columns={
"trading_strategy_link": "link",
"current_nav": "current_tvl",
"three_months_cagr": "three_months_annualised_return",
}
)
table = table.sort_values(
"three_months_annualised_return",
ascending=False,
na_position="last",
)
print(table.to_string(index=False))
30-day return correlation for top Hyperliquid Hypercore vaults#
This example selects the top 10 Hypercore vaults by TVL, with a minimum TVL of
2,000,000 USD, then calculates a 30-day correlation matrix from daily returns.
Hypercore native vaults use synthetic chain id 9999.
hypercore = vaults[
vaults["chain_id"].eq(9999)
& vaults["current_nav"].ge(2_000_000)
].copy()
top_hypercore = hypercore.sort_values(
"current_nav",
ascending=False,
).head(10)
top_ids = top_hypercore["id"].tolist()
hp = prices[prices["id"].isin(top_ids)].copy()
hp = hp.sort_values(["id", "timestamp"])
daily_share_price = (
hp.pivot_table(
index="timestamp",
columns="id",
values="share_price",
aggfunc="last",
)
.resample("D")
.last()
.ffill()
)
daily_returns = daily_share_price.pct_change().tail(30)
corr = daily_returns.corr()
id_to_name = top_hypercore.set_index("id")["name"].to_dict()
corr = corr.rename(index=id_to_name, columns=id_to_name)
print(corr.round(3).to_string())
Vault metadata format#
The vault metadata schema applies to both vault-metadata.sample.json and
vault-metadata.json. The sample file has limited Ethereum-only coverage; the
Professional / Pro file contains the full tracked dataset.
The vault metadata contains descriptions of all vaults.
The vault metadata is served as a JSON file.
The top-level JSON object has the following shape:
Key |
Description |
|---|---|
|
ISO 8601 UTC timestamp when the export was generated. |
|
Export provenance metadata. Currently contains |
|
Core3 protocol risk intelligence keyed by protocol slug. Only protocols present in exported vaults are included. |
|
Curator metadata keyed by curator slug. Includes identity fields, logo URLs and recent feed entries when available. |
|
List of per-vault metric records documented below. |
The metadata.version fields may be null when the exporter runs outside a Docker image
that was stamped with git version information.
Per-vault field descriptions:
Key |
Label |
Description |
|---|---|---|
|
Name |
Human‑readable vault name. May include chain information to ensure uniqueness. |
|
Vault Slug |
URL‑safe slug for the vault name, used in links and identifiers. |
|
Protocol Slug |
URL‑safe slug for the protocol name (e.g., |
|
Curator Slug |
Slug identifying the vault curator, or |
|
Curator Name |
Human‑readable curator name, or |
|
Protocol Curator |
Boolean indicating whether the curator is the protocol itself (not a third party). |
|
Share Token Address |
On‑chain address of the vault’s ERC‑20 share token. Usually the vault contract address itself. |
|
Share Token Decimals |
ERC‑20 decimals of the vault share token. Do not default a missing value to 18. |
|
Denomination Token Addr. |
On‑chain address of the denomination (underlying) token. |
|
Denomination Decimals |
ERC‑20 decimals of the denomination token. Needed for converting human token amounts to raw integer amounts. |
|
Lifetime Return (Gross) |
All‑time gross return from first to last price as a decimal fraction (e.g., 0.10 = 10%). |
|
Lifetime Return (Net) |
All‑time net return after fees as a decimal fraction. Present only when fee data is available. |
|
CAGR (Gross) |
Annualised gross return (Compound Annual Growth Rate) over the full history. |
|
CAGR (Net) |
Annualised net return after fees over the full history. |
|
3M Return (Gross) |
Absolute gross return over the last ~90 days as a decimal fraction. |
|
3M Return (Net) |
Absolute net return over the last ~90 days after fees as a decimal fraction. |
|
3M CAGR (Gross) |
Annualised gross return computed from the last ~90 days window. |
|
3M CAGR (Net) |
Annualised net return after fees computed from the last ~90 days window. |
|
3M Sharpe Ratio (Gross) |
Sharpe ratio over the last ~90 days using daily returns annualised to 365. Higher indicates better risk‑adjusted performance. |
|
3M Sharpe Ratio (Net) |
Net Sharpe ratio over the last ~90 days. Currently calculated from the same daily series as gross and may be identical. |
|
3M Volatility (Ann.) |
Annualised volatility over the last ~90 days: daily standard deviation scaled by sqrt(365). |
|
1M Return (Gross) |
Absolute gross return over the last ~30 days as a decimal fraction. |
|
1M Return (Net) |
Absolute net return over the last ~30 days after fees as a decimal fraction. |
|
1M CAGR (Gross) |
Annualised gross return computed from the last ~30 days window. |
|
1M CAGR (Net) |
Annualised net return after fees computed from the last ~30 days window. |
|
Denomination |
Underlying denomination token (e.g., USDC). Indicates the unit of account for share price and TVL. |
|
Normalised Denomination |
Canonical token symbol after normalisation (e.g., |
|
Denomination Slug |
Lower‑case slug of the normalised denomination, used for filtering. |
|
Share Token |
The vault’s share token identifier (symbol or address), representing depositor shares. |
|
Chain |
Human‑readable blockchain name (e.g., Ethereum, Arbitrum). |
|
Peak TVL/NAV |
All‑time high TVL by the vault. Reported in the denomination currency. |
|
Current TVL/NAV |
Latest TVL by the vault. Reported in the denomination currency. |
|
Age (Years) |
Vault observation window length in years from first to last data point. |
|
Management Fee |
Annual management fee as a decimal (e.g., 0.02 = 2%). May be missing if not detected. |
|
Management Fee Alias |
JSON compatibility alias for |
|
Performance Fee |
Performance fee as a decimal (e.g., 0.20 = 20% of profits). May be missing if not detected. |
|
Performance Fee Alias |
JSON compatibility alias for |
|
Deposit Fee |
Fee applied on deposits as a decimal (e.g., 0.01 = 1%). May be null if no fee. |
|
Withdrawal Fee |
Fee applied on withdrawals as a decimal (e.g., 0.01 = 1%). May be null if no fee. |
|
Fee Mode |
How fees are applied: |
|
Fee Internalised |
Boolean shorthand: |
|
Gross Fee Structure |
Fee object before protocol-specific net-fee adjustments. Contains management, performance, deposit and withdrawal fee fields. |
|
Net Fee Structure |
Investor-visible fee object after protocol-specific adjustments. |
|
Fee Label |
Human‑readable fee summary, e.g., |
|
Lock‑up (Estimated) |
Estimated lock‑up period before funds can be withdrawn. May be zero or missing. |
|
Deposit/Withdraw Events |
Total number of observed deposit and redeem events for the vault. |
|
Protocol |
Name of the protocol implementing the vault (e.g., Yearn, Beefy). |
|
Risk (Category) |
Technical risk classification object; renderable to a human label via its API. |
|
Risk (Numeric) |
Numeric representation of the technical risk category for sorting or filtering. |
|
Poll Frequency |
Latest adaptive vault scan cycle or poll frequency, e.g. |
|
Vault ID |
Unique identifier combining chain and address ( |
|
Start Date |
Timestamp of the first available price observation used in metrics. |
|
End Date |
Timestamp of the last available price observation used in metrics. |
|
Address |
Vault contract address on the blockchain. |
|
Chain ID |
Numeric EVM chain identifier (e.g., 1 for Ethereum). |
|
Stablecoin‑Like |
Boolean indicating whether the vault is denominated in a stablecoin-like token (could be yield bearing). |
|
First Updated At |
Timestamp of the earliest recorded on‑chain observation for this vault. |
|
First Updated Block |
Block number corresponding to the earliest recorded observation. |
|
Last Updated At |
Timestamp of the latest recorded on‑chain observation for this vault. |
|
Last Updated Block |
Block number corresponding to the latest recorded observation. |
|
Last Share Price |
Most recent share price observation in the denomination currency. |
|
1M Sample Start |
Actual timestamp of the first sample used for the legacy one-month metrics. |
|
1M Sample End |
Actual timestamp of the last sample used for the legacy one-month metrics. |
|
1M Samples |
Number of raw samples used for the legacy one-month metrics. |
|
3M Sample Start |
Actual timestamp of the first sample used for the legacy three-month metrics. |
|
3M Sample End |
Actual timestamp of the last sample used for the legacy three-month metrics. |
|
3M Samples |
Number of raw samples used for the legacy three-month metrics. |
|
Lifetime Sample Start |
Actual timestamp of the first sample used for lifetime metrics. |
|
Lifetime Sample End |
Actual timestamp of the last sample used for lifetime metrics. |
|
Lifetime Samples |
Number of raw samples used for lifetime metrics. |
|
Detected Features |
List of detected vault features (e.g., ERC‑4626/7540 capabilities) as feature names. |
|
Vault Flags |
Set of VaultFlag values indicating vault status (e.g., |
|
Notes |
Human‑readable note text for the vault (e.g., risk warnings, Morpho flag summaries). May be |
|
Link |
URL to the vault on the protocol’s website. May be |
|
Trading Strategy Link |
URL to the vault page on tradingstrategy.ai. May be |
|
Deposit Closed Reason |
Reason why deposits are closed (e.g., |
|
Redemption Closed Reason |
Reason why redemptions are closed. Empty string if redemptions are open. |
|
Deposit Next Open |
Estimated timestamp when deposits will next open. |
|
Redemption Next Open |
Estimated timestamp when redemptions will next open. |
|
Available Liquidity |
Available liquidity for withdrawals in the denomination currency (lending vaults). |
|
Utilisation |
Current utilisation ratio (0.0–1.0) for lending vaults. |
|
Leader Fraction |
Fraction of vault assets controlled by the leader (Hypercore vaults). |
|
Leader Commission |
Commission rate charged by the vault leader (Hypercore). |
|
Follower Count |
Number of followers in a Hypercore leader vault. |
|
Account PnL |
Cumulative PnL of the vault leader account (Hypercore). |
|
Cumulative Volume |
Cumulative trading volume of the vault (Hypercore). |
|
Netflow Metrics |
List of NetflowMetrics objects for 1d, 7d, 30d deposit/withdrawal flows. |
|
Description |
Long‑form vault description from offchain metadata (Euler, Lagoon, etc.). |
|
Short Description |
Brief vault description from offchain metadata. |
|
Manual Review Status |
Manual review decision (e.g., |
|
Core3 Risk Summary |
Compact per-vault Core3 risk summary for the vault protocol, or |
|
Denomination Rate |
Stablecoin rate and depeg metadata for the denomination token. Includes USD rate fields and native/source currency cross-rates. |
|
Protocol Extension Data |
Protocol‑specific extension dict. See other_data and Morpho flags below. |
|
Period Results |
List of PeriodMetrics objects for 1W, 1M, 3M, 6M, 1Y, and lifetime windows. See Structured period metrics below. |
|
First Qualified At |
Sticky export annotation: first time this vault passed the export filter. Only present on sticky-processed rows. |
|
Last Qualified At |
Sticky export annotation: latest time this vault passed the export filter. Only present on sticky-processed rows. |
|
Sticky Export |
|
|
Stale Export |
|
|
Sticky Reason |
Reason for sticky inclusion, currently |
|
Stale Current Row |
|
|
Risk Possibly Stale |
|
Structured period metrics#
In addition to the legacy flat fields (three_months_cagr, one_month_returns, etc.), each vault record
includes a period_results list containing
PeriodMetrics
objects for six standard lookback windows: 1W, 1M, 3M, 6M, 1Y, and lifetime.
Each PeriodMetrics object contains:
Field |
Description |
|---|---|
|
Period label ( |
|
Error string if metrics could not be calculated (e.g., insufficient data), otherwise |
|
Timestamp when the period’s start share price was sampled. |
|
Timestamp when the period’s end share price was sampled. |
|
Actual first raw sample timestamp used for the period. May differ from |
|
Actual last raw sample timestamp used for the period. |
|
Share price at the beginning of the period. |
|
Share price at the end of the period. |
|
Absolute gross return over the period as a decimal fraction. |
|
Absolute net return after fees over the period as a decimal fraction. |
|
Annualised gross CAGR over the period. |
|
Annualised net CAGR after fees over the period. |
|
Annualised volatility based on daily returns. |
|
Sharpe ratio for the period. |
|
Maximum drawdown during the period as a decimal fraction. |
|
TVL at the start of the period in denomination currency. |
|
TVL at the end of the period in denomination currency. |
|
Minimum TVL observed during the period. |
|
Maximum TVL observed during the period. |
|
Rank among all vaults (1 = best), based on CAGR. Requires minimum $50,000 TVL. |
|
Rank among vaults on the same chain (1 = best). Requires minimum $10,000 TVL. |
|
Rank among vaults in the same protocol (1 = best). Requires minimum $10,000 TVL. |
|
Average utilisation over the period (lending vaults only, 0.0–1.0). |
|
Number of raw (hourly) data points used. |
|
Number of daily data points used for volatility/Sharpe calculation. |
Rankings are calculated by calculate_vault_rankings() and use net CAGR (falling back to gross when net is unavailable). Vaults are excluded from rankings if they are blacklisted, have zero/NaN CAGR, or fall below the TVL thresholds.
other_data field for vault-protocol specific metadata#
The other_data field is a protocol‑specific extension dict included in every vault record.
It contains generic display warning hints and protocol-specific details. Future protocols should
add their own keys here rather than adding top‑level fields.
Generic keys:
Key |
Description |
|---|---|
|
UI-friendly warning entries with |
The Morpho‑specific keys are sourced from the Morpho Blue API via analyze_morpho_flags() and the MorphoFlagAnalytics dataclass:
Key |
Description |
|---|---|
|
List of vault‑level governance warning type strings from the Morpho Blue API. Example: |
|
List of market‑level risk warning type strings from the vault’s underlying Morpho market allocations.
Example: |
|
Combined RED‑level warning types across vault and market warnings. Non‑empty when |
|
Combined YELLOW‑level warning types. YELLOW flags do not trigger |
When any RED‑level flags are present, the vault is automatically blacklisted
(risk set to blacklisted) and the
VaultFlag.morpho_issues
flag is added to the flags set.
Historical vault data#
The historical vault data schema applies to both vault-historical.sample.parquet
and vault-historical.parquet. The sample file has limited Ethereum-only coverage;
the Professional / Pro file contains the full tracked dataset.
Historical vault data is the past performance metrics of a vault.
Historical data is served as a compressed Parquet file. The pipeline has two related schemas:
Raw scanner rows are written to
vault-prices-1h.parquetusing the canonicalVaultHistoricalRead.to_pyarrow_schema()columns.The published historical dataset is the cleaned/enriched Parquet output. It keeps the raw scanner columns, preserves native protocol extension columns, adds metadata columns such as
idandprotocol, and computes return columns such asreturns_1h.
When both share_price and raw_share_price are present, use share_price for
analytics. raw_share_price preserves the original scanner/API value before cleaning
and outlier fixes.
General columns (all protocols)#
These columns are present for every vault in the published cleaned dataset. Some columns
(id, name, event_count, protocol, returns_1h, deposit_closed_reason
and raw_share_price) are added by the cleaning pipeline and are not part of the raw
EVM scanner writer schema.
Column |
Description |
|---|---|
|
EVM chain id. Native protocols use synthetic ids: |
|
Vault address, lowercase. Format varies: |
|
Block number of the on-chain read. Synthetic sequence number for native protocols. |
|
Naive UTC timestamp (also the DatetimeIndex). |
|
Share price in denomination token units. Read from contract for ERC-4626; from API for GRVT, Lighter, Hibachi; internally calculated for Hypercore (see note below). |
|
Original share price before cleaning/outlier adjustments. Use |
|
Total assets under management (TVL) in denomination token units. |
|
Total supply of vault share tokens. |
|
Performance fee at time of read (e.g. 0.20 = 20%). NaN if unknown. |
|
Management fee at time of read (e.g. 0.02 = 2%). NaN if unknown. |
|
Comma-separated RPC error messages (e.g. |
|
Dynamic poll frequency (e.g. |
|
Vault identifier: |
|
Human-readable vault name (unique within the dataset). |
|
Total deposit + redeem events observed for this vault. |
|
Protocol name (e.g. |
|
Return as |
|
Why deposits are closed (e.g. |
|
When this row was written/fetched (naive UTC). NaT for old data. |
ERC-4626 only columns#
These columns come from on-chain ERC-4626 contract calls and are NaN or empty for native protocols.
Column |
Description |
|---|---|
|
Maximum deposit amount allowed ( |
|
Maximum redeem amount allowed ( |
|
Whether deposits were open: |
|
Whether redemptions were open: |
|
Whether the vault was actively trading. Currently only D2 Finance. |
Lending protocol only columns#
These columns are populated for lending protocol vaults (IPOR, Euler, Morpho, Gearbox, Silo, etc.) and NaN for other protocols.
Column |
Description |
|---|---|
|
Available liquidity for immediate withdrawal in denomination token units. |
|
Utilisation ratio (0.0–1.0). Caution: this measures capital deployment, not redeemable liquidity. Multi-market aggregators (Morpho, Euler Earn, IPOR) can show high utilisation yet have substantial instantly redeemable liquidity in underlying markets. |
Hypercore only columns#
These columns are populated for native Hyperliquid vaults (chain 9999) and NaN for all others.
Column |
Description |
|---|---|
|
Fraction of vault assets controlled by the leader (0.0–1.0). |
|
Commission rate charged by the vault leader (0.0–1.0). |
|
Number of followers in the vault. |
|
Cumulative PnL of the vault leader account in USD. |
|
Cumulative trading volume of the vault in USD. |
Native protocol flow columns#
These columns are populated for native protocols with daily deposit/withdrawal data (Hypercore, GRVT, Lighter, Hibachi) and NaN for ERC-4626 vaults.
Column |
Description |
|---|---|
|
Number of deposit events in the latest day. |
|
Number of withdrawal events in the latest day. |
|
Total USD deposited in the latest day. |
|
Total USD withdrawn in the latest day. |
Vault technical risk#
The data contains vault technical risk labels. These are based on the beta vault technical risk framework.
Stablecoin vs. crypto-denominated vaults#
Currently only stablecoin-denominated vault data is available.
Raw data for BTC-nominated and ETH-nominated vault is collected, but not published yet. Ask if needed.