v1 Position Tracking Endpoints for DeFi Wallets

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
}

Sections

Endpoints

Beta

Alpha

v1 Position Tracking Endpoints for DeFi Wallets

Get user positions

Path parameters

Query parameters

Example request

Example response

Get user balances

Query parameters

Example request

Example response

Get past vault transactions by user address

Path parameters

Example request

Example response

Get estimated returns for a user’s vault position

Path parameters

Example request

Example response

​Get user positions

​Path parameters

​Query parameters

​Example request

​Example response

​Get user balances

​Query parameters

​Example request

​Example response

​Get past vault transactions by user address

​Path parameters

​Example request

​Example response

​Get estimated returns for a user’s vault position

​Path parameters

​Example request

​Example response

Get user positions

Path parameters

Query parameters

Example request

Example response

Get user balances

Query parameters

Example request

Example response

Get past vault transactions by user address

Path parameters

Example request

Example response

Get estimated returns for a user’s vault position

Path parameters

Example request

Example response