Get positions

Return one address’s supply and debt balances on a Borrow integration and network, with account and per-market risk fields.

GET /v1/positions

Get user positions

cURL

curl --request GET \
  --url https://borrow.yield.xyz/v1/positions \
  --header 'x-api-key: <api-key>'

200

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28",
  "integrationId": "aave-borrow",
  "network": "ethereum",
  "totalSuppliedUsd": "5000.00",
  "totalCollateralUsd": "4200.00",
  "totalBorrowedUsd": "2000.00",
  "netWorthUsd": "3000.00",
  "healthFactor": "1.85",
  "currentLtv": "0.55",
  "availableToBorrowUsd": "1500.00",
  "netApy": "2.34",
  "supplyBalances": [
    {
      "marketId": "aave-v3-ethereum-usdc",
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "tokenSymbol": "USDC",
      "balance": "1000.00",
      "balanceRaw": "1000000000",
      "balanceUsd": "1000.00",
      "apy": "3.45",
      "isCollateral": true,
      "pendingActions": [
        {
          "type": "withdraw",
          "label": "Withdraw USDC",
          "args": {
            "marketId": "morpho-blue-borrow-base-cbbtc-usdc-86",
            "amount": "1.5",
            "amountRaw": "1500000",
            "repayAll": true,
            "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "collateralTokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "collateralAmount": "0.5",
            "collateralAmountRaw": "50000000",
            "borrowAmount": "100",
            "targetLtv": "0.1"
          }
        }
      ],
      "positionState": {
        "currentLtv": "0.1980",
        "liquidationThreshold": "0.8600",
        "healthFactor": "4.3430",
        "availableToBorrowUsd": "2.01"
      }
    }
  ],
  "debtBalances": [
    {
      "marketId": "aave-v3-ethereum-weth",
      "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "tokenSymbol": "WETH",
      "balance": "0.5",
      "balanceRaw": "500000000000000000",
      "balanceUsd": "1500.00",
      "apy": "5.67",
      "pendingActions": [
        {
          "type": "withdraw",
          "label": "Withdraw USDC",
          "args": {
            "marketId": "morpho-blue-borrow-base-cbbtc-usdc-86",
            "amount": "1.5",
            "amountRaw": "1500000",
            "repayAll": true,
            "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "collateralTokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
            "collateralAmount": "0.5",
            "collateralAmountRaw": "50000000",
            "borrowAmount": "100",
            "targetLtv": "0.1"
          }
        }
      ]
    }
  ]
}

integrationId, network and address are all required. An unknown integration, or a network the integration does not support, returns 400.

• Pool integrations (aave-borrow, sparklend-borrow): read on chain for the address. Use the account-level healthFactor and availableToBorrowUsd.
• Isolated integrations (morpho-blue-borrow, lista-borrow): only markets this address has acted on through the Borrow API are read; a position opened elsewhere does not appear. Account-level healthFactor and availableToBorrowUsd are null; read positionState on each supplyBalances entry.

Results may be cached for up to 30 seconds, except that they are read fresh for 30 minutes after an action is created for the address on that integration. A Morpho Blue position that was fully liquidated no longer appears here; use Get liquidations.

The nullability table is on Objects and enums.

Authorizations

x-api-key · string · header · required

Query Parameters

integrationId · string · required

Integration identifier

Example:

"aave-borrow"

network · enum<string> · required

Network

Available options: ethereum, ethereum-goerli, ethereum-holesky, ethereum-sepolia, ethereum-hoodi, arbitrum, base, base-sepolia, gnosis, optimism, polygon, polygon-amoy, starknet, zksync, linea, unichain, plume, monad-testnet, monad, robinhood, robinhood-testnet, arc-testnet, arc, avalanche-c, avalanche-c-atomic, avalanche-p, binance, celo, fantom, harmony, moonriver, okc, viction, core, sonic, plasma, katana, hyperevm, tempo, pharos, agoric, akash, axelar, band-protocol, bitsong, canto, chihuahua, comdex, coreum, cosmos, crescent, cronos, cudos, desmos, dydx, evmos, fetch-ai, gravity-bridge, injective, irisnet, juno, kava, ki-network, mars-protocol, nym, okex-chain, onomy, osmosis, persistence, quicksilver, regen, secret, sentinel, sommelier, stafi, stargaze, stride, teritori, tgrade, umee, sei, mantra, celestia, saga, zetachain, dymension, humansai, neutron, polkadot, kusama, westend, bittensor, aptos, binancebeacon, cardano, near, solana, solana-devnet, stellar, stellar-testnet, sui, tezos, tron, ton, ton-testnet, hyperliquid

Example:

"ethereum"

address · string · required

User wallet address

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28"

Response

200

application/json

User positions retrieved successfully

address · string · required

User wallet address

Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28"

integrationId · string · required

Integration ID

Example:

"aave-borrow"

network · enum<string> · required

Network

Available options: ethereum, ethereum-goerli, ethereum-holesky, ethereum-sepolia, ethereum-hoodi, arbitrum, base, base-sepolia, gnosis, optimism, polygon, polygon-amoy, starknet, zksync, linea, unichain, plume, monad-testnet, monad, robinhood, robinhood-testnet, arc-testnet, arc, avalanche-c, avalanche-c-atomic, avalanche-p, binance, celo, fantom, harmony, moonriver, okc, viction, core, sonic, plasma, katana, hyperevm, tempo, pharos, agoric, akash, axelar, band-protocol, bitsong, canto, chihuahua, comdex, coreum, cosmos, crescent, cronos, cudos, desmos, dydx, evmos, fetch-ai, gravity-bridge, injective, irisnet, juno, kava, ki-network, mars-protocol, nym, okex-chain, onomy, osmosis, persistence, quicksilver, regen, secret, sentinel, sommelier, stafi, stargaze, stride, teritori, tgrade, umee, sei, mantra, celestia, saga, zetachain, dymension, humansai, neutron, polkadot, kusama, westend, bittensor, aptos, binancebeacon, cardano, near, solana, solana-devnet, stellar, stellar-testnet, sui, tezos, tron, ton, ton-testnet, hyperliquid

Example:

"ethereum"

totalSuppliedUsd · string · required

Total supplied value in USD (all supplied assets)

Example:

"5000.00"

totalCollateralUsd · string · required

Total collateral value in USD (only assets enabled as collateral)

Example:

"4200.00"

totalBorrowedUsd · string · required

Total borrowed value in USD

Example:

"2000.00"

netWorthUsd · string · required

Net worth (supplied - borrowed) in USD

Example:

"3000.00"

healthFactor · string | null · required

Account-level health factor (>1 is safe, <1 means liquidatable). Null when there is no debt, and always null for isolated-market protocols (e.g. Morpho) — read each supply balance's positionState.healthFactor instead.

Example:

"1.85"

currentLtv · string · required

Current loan-to-value ratio as decimal (e.g., "0.55" = 55%)

Example:

"0.55"

availableToBorrowUsd · string | null · required

Account-level available to borrow in USD based on collateral. Null for isolated-market protocols (e.g. Morpho), where headroom is per-market — read each supply balance's positionState.availableToBorrowUsd instead.

Example:

"1500.00"

netApy · string · required

Net APY (supply earnings - borrow costs)

Example:

"2.34"

supplyBalances · object[] · required

Supply positions

Show child attributes

debtBalances · object[] · required

Debt positions

Show child attributes