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

Get a list of vaults given a specific filters

get

/v1/vaults

Authorizations

Query parameters

tagsstring · min: 1[]

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

tokenstring · min: 1

Name or symbol of the token to filter by

networkstring · enum

Network name or caip to filter by

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

tvl_minnumber

Minimum TVL in USD to filter by

tvl_maxnumber

Maximum TVL in USD to filter by

transactionalOnlystring · enum

Return only vaults that support transactional endpoints

Options: true, false

transactionalFeaturedOnlystring · enum

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

Options: true, false

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

[
  {
    "address": "text",
    "network": "mainnet"
  }
]

Array of vaults addresses and their networks

Get list of tags present in vaults.fyi database

get

/v1/tags

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/tags' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

[
  "text"
]

Array of tags

Get list of tokens present in vaults.fyi database

get

/v1/tokens

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/tokens' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Array of tokens

Get list of networks present in vaults.fyi database

get

/v1/networks

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/networks' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Array of networks

Get a detailed list of vaults filtered by given parameters

get

/v1/detailed/vaults

Authorizations

Query parameters

pageinteger

Page number

per_pageinteger · max: 100 · default: 10

Number of items per page

tagsstring · min: 1[]

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

tokenstring · min: 1

Name or symbol of the token to filter by

networkstring · enum

Network name or caip to filter by

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

tvl_minnumber

Minimum TVL in USD to filter by

tvl_maxnumber

Maximum TVL in USD to filter by

transactionalOnlystring · enum

Return only vaults that support transactional endpoints

Options: true, false

transactionalFeaturedOnlystring · enum

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

Options: true, false

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/detailed/vaults' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response

Get the best vault for the user

get

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

Authorizations

Path parameters

userAddressstringrequired

User wallet address

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/top-vault/{network}/{userAddress}' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response

Get vaults.fyi benchmark rates

get

/v1/benchmarks

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/benchmarks' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response

Get a vault information given a specific address and network

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Object describing the vault

Get APY data for a vault for given interval

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

Query parameters

intervalstring · enumrequired

Resolution of the APY data

Options: 1day, 7day, 30day

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/apy?interval=1day' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Object describing the APY of the vault in current time

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

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

timestampintegerrequired

Timestamp of the historical data

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/historical-tvl/{timestamp}' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Object describing the TVL of the vault in given time

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

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

timestampintegerrequired

Timestamp of the historical data

Query parameters

intervalstring · enumrequired

Resolution of the APY data

Options: 1day, 7day, 30day

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/historical-apy/{timestamp}?interval=1day' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Object describing the APY of the vault in given time

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

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

Query parameters

intervalstring · enumrequired

Resolution of the APY data

Options: 1day, 7day, 30day

from_timestampintegerrequired

Timestamp of the beginning of the range

to_timestampintegerrequired

Timestamp of the end of the range

pageinteger

Page number

per_pageinteger · max: 50 · default: 10

Number of items per page

granularityintegerrequired

Time difference between returned data points

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/historical-apy?interval=1day&from_timestamp=1&to_timestamp=1&granularity=1' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response

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

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

Query parameters

pageinteger

Page number

per_pageinteger · max: 50 · default: 10

Number of items per page

intervalstring · enum · default: 7day

Resolution of the APY data

Options: 1day, 7day, 30day

from_timestampinteger · default: 1737552250

Timestamp of the beginning of the range in epoch seconds

to_timestampinteger · default: 1740144250

Timestamp of the end of the range in epoch seconds

granularityinteger · default: 86400

Time difference between returned data points

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/historical-data' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

{
  "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"
      }
    }
  ]
}

Default Response

Get a list of holder events on a vault

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

holderstringrequired

Address of a holder

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/holder-events/{holder}' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response

Get a holder total returns on a vault

get

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

Authorizations

Path parameters

vaultAddressstringrequired

Address of a vault

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

networkstring · enumrequired

Network name or caip

Options: mainnet, arbitrum, optimism, polygon, base, gnosis, eip155:1, eip155:42161, eip155:10, eip155:137, eip155:8453, eip155:100

holderstringrequired

Address of a holder

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/v1/vaults/{network}/{vaultAddress}/holder-total-returns/{holder}' \
  --header 'x-api-key: YOUR_API_KEY'

200

200

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

Default Response