> ## Documentation Index > Fetch the complete documentation index at: https://docs.vaults.fyi/llms.txt > Use this file to discover all available pages before exploring further. # List user historical balances > Returns the user vault positions and balances at a specific historical timestamp. ## OpenAPI ````yaml https://api.vaults.fyi/alpha/documentation/json get /alpha/historical-balances/{userAddress}/{timestamp} openapi: 3.0.3 info: title: Vaults.fyi Alpha API version: 0.1.0 description: >- Alpha API endpoints for features in early access. These endpoints are not included in the main API documentation and may change without notice. servers: - url: https://api.vaults.fyi description: Vaults.fyi Alpha API security: [] tags: - name: Cross Chain - name: CCTP Bridge - name: Holders - name: Advanced Analytics - name: Historical Positions paths: /alpha/historical-balances/{userAddress}/{timestamp}: get: tags: - Historical Positions summary: List user historical balances description: >- Returns the user vault positions and balances at a specific historical timestamp. operationId: listHistoricalBalances parameters: - schema: type: array items: type: string minLength: 1 in: query name: allowedAssets required: false description: Assets to be included by symbol(ticker). - schema: type: array items: type: string minLength: 1 in: query name: disallowedAssets required: false description: >- Assets to be excluded by symbol(ticker). The parameter is ignored if "allowedAssets" is specified. - schema: type: array items: type: string minLength: 1 in: query name: allowedProtocols required: false description: Protocols to be included by name. - schema: type: array items: type: string minLength: 1 in: query name: disallowedProtocols required: false description: >- Protocols to be excluded by name. The parameter is ignored if "allowedProtocols" is specified. - schema: type: integer default: 100000 in: query name: minTvl required: false description: Minimum TVL in USD of the vaults to be included - schema: type: number minimum: 0 in: query name: minVaultScore required: false description: Minimum vault score required for a vault to be included - schema: type: boolean in: query name: onlyTransactional required: false description: >- Include only vaults that are supported in the transactional interface. - schema: type: boolean in: query name: onlyAppFeatured required: false description: Include only vaults that are featured in app.vaults.fyi - schema: type: boolean default: false in: query name: allowCorrupted required: false description: Allow inclusion of corrupted vaults. - schema: type: boolean in: query name: allowVaultsWithWarnings required: false description: Whether to include vaults with warnings. Defaults to true. - schema: type: array items: type: string enum: - 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 description: Include only vaults with provided network(name or CAIP) default: - base - mainnet - arbitrum - optimism in: query name: allowedNetworks required: false description: Networks to be included (name or CAIP). - schema: type: array items: type: string enum: - 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 description: Include only vaults with provided network(name or CAIP) in: query name: disallowedNetworks required: false description: >- Networks to be excluded (name or CAIP). The parameter is ignored if "allowedNetworks" is specified. - schema: type: integer in: query name: maxTvl required: false description: Maximum TVL in USD of the vaults to be included - schema: type: number in: query name: maxApy required: false description: Maximum APY (in decimal) of the vaults to be included - schema: type: number in: query name: minApy required: false description: Minimum APY (in decimal) of the vaults to be included - schema: type: array items: type: string minLength: 1 in: query name: tags required: false description: Tags to be included. - schema: type: array items: type: string minLength: 1 in: query name: curators required: false description: Curators to be included. - schema: type: string enum: - asc - desc default: asc in: query name: sortOrder required: false description: Sort order, either asc or desc. Ascending is default. - schema: type: string enum: - balanceUsd - tvl - apy1Day - apy7Day - apy30Day in: query name: sortBy required: false description: Field to sort by. - schema: type: string enum: - 1day - 7day - 30day default: 7day in: query name: apyInterval required: false description: 'Interval for APY data. Possible values: 1day, 7day, 30day' - schema: type: number minimum: 0 default: 1 in: query name: minUsdAssetValueThreshold required: false description: Minimum USD value of the vault to be included - schema: type: string pattern: ^0x[a-fA-F0-9]{40}$ in: path name: userAddress required: true description: User address to fetch historical balances for - schema: type: integer in: path name: timestamp required: true description: Unix timestamp (seconds) to fetch balances at responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: vaultId: type: string description: Stable vault identity for API lookups and links address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the vault network: type: object properties: name: type: string enum: - mainnet - optimism - arbitrum - polygon - gnosis - base - unichain - swellchain - celo - worldchain - berachain - ink - bsc - hyperliquid - plasma - avalanche - katana - linea - mega-eth - monad - etherlink - robinhood description: Name of the network chainId: type: integer description: Chain ID of the network networkCaip: type: string pattern: ^eip155:\d+$ description: CAIP-2 of the network required: - name - chainId - networkCaip additionalProperties: false description: Network details of the vault asset: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the asset assetCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the asset name: type: string description: Name of the asset symbol: type: string description: Symbol of the asset decimals: type: integer description: Number of decimals of the asset assetLogo: type: string format: uri description: URL of the asset logo assetPriceInUsd: type: string description: Price of the asset in USD assetGroup: type: string description: >- Group of the asset, e.g., ETH, USD, EURO, BTC, OTHER balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision required: - address - assetCaip - name - symbol - decimals - assetGroup - balanceNative additionalProperties: false description: Asset details of the vault name: type: string description: Name of the vault protocol: type: object properties: name: type: string description: Name of the protocol displayName: type: string description: Display name of the protocol product: type: string description: Product of the protocol version: type: string description: Version of the protocol protocolUrl: type: string description: URL of the protocol description: type: string description: Description of the protocol protocolLogo: type: string description: URL of the protocol logo required: - name additionalProperties: false description: Protocol details of the vault additionalAssets: type: array items: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the asset assetCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the asset name: type: string description: Name of the asset symbol: type: string description: Symbol of the asset decimals: type: integer description: Number of decimals of the asset assetLogo: type: string format: uri description: URL of the asset logo assetPriceInUsd: type: string description: Price of the asset in USD assetGroup: type: string description: >- Group of the asset, e.g., ETH, USD, EURO, BTC, OTHER balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision required: - address - assetCaip - name - symbol - decimals - assetGroup - balanceNative additionalProperties: false description: Additional assets of the vault lpToken: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the LP token tokenCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the LP token name: type: string description: Name of the LP token symbol: type: string description: Symbol of the LP token decimals: type: integer description: Number of decimals of the LP token balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision assetPriceInUsd: type: string description: Price of the asset in USD required: - address - tokenCaip - name - symbol - decimals - balanceNative additionalProperties: false description: LP token details of the vault childrenVaults: type: array items: type: object properties: vaultId: type: string description: Vault id of the child vault address: type: string description: Address of the child vault asset: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the asset assetCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the asset name: type: string description: Name of the asset symbol: type: string description: Symbol of the asset decimals: type: integer description: Number of decimals of the asset assetLogo: type: string format: uri description: URL of the asset logo assetPriceInUsd: type: string description: Price of the asset in USD assetGroup: type: string description: >- Group of the asset, e.g., ETH, USD, EURO, BTC, OTHER balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision required: - address - assetCaip - name - symbol - decimals - assetGroup - balanceNative additionalProperties: false description: Asset details of the child vault lpToken: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the LP token tokenCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the LP token name: type: string description: Name of the LP token symbol: type: string description: Symbol of the LP token decimals: type: integer description: Number of decimals of the LP token balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision assetPriceInUsd: type: string description: Price of the asset in USD required: - address - tokenCaip - name - symbol - decimals - balanceNative additionalProperties: false description: LP token details of the child vault additionalAssets: type: array items: type: object properties: address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: Address of the asset assetCaip: type: string pattern: >- ^eip155:\d+\/(erc20:0x[0-9a-fA-F]{40}|slip44:\d+)$ description: CAIP-2 of the asset name: type: string description: Name of the asset symbol: type: string description: Symbol of the asset decimals: type: integer description: Number of decimals of the asset assetLogo: type: string format: uri description: URL of the asset logo assetPriceInUsd: type: string description: Price of the asset in USD assetGroup: type: string description: >- Group of the asset, e.g., ETH, USD, EURO, BTC, OTHER balanceNative: type: string description: >- Balance of the asset denominated in asset precision balanceUsd: type: string description: >- Balance of the asset denominated in usd. Omitted when no price is available. unclaimedNative: type: string description: >- Unclaimed balance of the asset in the position denominated in asset precision unclaimedUsd: type: string description: >- Unclaimed balance of the asset in the position denominated in usd positionValueInAsset: type: string description: >- Position value in asset denominated in asset precision required: - address - assetCaip - name - symbol - decimals - assetGroup - balanceNative additionalProperties: false description: Additional assets of the child vault required: - vaultId - address - asset additionalProperties: false description: List of child vaults required: - vaultId - address - network - asset - name - protocol additionalProperties: false description: List of historical balance items errors: type: object properties: unsupportedNetworks: type: array items: type: string unsupportedAssets: type: array items: type: string unsupportedProtocols: type: array items: type: string required: - unsupportedNetworks - unsupportedAssets - unsupportedProtocols additionalProperties: false required: - data - errors additionalProperties: false '400': description: Default Response content: application/json: schema: anyOf: - type: object properties: statusCode: type: number error: type: string enum: - Bad Request message: type: string errorId: type: string required: - statusCode - error - message additionalProperties: false - {} '401': description: Default Response content: application/json: schema: anyOf: - type: object properties: error: type: string enum: - Unauthorized message: type: string enum: - >- 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: type: string required: - error - message additionalProperties: false - {} '402': description: Default Response content: application/json: schema: anyOf: - type: object properties: x402Version: anyOf: - type: number - type: string error: type: string resource: type: object properties: url: type: string description: type: string mimeType: type: string serviceName: type: string tags: type: array items: type: string iconUrl: type: string required: - url additionalProperties: false accepts: anyOf: - type: array items: type: object properties: scheme: type: string enum: - exact network: type: string amount: type: string payTo: type: string maxTimeoutSeconds: type: number asset: type: string extra: type: object properties: name: type: string version: type: string required: - name - version additionalProperties: false required: - scheme - network - amount - payTo - maxTimeoutSeconds - asset additionalProperties: false - {} extensions: type: object additionalProperties: {} required: - x402Version - resource additionalProperties: false - {} '403': description: Default Response content: application/json: schema: anyOf: - type: object properties: error: type: string enum: - Forbidden message: type: string enum: - >- This API key has exhausted its available credits. To resume service, please visit https://portal.vaults.fyi/signup to top-up your credits errorId: type: string required: - error - message additionalProperties: false - {} '404': description: Default Response content: application/json: schema: type: object properties: error: type: string enum: - Not Found message: type: string required: - error - message additionalProperties: false '408': description: Default Response content: application/json: schema: anyOf: - type: object properties: message: type: string errorId: type: string additionalProperties: false - {} '422': description: Default Response content: application/json: schema: anyOf: - type: object properties: statusCode: type: number error: type: string enum: - Unprocessable Entity message: type: string errorId: type: string required: - statusCode - error - message additionalProperties: false - {} '500': description: Default Response content: application/json: schema: anyOf: - type: object properties: error: type: string enum: - Internal Server Error message: type: string errorId: type: string required: - error - message additionalProperties: false - {} '503': description: Default Response content: application/json: schema: anyOf: - type: object properties: statusCode: type: number error: type: string enum: - Service Unavailable message: type: string errorId: type: string required: - statusCode - error - message additionalProperties: false - {} security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey name: x-api-key in: header ````