Skip to main content
GET
/
alpha
/
historical-balances
/
{userAddress}
/
{timestamp}
List user historical balances
curl --request GET \
  --url https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp} \
  --header 'x-api-key: <api-key>'
import requests

url = "https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}")
  .header("x-api-key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.vaults.fyi/alpha/historical-balances/{userAddress}/{timestamp}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "data": [
    {
      "vaultId": "<string>",
      "address": "<string>",
      "network": {
        "chainId": 123,
        "networkCaip": "<string>"
      },
      "asset": {
        "address": "<string>",
        "assetCaip": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "decimals": 123,
        "assetGroup": "<string>",
        "balanceNative": "<string>",
        "assetLogo": "<string>",
        "assetPriceInUsd": "<string>",
        "balanceUsd": "<string>",
        "unclaimedNative": "<string>",
        "unclaimedUsd": "<string>",
        "positionValueInAsset": "<string>"
      },
      "name": "<string>",
      "protocol": {
        "name": "<string>",
        "displayName": "<string>",
        "product": "<string>",
        "version": "<string>",
        "protocolUrl": "<string>",
        "description": "<string>",
        "protocolLogo": "<string>"
      },
      "additionalAssets": [
        {
          "address": "<string>",
          "assetCaip": "<string>",
          "name": "<string>",
          "symbol": "<string>",
          "decimals": 123,
          "assetGroup": "<string>",
          "balanceNative": "<string>",
          "assetLogo": "<string>",
          "assetPriceInUsd": "<string>",
          "balanceUsd": "<string>",
          "unclaimedNative": "<string>",
          "unclaimedUsd": "<string>",
          "positionValueInAsset": "<string>"
        }
      ],
      "lpToken": {
        "address": "<string>",
        "tokenCaip": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "decimals": 123,
        "balanceNative": "<string>",
        "balanceUsd": "<string>",
        "unclaimedNative": "<string>",
        "unclaimedUsd": "<string>",
        "positionValueInAsset": "<string>",
        "assetPriceInUsd": "<string>"
      },
      "childrenVaults": [
        {
          "vaultId": "<string>",
          "address": "<string>",
          "asset": {
            "address": "<string>",
            "assetCaip": "<string>",
            "name": "<string>",
            "symbol": "<string>",
            "decimals": 123,
            "assetGroup": "<string>",
            "balanceNative": "<string>",
            "assetLogo": "<string>",
            "assetPriceInUsd": "<string>",
            "balanceUsd": "<string>",
            "unclaimedNative": "<string>",
            "unclaimedUsd": "<string>",
            "positionValueInAsset": "<string>"
          },
          "lpToken": {
            "address": "<string>",
            "tokenCaip": "<string>",
            "name": "<string>",
            "symbol": "<string>",
            "decimals": 123,
            "balanceNative": "<string>",
            "balanceUsd": "<string>",
            "unclaimedNative": "<string>",
            "unclaimedUsd": "<string>",
            "positionValueInAsset": "<string>",
            "assetPriceInUsd": "<string>"
          },
          "additionalAssets": [
            {
              "address": "<string>",
              "assetCaip": "<string>",
              "name": "<string>",
              "symbol": "<string>",
              "decimals": 123,
              "assetGroup": "<string>",
              "balanceNative": "<string>",
              "assetLogo": "<string>",
              "assetPriceInUsd": "<string>",
              "balanceUsd": "<string>",
              "unclaimedNative": "<string>",
              "unclaimedUsd": "<string>",
              "positionValueInAsset": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "errors": {
    "unsupportedNetworks": [
      "<string>"
    ],
    "unsupportedAssets": [
      "<string>"
    ],
    "unsupportedProtocols": [
      "<string>"
    ]
  }
}
{
  "statusCode": 123,
  "error": "Bad Request",
  "message": "<string>",
  "errorId": "<string>"
}
{
  "error": "Unauthorized",
  "message": "An API key is required to access this service. Sign up at https://portal.vaults.fyi/signup to generate a key. We offer a Pay-As-You-Go plan so you only pay for what you use, with no commitments.",
  "errorId": "<string>"
}
{
  "x402Version": 123,
  "resource": {
    "url": "<string>",
    "description": "<string>",
    "mimeType": "<string>",
    "serviceName": "<string>",
    "tags": [
      "<string>"
    ],
    "iconUrl": "<string>"
  },
  "error": "<string>",
  "accepts": [
    {
      "scheme": "exact",
      "network": "<string>",
      "amount": "<string>",
      "payTo": "<string>",
      "maxTimeoutSeconds": 123,
      "asset": "<string>",
      "extra": {
        "name": "<string>",
        "version": "<string>"
      }
    }
  ],
  "extensions": {}
}
{
  "error": "Forbidden",
  "message": "This API key has exhausted its available credits. To resume service, please visit https://portal.vaults.fyi/signup to top-up your credits",
  "errorId": "<string>"
}
{
  "error": "Not Found",
  "message": "<string>"
}
{
  "message": "<string>",
  "errorId": "<string>"
}
{
  "statusCode": 123,
  "error": "Unprocessable Entity",
  "message": "<string>",
  "errorId": "<string>"
}
{
  "error": "Internal Server Error",
  "message": "<string>",
  "errorId": "<string>"
}
{
  "statusCode": 123,
  "error": "Service Unavailable",
  "message": "<string>",
  "errorId": "<string>"
}

Authorizations

x-api-key
string
header
required

Path Parameters

userAddress
string
required

User address to fetch historical balances for

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

Unix timestamp (seconds) to fetch balances at

Query Parameters

allowedAssets
string[]

Assets to be included by symbol(ticker).

Minimum string length: 1
disallowedAssets
string[]

Assets to be excluded by symbol(ticker). The parameter is ignored if "allowedAssets" is specified.

Minimum string length: 1
allowedProtocols
string[]

Protocols to be included by name.

Minimum string length: 1
disallowedProtocols
string[]

Protocols to be excluded by name. The parameter is ignored if "allowedProtocols" is specified.

Minimum string length: 1
minTvl
integer
default:100000

Minimum TVL in USD of the vaults to be included

minVaultScore
number

Minimum vault score required for a vault to be included

Required range: x >= 0
onlyTransactional
boolean

Include only vaults that are supported in the transactional interface.

Include only vaults that are featured in app.vaults.fyi

allowCorrupted
boolean
default:false

Allow inclusion of corrupted vaults.

allowVaultsWithWarnings
boolean

Whether to include vaults with warnings. Defaults to true.

allowedNetworks
enum<string>[]

Networks to be included (name or CAIP).

Include only vaults with provided network(name or CAIP)

Available options:
mainnet,
optimism,
arbitrum,
polygon,
gnosis,
base,
unichain,
swellchain,
celo,
worldchain,
berachain,
ink,
bsc,
hyperliquid,
plasma,
avalanche,
katana,
linea,
mega-eth,
monad,
etherlink,
robinhood,
eip155:1,
eip155:10,
eip155:42161,
eip155:137,
eip155:100,
eip155:8453,
eip155:130,
eip155:1923,
eip155:42220,
eip155:480,
eip155:80094,
eip155:57073,
eip155:56,
eip155:999,
eip155:9745,
eip155:43114,
eip155:747474,
eip155:59144,
eip155:4326,
eip155:143,
eip155:42793,
eip155:4663
disallowedNetworks
enum<string>[]

Networks to be excluded (name or CAIP). The parameter is ignored if "allowedNetworks" is specified.

Include only vaults with provided network(name or CAIP)

Available options:
mainnet,
optimism,
arbitrum,
polygon,
gnosis,
base,
unichain,
swellchain,
celo,
worldchain,
berachain,
ink,
bsc,
hyperliquid,
plasma,
avalanche,
katana,
linea,
mega-eth,
monad,
etherlink,
robinhood,
eip155:1,
eip155:10,
eip155:42161,
eip155:137,
eip155:100,
eip155:8453,
eip155:130,
eip155:1923,
eip155:42220,
eip155:480,
eip155:80094,
eip155:57073,
eip155:56,
eip155:999,
eip155:9745,
eip155:43114,
eip155:747474,
eip155:59144,
eip155:4326,
eip155:143,
eip155:42793,
eip155:4663
maxTvl
integer

Maximum TVL in USD of the vaults to be included

maxApy
number

Maximum APY (in decimal) of the vaults to be included

minApy
number

Minimum APY (in decimal) of the vaults to be included

tags
string[]

Tags to be included.

Minimum string length: 1
curators
string[]

Curators to be included.

Minimum string length: 1
sortOrder
enum<string>
default:asc

Sort order, either asc or desc. Ascending is default.

Available options:
asc,
desc
sortBy
enum<string>

Field to sort by.

Available options:
balanceUsd,
tvl,
apy1Day,
apy7Day,
apy30Day
apyInterval
enum<string>
default:7day

Interval for APY data. Possible values: 1day, 7day, 30day

Available options:
1day,
7day,
30day
minUsdAssetValueThreshold
number
default:1

Minimum USD value of the vault to be included

Required range: x >= 0

Response

Default Response

data
object[]
required

List of historical balance items

errors
object
required