Insights API endpoints

General endpoints

Access data across all vaults to perform broad market analyses or enhance application features. Fetch lists of vaults, tokens, tags, and networks to quickly integrate a wide range of DeFi assets into your service.

Obtain real-time and historical data on vaults, including detailed TVL and APY metrics.

• List Vaults (GET /v1/vaults): Fetches a list of vaults filtered by tags, tokens, network, and TVL parameters.

• Retrieve Tags (GET /v1/tags): Obtains a list of all tags present in the database, aiding in the categorization and search of vaults.

• Retrieve Tokens (GET /v1/tokens): Retrieves a comprehensive list of tokens, including details like name, symbol, and network, available in the database.

• Retrieve Networks (GET /v1/networks): Gathers a list of all blockchain networks represented in the database, complete with their names and chain IDs.

• Detailed Vaults Data (GET /v1/detailed/vaults): Provides an in-depth look at vaults with detailed information, including financial statistics and operational details, with robust filtering and pagination capabilities.

• Benchmarks (GET /v1/benchmarks): Provides benchmark data related to the vaults.fyi USD benchmark rate and vaults.fyi ETH benchmark rate.

Vaults endpoints

These endpoints are essential for detailed insights into the performance and statistics of a single vault. Each endpoint within the Vault Endpoints section provides access to in-depth vault-specific data. The endpoints provide granular control over the data retrieved, ensuring that the information can be as broad or as detailed as required for the user's purpose.

• Vault Information (GET /v1/vaults/{network}/{vaultAddress}): Provides comprehensive details about a specific vault, including its address, network, TVL, and other operational data.

• Vault APY (GET /v1/vaults/{network}/{vaultAddress}/apy): Retrieves the current APY data for a vault over various intervals, such as 1 day, 7 days, or 30 days.

• Vault Historical TVL (GET /v1/vaults/{network}/{vaultAddress}/historical-tvl/{timestamp}): Offers historical TVL information for a vault based on the closest block time to a given timestamp.

• Vault Historical APY (GET /v1/vaults/{network}/{vaultAddress}/historical-apy/{timestamp}): Fetches APY data from the past for a specific vault, corresponding to the closest timestamp available.

Vaults PRO endpoints

The following endpoints provide rich historical data and are available to premium subscribers. Get comprehensive historical datasets in a single call.

Contact us to learn more.

• Vault Range Historical APY (GET /v1/vaults/{network}/{vaultAddress}/historical-apy): Provides a range of historical APY data points for a vault, between specified start and end timestamps, with configurable granularity.

• Vault Range Historical DATA (GET /v1/vaults/{network}/{vaultAddress}/historical-data): Provides detailed TVL and APY data for a vault, between specified start and end timestamps, with configurable granularity.

---

Endpoints

General

get

Get list of tags present in vaults.fyi database

Authorizations

apiKey

x-api-keystringRequired

Responses

200

Array of tags

application/json

string[]Optional

Array of tags

get

/v1/tags

HTTPcURLJavaScriptPython

GET /v1/tags HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Array of tags

[
  "text"
]

get

Get list of tokens present in vaults.fyi database

Authorizations

apiKey

x-api-keystringRequired

Responses

200

Array of tokens

application/json

Array of tokens

assetAddressstringRequired

Address of the token

assetCaipstringRequiredPattern: ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$

decimalsnumberRequired

Decimals of the token

namestringRequired

Name of the token

symbolstringRequired

Symbol of the token

get

/v1/tokens

HTTPcURLJavaScriptPython

GET /v1/tokens HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Array of tokens

[
  {
    "assetAddress": "text",
    "assetCaip": "text",
    "decimals": 1,
    "name": "text",
    "network": {
      "name": "mainnet",
      "chainId": 1
    },
    "symbol": "text"
  }
]

get

Get list of networks present in vaults.fyi database

Authorizations

apiKey

x-api-keystringRequired

Responses

200

Array of networks

application/json

Array of networks

namestringRequired

Name of the network

chainIdnumberRequired

Chain ID of the network

get

/v1/networks

HTTPcURLJavaScriptPython

GET /v1/networks HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Array of networks

[
  {
    "name": "text",
    "chainId": 1
  }
]

get

Get a detailed list of vaults filtered by given parameters

Authorizations

apiKey

x-api-keystringRequired

Query parameters

pageintegerOptional

Page number

Default: 0

per_pageinteger · max: 500Optional

Number of items per page

Default: 10

tagsstring[]Optional

List of tags to filter by all of the tags must be present on the vault to be included in the results

tokenstring · min: 1Optional

Name or symbol of the token to filter by

networkstring · enumOptional

Network name or caip to filter by

Possible values:

tvl_minnumberOptional

Minimum TVL in USD to filter by

tvl_maxnumberOptional

Maximum TVL in USD to filter by

transactionalOnlybooleanOptional

Return only vaults that support transactional endpoints

transactionalFeaturedOnlybooleanOptional

Return only vaults that support transactional endpoints and are featured in app.vaults.fyi

Responses

200

Default Response

application/json

next_pageintegerOptional

Next page number

get

/v1/detailed/vaults

HTTPcURLJavaScriptPython

GET /v1/detailed/vaults HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "next_page": 1,
  "data": [
    {
      "name": "text",
      "address": "text",
      "network": "mainnet",
      "protocol": "text",
      "tvlDetails": {
        "tvlNative": "text",
        "tvlUsd": "text",
        "lockedNative": "text",
        "lockedUsd": "text",
        "liquidNative": "text",
        "liquidUsd": "text"
      },
      "numberOfHolders": 1,
      "lendLink": "text",
      "tags": [
        "text"
      ],
      "token": {
        "name": "text",
        "assetAddress": "text",
        "assetCaip": "text",
        "symbol": "text",
        "decimals": 1
      },
      "apy": {
        "base": {
          "1day": 1,
          "7day": 1,
          "30day": 1
        },
        "rewards": {
          "1day": 1,
          "7day": 1,
          "30day": 1
        },
        "total": {
          "1day": 1,
          "7day": 1,
          "30day": 1
        }
      },
      "description": "text",
      "additionalIncentives": "text",
      "rewards": [
        {
          "apy": {
            "1day": 1,
            "7day": 1,
            "30day": 1
          },
          "assetPriceInUsd": 1,
          "asset": {
            "name": "text",
            "assetAddress": "text",
            "assetCaip": "text",
            "symbol": "text",
            "decimals": 1
          }
        }
      ],
      "isTransactional": true,
      "score": {
        "vaultScore": 1,
        "vaultTvlScore": 1,
        "protocolTvlScore": 1,
        "holderScore": 1,
        "networkScore": 1,
        "assetScore": 1
      },
      "children": [
        "text"
      ]
    }
  ]
}

get

Get the best vault for the user

Authorizations

apiKey

x-api-keystringRequired

Path parameters

userAddressstringRequired

User wallet address

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

Responses

200

Default Response

application/json

userAddressstringRequired

User wallet address

Pattern: ^0x[a-fA-F0-9]{40}$

get

/v1/top-vault/{network}/{userAddress}

HTTPcURLJavaScriptPython

GET /v1/top-vault/{network}/{userAddress} HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "userAddress": "text",
  "bestVault": {
    "name": "text",
    "protocol": {
      "name": "text",
      "product": "text",
      "version": "text"
    },
    "vaultAddress": "text",
    "networkName": "mainnet",
    "tvlInUsd": 1,
    "apy": 1,
    "projectedEarnings": 1,
    "asset": {
      "assetAddress": "text",
      "decimals": 1,
      "name": "text",
      "symbol": "text"
    }
  },
  "bestEthVault": {
    "name": "text",
    "protocol": {
      "name": "text",
      "product": "text",
      "version": "text"
    },
    "vaultAddress": "text",
    "networkName": "mainnet",
    "tvlInUsd": 1,
    "apy": 1,
    "projectedEarnings": 1
  }
}

get

Get vaults.fyi benchmark rates

Authorizations

apiKey

x-api-keystringRequired

Responses

200

Default Response

application/json

get

/v1/benchmarks

HTTPcURLJavaScriptPython

GET /v1/benchmarks HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "usd": {
    "name": "text",
    "apy": {
      "1day": 1,
      "7day": 1,
      "30day": 1
    },
    "vaults": [
      {
        "name": "text",
        "network": "mainnet",
        "address": "text"
      }
    ]
  },
  "eth": {
    "name": "text",
    "apy": {
      "1day": 1,
      "7day": 1,
      "30day": 1
    },
    "vaults": [
      {
        "name": "text",
        "network": "mainnet",
        "address": "text"
      }
    ]
  }
}

get

Get a vault information given a specific address and network

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

Responses

200

Object describing the vault

application/json

Object describing the vault

namestringRequired

Name of the vault

addressstringRequired

Address of a vault

networkstring · enumRequired

Network name on which vault exists

Possible values:

protocolstringRequired

Protocol name to which the vault belongs

numberOfHoldersnumber · nullableRequired

Number of holders of vault LP tokens

lendLinkstring · nullableRequired

Lend link of the vault

tagsstring[]Required

Array of tags present on vault

descriptionstring · nullableRequired

Description of the vault

additionalIncentivesstring · nullableRequired

Additional incentives of the vault

isTransactionalbooleanRequired

Boolean indicating if the vault is transactional

childrenstring[]Optional

Array of derivative vaults

assetPriceInUsdnumberRequired

Price of the underlying vault asset in USD with 1e8 precision

holdersTotalBalancestringRequired

Total balance of all holders of vault LP tokens

get

/v1/vaults/{network}/{vaultAddress}/

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/ HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Object describing the vault

{
  "name": "text",
  "address": "text",
  "network": "mainnet",
  "protocol": "text",
  "tvlDetails": {
    "tvlNative": "text",
    "tvlUsd": "text",
    "lockedNative": "text",
    "lockedUsd": "text",
    "liquidNative": "text",
    "liquidUsd": "text"
  },
  "numberOfHolders": 1,
  "lendLink": "text",
  "tags": [
    "text"
  ],
  "token": {
    "name": "text",
    "assetAddress": "text",
    "assetCaip": "text",
    "symbol": "text",
    "decimals": 1
  },
  "apy": {
    "base": {
      "1day": 1,
      "7day": 1,
      "30day": 1
    },
    "rewards": {
      "1day": 1,
      "7day": 1,
      "30day": 1
    },
    "total": {
      "1day": 1,
      "7day": 1,
      "30day": 1
    }
  },
  "description": "text",
  "additionalIncentives": "text",
  "rewards": [
    {
      "apy": {
        "1day": 1,
        "7day": 1,
        "30day": 1
      },
      "assetPriceInUsd": 1,
      "asset": {
        "name": "text",
        "assetAddress": "text",
        "assetCaip": "text",
        "symbol": "text",
        "decimals": 1
      }
    }
  ],
  "isTransactional": true,
  "score": {
    "vaultScore": 1,
    "vaultTvlScore": 1,
    "protocolTvlScore": 1,
    "holderScore": 1,
    "networkScore": 1,
    "assetScore": 1
  },
  "children": [
    "text"
  ],
  "assetPriceInUsd": 1,
  "topHolders": [
    {
      "address": "text",
      "balance": "text"
    }
  ],
  "holdersTotalBalance": "text"
}

get

Get APY data for a vault for given interval

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

Query parameters

intervalstring · enumRequired

Resolution of the APY data

Possible values:

Responses

200

Object describing the APY of the vault in current time

application/json

Object describing the APY of the vault in current time

basenumberRequired

APY of the vault in BIPS

rewardsnumberOptional

APY of the vault rewards in BIPS

totalnumberRequired

Sum of base APY of the vault and rewards in BIPS

get

/v1/vaults/{network}/{vaultAddress}/apy

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/apy?interval=1day HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Object describing the APY of the vault in current time

{
  "base": 1,
  "rewards": 1,
  "total": 1
}

get

Get historical TVL data for a vault for block with closest timestamp to the given one

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

timestampintegerRequired

Timestamp of the historical data

Responses

200

Object describing the TVL of the vault in given time

application/json

Object describing the TVL of the vault in given time

timestampnumberRequired

Timestamp of the block for given data

blockNumbernumberRequired

Block number for given data

get

/v1/vaults/{network}/{vaultAddress}/historical-tvl/{timestamp}

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/historical-tvl/{timestamp} HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Object describing the TVL of the vault in given time

{
  "timestamp": 1,
  "blockNumber": 1,
  "tvlDetails": {
    "tvlNative": "text",
    "tvlUsd": "text",
    "lockedNative": "text",
    "lockedUsd": "text",
    "liquidNative": "text",
    "liquidUsd": "text"
  }
}

get

Get historical APY data for a vault for block with closest timestamp to the given one

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

timestampintegerRequired

Timestamp of the historical data

Query parameters

intervalstring · enumRequired

Resolution of the APY data

Possible values:

Responses

200

Object describing the APY of the vault in given time

application/json

Object describing the APY of the vault in given time

timestampnumberRequired

Timestamp of the block for given data

blockNumbernumberRequired

Block number for given data

get

/v1/vaults/{network}/{vaultAddress}/historical-apy/{timestamp}

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/historical-apy/{timestamp}?interval=1day HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Object describing the APY of the vault in given time

{
  "timestamp": 1,
  "blockNumber": 1,
  "apy": {
    "base": 1,
    "rewards": 1,
    "total": 1
  }
}

get

Get historical APY data for a vault for blocks in given timestamp range

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

Query parameters

intervalstring · enumRequired

Resolution of the APY data

Possible values:

from_timestampintegerRequired

Timestamp of the beginning of the range

to_timestampintegerRequired

Timestamp of the end of the range

pageintegerOptional

Page number

Default: 0

per_pageinteger · max: 50Optional

Number of items per page

Default: 10

granularityintegerRequired

Time difference between returned data points

Responses

200

Default Response

application/json

next_pageintegerOptional

Next page number

get

/v1/vaults/{network}/{vaultAddress}/historical-apy

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/historical-apy?interval=1day&from_timestamp=1&to_timestamp=1&granularity=1 HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "next_page": 1,
  "data": [
    {
      "timestamp": 1,
      "blockNumber": 1,
      "apy": {
        "base": 1,
        "rewards": 1,
        "total": 1
      }
    }
  ]
}

get

Get historical APY data for a vault for blocks in given timestamp range

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

Query parameters

pageintegerOptional

Page number

Default: 0

per_pageinteger · max: 10000Optional

Number of items per page

Default: 10

intervalstring · enumOptional

Resolution of the APY data

Default: 7dayPossible values:

from_timestampintegerOptional

Timestamp of the beginning of the range in epoch seconds

Default: 1770222636

to_timestampintegerOptional

Timestamp of the end of the range in epoch seconds

Default: 1772814636

granularityintegerOptional

Time difference between returned data points

Default: 86400

Responses

200

Default Response

application/json

next_pageintegerOptional

Next page number

get

/v1/vaults/{network}/{vaultAddress}/historical-data

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/historical-data HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "next_page": 1,
  "data": [
    {
      "timestamp": 1,
      "blockNumber": 1,
      "apy": {
        "base": 1,
        "rewards": 1,
        "total": 1
      },
      "tvlDetails": {
        "tvlNative": "text",
        "tvlUsd": "text",
        "lockedNative": "text",
        "lockedUsd": "text",
        "liquidNative": "text",
        "liquidUsd": "text"
      }
    }
  ]
}

get

Get a list of holder events on a vault, supported networks: arbitrum, base, mainnet, optimism, polygon, gnosis, celo, swellchain, unichain

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

holderstringRequired

Address of a holder

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Default Response

application/json

get

/v1/vaults/{network}/{vaultAddress}/holder-events/{holder}

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/holder-events/{holder} HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "events": [
    {
      "activity": "Transfer",
      "timestamp": 1,
      "amount": {
        "usd": 1,
        "native": "text"
      },
      "positionValue": {
        "usd": 1,
        "native": "text"
      }
    }
  ]
}

get

Get a holder total returns on a vault, supported networks: arbitrum, base, mainnet, optimism, polygon, gnosis, celo, swellchain, unichain

Authorizations

apiKey

x-api-keystringRequired

Path parameters

vaultAddressstringRequired

Address of a vault

Pattern: ^0x[a-fA-F0-9]{40}$

networkstring · enumRequired

Network name or caip

Possible values:

holderstringRequired

Address of a holder

Pattern: ^0x[a-fA-F0-9]{40}$

Responses

200

Default Response

application/json

usdnumberRequired

nativenumberRequired

get

/v1/vaults/{network}/{vaultAddress}/holder-total-returns/{holder}

HTTPcURLJavaScriptPython

GET /v1/vaults/{network}/{vaultAddress}/holder-total-returns/{holder} HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

200

Default Response

{
  "usd": 1,
  "native": 1
}