Skip to main content
The v1 position tracking endpoints let you look up everything related to a wallet’s activity across supported vaults: active lending and staking positions, idle token balances, a full transaction history for any vault, and estimated total returns.
These are legacy v1 endpoints. They are fully supported and maintained. For new integrations, consider using the v2 endpoints.

​
Get user positions

GET https://api.vaults.fyi/v1/portfolio/positions/{userAddress}
Returns all active lending and staking LP positions for a wallet, organized by network. Each position includes the vault address, protocol name, native and USD balances, unclaimed rewards, current APY, and underlying asset details. Authentication: x-api-key header required.

​
Path parameters

​
userAddress
string
required
Wallet address to query. Pattern: ^0x[a-fA-F0-9]{40}$.

​
Query parameters

​
apyInterval
string
default:"7day"
APY averaging window to use in the response. Possible values: 1day, 7day, 30day.

​
Example request

GET /v1/portfolio/positions/0xabc...123 HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

​
Example response

{
  "mainnet": [
    {
      "vaultAddress": "0xdef...456",
      "protocolName": "Aave",
      "protocolLogo": "https://example.com/aave.png",
      "vaultName": "USDC Lending",
      "balanceUsd": "1050.00",
      "balanceNative": "1050.000000",
      "balanceLp": "1045.123456",
      "unclaimedUsd": "2.50",
      "unclaimedNative": "2.500000",
      "apy": {
        "base": 420,
        "rewards": 48,
        "total": 468
      },
      "asset": {
        "name": "USD Coin",
        "assetAddress": "0xa0b...789",
        "assetCaip": "eip155:1/erc20:0xa0b...789",
        "symbol": "USDC",
        "decimals": 6
      }
    }
  ],
  "arbitrum": [],
  "base": []
}
The response includes a key for every supported network (mainnet, arbitrum, optimism, polygon, base, gnosis, unichain) even if the wallet has no positions on that network.

​
Get user balances

GET https://api.vaults.fyi/v1/portfolio/wallet-balances
Returns idle (non-staked) token balances for a wallet across all supported networks. Use this to identify assets a user holds that could be put to work in a yield vault. Authentication: x-api-key header required.

​
Query parameters

​
account
string
required
Wallet address to query. Pattern: ^0x[a-fA-F0-9]{40}$.

​
Example request

GET /v1/portfolio/wallet-balances?account=0xabc...123 HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

​
Example response

{
  "mainnet": [
    {
      "address": "0xa0b...789",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "network": "mainnet",
      "balance": "500000000",
      "balanceNative": "500.000000",
      "balanceUsd": "500.00",
      "type": "asset"
    }
  ],
  "arbitrum": [],
  "base": []
}

​
Get past vault transactions by user address

GET https://api.vaults.fyi/v1/vaults/{network}/{vaultAddress}/holder-events/{holder}
Returns a chronological list of all deposit, withdrawal, and transfer events for a specific wallet on a specific vault. Each event includes the activity type, timestamp, transaction amount, and position value at the time. Authentication: x-api-key header required.

​
Path parameters

​
network
string
required
Network name or CAIP identifier. E.g. mainnet, arbitrum, base.
​
vaultAddress
string
required
Vault contract address. Pattern: ^0x[a-fA-F0-9]{40}$.
​
holder
string
required
Wallet address of the holder. Pattern: ^0x[a-fA-F0-9]{40}$.

​
Example request

GET /v1/vaults/mainnet/0xdef...456/holder-events/0xabc...123 HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

​
Example response

{
  "events": [
    {
      "activity": "Transfer",
      "timestamp": 1700000000,
      "amount": {
        "usd": 1000.00,
        "native": "1000.000000"
      },
      "positionValue": {
        "usd": 1050.00,
        "native": "1050.000000"
      }
    }
  ]
}

​
Get estimated returns for a user’s vault position

GET https://api.vaults.fyi/v1/vaults/{network}/{vaultAddress}/holder-total-returns/{holder}
Returns the estimated total returns a wallet has earned from a specific vault, denominated in both USD and the vault’s native asset. Authentication: x-api-key header required.

​
Path parameters

​
network
string
required
Network name or CAIP identifier.
​
vaultAddress
string
required
Vault contract address. Pattern: ^0x[a-fA-F0-9]{40}$.
​
holder
string
required
Wallet address of the holder. Pattern: ^0x[a-fA-F0-9]{40}$.

​
Example request

GET /v1/vaults/mainnet/0xdef...456/holder-total-returns/0xabc...123 HTTP/1.1
Host: api.vaults.fyi
x-api-key: YOUR_API_KEY
Accept: */*

​
Example response

{
  "usd": 52.34,
  "native": 52.34
}