> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get positions

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

`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](/api-reference/borrow/positions/get-liquidations).

The nullability table is on [Objects and enums](/api-reference/borrow/objects#position-fields-and-nullability).


## OpenAPI

````yaml openapi-borrow.json GET /v1/positions
openapi: 3.0.0
info:
  title: 'Yield API: Borrow'
  description: API Documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://borrow.yield.xyz
    description: Production
security: []
tags:
  - name: Discovery
    description: Browse and discover lending markets, integrations, and supported networks
  - name: Positions
    description: User-specific supply and borrow positions
  - name: Actions
    description: >-
      Execute actions (supply, borrow, repay, withdraw) and manage multi-step
      flows
  - name: Transactions
    description: Submit signed transactions and track status
externalDocs:
  description: For more information
  url: https://docs.yield.xyz
paths:
  /v1/positions:
    get:
      tags:
        - Positions
        - Positions
      summary: Get user positions
      description: >-
        Retrieve all supply and borrow positions for a user address across
        specified integration and network.
      operationId: PositionsController_getPositions_v1
      parameters:
        - name: integrationId
          required: true
          in: query
          description: Integration identifier
          schema:
            example: aave-borrow
            type: string
        - name: network
          required: true
          in: query
          description: Network
          schema:
            example: ethereum
            type: string
            enum:
              - 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
        - name: address
          required: true
          in: query
          description: User wallet address
          schema:
            example: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28'
            type: string
      responses:
        '200':
          description: User positions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionDto'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid API key
                  error:
                    type: string
                    example: Unauthorized
                  statusCode:
                    type: number
                    example: 401
        '429':
          description: Rate limit exceeded
          headers:
            x-ratelimit-limit:
              description: Request limit per window
              schema:
                type: string
            x-ratelimit-remaining:
              description: Remaining requests (will be 0)
              schema:
                type: string
            x-ratelimit-reset:
              description: Unix timestamp when window resets
              schema:
                type: string
            retry-after:
              description: Seconds to wait before retrying
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Rate limit exceeded
                  error:
                    type: string
                    example: Too Many Requests
                  statusCode:
                    type: number
                    example: 429
                  retryAfter:
                    type: number
                    example: 30
      security:
        - ApiKey: []
components:
  schemas:
    PositionDto:
      type: object
      properties:
        address:
          type: string
          description: User wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fB28'
        integrationId:
          type: string
          description: Integration ID
          example: aave-borrow
        network:
          type: string
          description: Network
          enum:
            - 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:
          type: string
          description: Total supplied value in USD (all supplied assets)
          example: '5000.00'
        totalCollateralUsd:
          type: string
          description: Total collateral value in USD (only assets enabled as collateral)
          example: '4200.00'
        totalBorrowedUsd:
          type: string
          description: Total borrowed value in USD
          example: '2000.00'
        netWorthUsd:
          type: string
          description: Net worth (supplied - borrowed) in USD
          example: '3000.00'
        healthFactor:
          type: string
          description: >-
            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'
          nullable: true
        currentLtv:
          type: string
          description: Current loan-to-value ratio as decimal (e.g., "0.55" = 55%)
          example: '0.55'
        availableToBorrowUsd:
          type: string
          description: >-
            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'
          nullable: true
        netApy:
          type: string
          description: Net APY (supply earnings - borrow costs)
          example: '2.34'
        supplyBalances:
          description: Supply positions
          type: array
          items:
            $ref: '#/components/schemas/SupplyBalanceDto'
        debtBalances:
          description: Debt positions
          type: array
          items:
            $ref: '#/components/schemas/DebtBalanceDto'
      required:
        - address
        - integrationId
        - network
        - totalSuppliedUsd
        - totalCollateralUsd
        - totalBorrowedUsd
        - netWorthUsd
        - healthFactor
        - currentLtv
        - availableToBorrowUsd
        - netApy
        - supplyBalances
        - debtBalances
    SupplyBalanceDto:
      type: object
      properties:
        marketId:
          type: string
          description: Market ID
          example: aave-v3-ethereum-usdc
        tokenAddress:
          type: string
          description: Token contract address
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        tokenSymbol:
          type: string
          description: Token symbol
          example: USDC
        balance:
          type: string
          description: Supplied balance in human-readable token units
          example: '1000.00'
        balanceRaw:
          type: string
          description: Supplied balance in raw token units
          example: '1000000000'
        balanceUsd:
          type: string
          description: Supplied balance in USD
          example: '1000.00'
        apy:
          type: string
          description: Current supply APY as percentage
          example: '3.45'
        isCollateral:
          type: boolean
          description: Whether this supply is being used as collateral
          example: true
        positionState:
          description: >-
            Per-market risk state for isolated-market protocols (e.g. Morpho
            Blue), where borrowing power and liquidation are scoped to this
            market. Omitted for pool-based protocols (e.g. Aave), where the
            account-level fields apply.
          allOf:
            - $ref: '#/components/schemas/PositionStateDto'
        pendingActions:
          description: Available actions for this supply balance
          type: array
          items:
            $ref: '#/components/schemas/BorrowPendingActionDto'
      required:
        - marketId
        - tokenAddress
        - tokenSymbol
        - balance
        - balanceRaw
        - balanceUsd
        - apy
        - isCollateral
        - pendingActions
    DebtBalanceDto:
      type: object
      properties:
        marketId:
          type: string
          description: Market ID
          example: aave-v3-ethereum-weth
        tokenAddress:
          type: string
          description: Token contract address
          example: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
        tokenSymbol:
          type: string
          description: Token symbol
          example: WETH
        balance:
          type: string
          description: Borrowed balance in human-readable token units
          example: '0.5'
        balanceRaw:
          type: string
          description: Borrowed balance in raw token units
          example: '500000000000000000'
        balanceUsd:
          type: string
          description: Borrowed balance in USD
          example: '1500.00'
        apy:
          type: string
          description: Current borrow APY as percentage
          example: '5.67'
        pendingActions:
          description: Available actions for this debt balance
          type: array
          items:
            $ref: '#/components/schemas/BorrowPendingActionDto'
      required:
        - marketId
        - tokenAddress
        - tokenSymbol
        - balance
        - balanceRaw
        - balanceUsd
        - apy
        - pendingActions
    PositionStateDto:
      type: object
      properties:
        currentLtv:
          type: string
          description: Loan-to-value for this market as a decimal (e.g., "0.20" = 20%)
          example: '0.1980'
        liquidationThreshold:
          type: string
          description: Liquidation LTV for this market as a decimal (e.g., "0.86" = 86%)
          example: '0.8600'
        healthFactor:
          type: string
          description: >-
            Health factor for this market (>1 is safe, <1 means liquidatable).
            Null when this market has no debt.
          example: '4.3430'
          nullable: true
        availableToBorrowUsd:
          type: string
          description: Remaining borrowing power in USD within this market
          example: '2.01'
      required:
        - currentLtv
        - liquidationThreshold
        - healthFactor
        - availableToBorrowUsd
    BorrowPendingActionDto:
      type: object
      properties:
        type:
          type: string
          description: >-
            Action type — pass this value to POST /v1/actions as the action
            field
          enum:
            - supply
            - borrow
            - repay
            - withdraw
            - enableCollateral
            - disableCollateral
            - supplyAndBorrow
          example: withdraw
        label:
          type: string
          description: Human-readable action label
          example: Withdraw USDC
        args:
          description: Pre-filled arguments for the action
          allOf:
            - $ref: '#/components/schemas/ArgumentsDto'
      required:
        - type
        - label
        - args
    ArgumentsDto:
      type: object
      properties:
        amount:
          type: string
          description: >-
            Amount in human-readable units (e.g. "1.5" for 1.5 USDC). Provide
            either amount or amountRaw.
          example: '1.5'
        amountRaw:
          type: string
          description: >-
            Amount in raw token units (e.g. "1500000" for 1.5 USDC with 6
            decimals). Provide either amount or amountRaw.
          example: '1500000'
        repayAll:
          type: boolean
          description: >-
            Repay the full outstanding debt using protocol-specific full-repay
            semantics. Only valid for repay actions. When true, omit amount and
            amountRaw.
          example: true
        tokenAddress:
          type: string
          description: Token address to supply/borrow/repay/withdraw
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        collateralTokenAddress:
          type: string
          description: >-
            Collateral token address. Required when providing collateralAmount
            for pool-based protocols (Aave). Inferred from marketId for
            isolated-market protocols (Morpho Blue).
          example: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
        collateralAmount:
          type: string
          description: >-
            Optional collateral amount in human-readable units (e.g. "0.5" for
            0.5 ETH). For borrow: collateral to deposit before borrowing. For
            repay: collateral to withdraw after repaying. Provide either
            collateralAmount or collateralAmountRaw.
          example: '0.5'
        collateralAmountRaw:
          type: string
          description: >-
            Optional collateral amount in raw token units (e.g. "50000000" for
            0.5 ETH with 8 decimals). Provide either collateralAmount or
            collateralAmountRaw.
          example: '50000000'
        borrowAmount:
          type: string
          description: >-
            Supply action only. Desired borrow amount in human-readable units of
            the market loan token. Provide together with targetLtv to have the
            API derive the required collateral (post-fee). Mutually exclusive
            with amount/amountRaw.
          example: '100'
        targetLtv:
          type: string
          description: >-
            Supply action only. Target loan-to-value as a decimal (e.g. "0.1" =
            10%). Provide together with borrowAmount. Must not exceed the market
            max LTV.
          example: '0.1'
        marketId:
          type: string
          description: >-
            Market ID as returned by GET /v1/markets. Identifies the specific
            lending market for the action.
          example: morpho-blue-borrow-base-cbbtc-usdc-86
      required:
        - marketId
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.