Superform currently has over 800 vaults listed across 10 chains. The API provides two entrypoints into the world of vaults - the Get All Vaults endpoint and Get Vault Data endpoint. A vault may belong to a protocol. Since Superform is a decentralized platform, anyone can list any ERC4626 vault and any protocol.

The vault object returned contains several vital pieces of information. Below, we will explain this information and show you what you can do with that data.

Vault Statistics

This part of the vault object contains the most important data. These stats power the graphs found on the vault details page for every vault. Vault statistics are collected every 8 hours in most cases. The APY numbers are then annualized to three different time frames: daily, weekly, and monthly.

apy_now is the APY calculation at the most recent time of collection, representing the 8 hour time frame. apy_daily, apy_weekly, and apy_monthly are the annualized values. apy_day_change, apy_week_change, and apy_month_change are percent values that represent their respective deltas.

The same holds for the Sharpe values - sharpe_day and sharpe_month- and the TVL values.

Lastly, an alternative to the APY metric is provided via Price Per Share. pps holds the price per share with the vault's underlying asset as the unit, while pps_usd holds the same value in USD. PPS is defined as total_assets divided by total_supply. In contrast to the often volatile nature of APY, price per share (PPS) typically exhibits a consistent upward trend over time for most vaults, reflecting the compound growth of the underlying assets. However, PPS changes may be more gradual, driven by the vault's performance and market conditions.

An example of the relationships can be seen on this FLUID USD Coin Vault on Base chart:

The interplay between these metrics can be visualized as follows:

PPS steadily increases, reflecting consistent returns.
APY, represented by a dashed line, may fluctuate significantly as it is sensitive to market dynamics and strategies employed by the vault.
TVL, plotted as a solid line, demonstrates the scale of funds locked in the vault and can impact APY and PPS indirectly through fees, liquidity, and overall efficiency.

Together, these metrics provide a comprehensive picture of the vault's performance and risk-adjusted returns.

Property	Description
`vault_id`	This is a unique identifier for the vault generated off-chain by the Superform backend.
`superform_id`	This is a unique identifier for the vault generated onchain by the SuperformFactory contract upon initial vault listing and superform creation.
`apy_now`	This is an APY value observed over a period of one hour and annualized using the standard formula.
`apy_x`	`apy_day`, `apy_week`, and `apy_month` are observed over their respective time frames and annualized using the standard formula.
`tvl`	The vault's TVL is calculated as `total_assets` multiplied by the underlying asset's price, adjusted by the underlying asset's decimals.
`deltas`	`apy_day_change`, `apy_week_change`, `apy_month_change`, `tvl_day_change`, `tvl_week_change`, and `tvl_month_change` are the deltas calculated over their respective time period.
`sharpe_x`	This calculates the Sharpe ratio for a vault over a given time interval using the standard deviation of APY values.
`pps`	Price Per Share is defined as `(total_assets / 10^asset_decimals) / (total_supply / 10^vault_decimals)`
`pps_usd`	PPS priced in USD

Example Vault Object

To get the vault, you have three options. The path param vaultOrSuperformIDOrContractAddress is self-descriptive. Each vault can be queried in one of three ways:

the contract address is just the hexadecimal string of the vault's on-chain contract address. Our system is case-insensitive, meaning it doesn’t matter if the address is lowercase, uppercase, or mixed. You can submit the address in any format, and the string will be searchable to find the intended vault contract.
the vaultID is Superform's internal representation of the vault in the database. It is useful insofar as other objects, such as the VaultStatistics object, may reference it. The frontend UI also makes ample use of it.
the superformID is a uint256 that is generated by the SuperformFactory upon the creation of the vault during the vault listing flow. It is how this vault is referenced in all on-chain events that take place, e.g. during a cross-chain transaction that touches multiple contracts.

Here is an actual vault object for the Fluid USDC vault on Base. The numbers returned here reflect the state of the vault at the time of writing, 01/06/2025:

{
    "$schema": "https://api.superform.xyz/schemas/Vault.json",
    "superform_id": "53060340969225575574578202921289080472325404311817176524113555",
    "superform_address": "0x57dB74d29604511e0B0472be0e2528fF4c85c693",
    "form_implementation_id": "1",
    "contract_address": "0xf42f5795D9ac7e9D757dB633D693cD548Cfd9169",
    "decimals": 6,
    "symbol": "fUSDC",
    "id": "qnHpBjBfHy7Trug1ElI1U",
    "name": "Fluid USD Coin",
    "protocol_id": "FPx31qQBIrR2mYV71JqkX",
    "protocol": {
        "id": "FPx31qQBIrR2mYV71JqkX",
        "name": "Fluid",
        "description": "An ever-evolving DeFi protocol. The financial system of the future.\n\nEnabling the highest capital efficiency and unbeatable rates.\n\nFluid's innovative features, including its liquidity layer, automated limits, lending and vault protocols, robust oracle system, and DEX protocol, collectively create a revolutionary financial layer poised to redefine how DeFi users interact with the ecosystem. \n",
        "type": "Lending",
        "tagline": "Financial system of the future",
        "is_hidden": false,
        "is_authenticated": true,
        "defillama_id": "",
        "vanity_url": "Fluid",
        "primary_color": "#4E80EE",
        "num_depositors": 13705,
        "status": "",
        "status_message": "",
        "deploy_date": "0001-01-01T00:00:00Z",
        "users": null,
        "audits": null,
        "exploits": null,
        "faq": null,
        "analytics": null,
        "graphics": {
            "icon": "https://superform-celeste.s3.amazonaws.com/dWNPR_urPlRrTaJuWfkpo.png",
            "header": "",
            "avatar": "https://superform-celeste.s3.amazonaws.com/dWNPR_urPlRrTaJuWfkpo.png",
            "watermark": ""
        },
        "links": {
            "website": "https://fluid.instadapp.io/",
            "twitter": "https://twitter.com/0xfluid",
            "discord": "https://discord.com/invite/C76CeZc",
            "telegram": ""
        },
        "chain_ids": null,
        "deployers": null,
        "vaults_amount": 0,
        "tvl": 0,
        "tvl_day_change": 0,
        "tvl_week_change": 0,
        "tvl_month_change": 0,
        "created_at": "2024-04-16T10:40:23.948866Z",
        "updated_at": "2025-01-01T00:45:31.766559Z"
    },
    "chain": {
        "id": 8453,
        "name": "Base",
        "short_name": "base",
        "logo_url": "https://static.debank.com/image/chain/logo_url/base/ccc1513e4f390542c4fb2f4b88ce9579.png",
        "wrapped_token_id": "0x4200000000000000000000000000000000000006"
    },
    "friendly_name": "Fluid USD Coin",
    "description": "The Lending Protocol is the ‘Deposit and Earn’ side of the Fluid protocol. Supply to the Fluid protocol through this simple UX and earn yield on your supplied asset in kind.",
    "yield_type": "Lending",
    "yield_source": "",
    "super_pools": [],
    "has_timelock": false,
    "timelock_duration": 0,
    "timelock_unit": "",
    "external_url": "https://fluid.instadapp.io/lending/8453/USDC",
    "deploy_date": "0001-01-01T00:00:00Z",
    "is_authenticated": false,
    "visibility": "featured",
    "availability": "available",
    "vault_status_message": null,
    "vault_lister": "0x0a87D7b1eb7FF9548d4FFBe1D975bABb3CFb51ed",
    "num_depositors": 71,
    "fees": null,
    "analytics": null,
    "audits": [
        {
            "id": "sKLpTOzA4mPEMqpejFXSq",
            "vault_id": "qnHpBjBfHy7Trug1ElI1U",
            "audit_name": "Audits & Security",
            "audit_link": "https://docs.fluid.instadapp.io/audits-and-security.html",
            "audit_date": "2024-12-04T00:00:00Z",
            "is_deleted": false
        }
    ],
    "exploits": null,
    "has_rewards": false,
    "kyc": null,
    "faq": null,
    "other": null,
    "recommend_vault_share_withdrawal": false,
    "withdrawal_link": "",
    "is_supervault": false,
    "assets": [
        {
            "id": 104,
            "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "name": "USD Coin",
            "symbol": "USDC",
            "image": "https://assets.coingecko.com/coins/images/6319/standard/usdc.png",
            "decimals": 6
        }
    ],
    "rewards": null,
    "superform_stats": null,
    "vault_statistics": {
        "vault_id": "qnHpBjBfHy7Trug1ElI1U",
        "superform_id": "53060340969225575574578202921289080472325404311817176524113555",
        "apy_now": 7.6832,
        "tvl_now": 16232924.1422,
        "sharpe_day": 22.97,
        "sharpe_month": 2.48,
        "apy_day": 10.4178,
        "apy_week": 12.508,
        "apy_month": -1000000,
        "apy_day_change": -8.34,
        "apy_week_change": -35.68,
        "apy_month_change": -1000000,
        "tvl_day_change": -0.66,
        "tvl_week_change": 4.81,
        "tvl_month_change": -0.1,
        "pps": 1.0417476732159983,
        "pps_usd": 1.0427894208892141
    },
    "has_aerc_20_registered": false,
    "created_at": "2024-12-19T04:45:12.245805Z",
    "updated_at": "2025-01-01T01:14:08.521165Z"
}

That's a lot of data, so let's break it down by sections.

Onchain Data

superform_id - unique identifier for this superform at the contract level
superform_address - the address of the superform contract
form_implementation_id - this is another detail mostly internal to the contracts. It will be 1 for most vaults, as most vaults are ERC4626. ERC5115 vaults in listed on Superform in the future will have a value of 5 for this.
contract_address - address of the vault itself
decimals - the number of decimals in the vault
symbol - the symbol of the vault
name - this is the name of the vault as stored on-chain
assets - this is an array of underlying asset for this vault. Most vaults will have only one value here.

That's it for the on-chain data. We won't go over every remaining value, but we'll highlight some of the more salient ones.

Protocol

A vault may belong to a protocol. Since Superform is a decentralized platform, anyone can list any ERC4626 vault, and anyone can list any protocol. Official protocols which have been reviewed by the Superform team will have the is_authenticatedflag set to true and appear as such in the UI. The authentication process for a protocol consists of reaching out to Christian in Discord (croutond) or via email.

If a vault belongs to a protocol, the protocol object will be filled out. Note that some fields will be left empty. For a full protocol object, use the Get Protocol By ID endpoint or Get All Protocols endpoint.

vaults_amount - the number of vaults that belong to this protocol
tvl - protocol TVL
tvl_day_change , tvl_week_change, tvl_month_change - changes in percent of the protocol's TVL across different time intervals
status - not used, reserved for future use
status_message - a message a protocol admin can set that will appear as a status bar at the top of the protocol overview page in the UI
analytics - these are links to Dune charts that a protocol admin can set. If set, they will be rendered in the Insights tab in the UI. See Morpho for an example.

Metadata

The vault will contain metadata fields that are mostly used by the UI. friendly_name is a user-supplied name for the vault, distinct from the immutable name stored on-chain. description and yield_type are also supplied by the user at time of listing. The last bits of optional metadata include the following objects. You can find a description for each in the Get Vault Data docs:

fees
analytics
audits
exploits
kyc
faq
other
recommend_vault_share_withdrawal - certain vaults cannot be withdrawn through Superform due to various reasons like timelocks. For these vaults, we set this property to true so that a user is advised in the UI to select to retain the 4626 share upon deposit. In this case, a SuperPosition will not be minted and the user will hold the vault shares directly. See docs here for more details.

Timelock

Some vaults are timelocked. If so, the following three properties will have non-zero, non-null values:

has_timelock
timelock_duration
timelock_unit

Rewards

Many vaults, like Morpho, will earn rewards. Some vaults will earn multiple rewards during certain time periods. The rewards array lists all rewards currently live for this vault. The Fluid vault in the example above does not have any. See SuperVault for an example of live rewards.

ERC20

If this vault has an ERC20 registered, has_aerc_20_registered is set to true. That means a user has the option to transmute the ERC115 Superposition to an ERC20 and use a superpool to trade positions without incurring the high fees on mainnet. More info in this wonderful, very detailed Mirror post. If there is a superpool available, the super_poolsarray will contain the chain IDs of any chain(s) that have a superpool with adequate liquidity.

Where to go from here

Once you have the vault object, you can get historical data for that vault by making a request to Get historical vault data endpoint. This endpoint accepts multiple vaultIDs or superformIDs and will return a time series data of the vault statistics described above, across any time frame for which we have data. Generally, data is available from the day the vault was listed on Superform.

You can also use this vault data to make a deposit or withdrawal. See this guide for more details!