---
title: "Get positions"
method: POST
path: "/v1/positions"
tags: ["Portfolio"]
---

# Get positions

`POST /v1/positions`

Retrieve active positions for a wallet address. Pass providerId or providerIds (one or more providers).

## Request body

- PortfolioRequestDto
  - `providerId` 'hyperliquid' | 'hyperliquid-xyz' — Single provider identifier. At least one of providerId or providerIds must be provided.
  - `providerIds` string[] — Filter by multiple providers (CSV, repeated query params, or JSON array). At least one of providerId or providerIds must be provided. When both providerId and providerIds are set, results include all listed providers.
  - `address` string, required — User wallet address

## Response `200`

User positions

- PositionDto[]
  - `address` string, required — User wallet address
  - `integrationId` string, required — Integration ID
  - `network` 'ethereum' | 'ethereum-goerli' | 'ethereum-holesky' | 'ethereum-sepolia' | 'ethereum-hoodi' | 'arbitrum' | 'base' | 'base-sepolia' | 'gnosis' | 'optimism' | 'polygon' | 'polygon-amoy' | 'starknet' | 'zksync' | 'linea' | 'unichain' | 'monad-testnet' | 'monad' | 'robinhood' | 'robinhood-testnet' | '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', required — Network
  - `totalSuppliedUsd` string, required — Total supplied value in USD (all supplied assets)
  - `totalCollateralUsd` string, required — Total collateral value in USD (only assets enabled as collateral)
  - `totalBorrowedUsd` string, required — Total borrowed value in USD
  - `netWorthUsd` string, required — Net worth (supplied - borrowed) in USD
  - `healthFactor` string, nullable, 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.
  - `currentLtv` string, required — Current loan-to-value ratio as decimal (e.g., "0.55" = 55%)
  - `availableToBorrowUsd` string, nullable, 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.
  - `netApy` string, required — Net APY (supply earnings - borrow costs)
  - `supplyBalances` SupplyBalanceDto[], required — Supply positions
    - `marketId` string, required — Market ID
    - `tokenAddress` string, required — Token contract address
    - `tokenSymbol` string, required — Token symbol
    - `balance` string, required — Supplied balance in human-readable token units
    - `balanceRaw` string, required — Supplied balance in raw token units
    - `balanceUsd` string, required — Supplied balance in USD
    - `apy` string, required — Current supply APY as percentage
    - `isCollateral` boolean, required — Whether this supply is being used as collateral
    - `positionState` PositionStateDto
      - `currentLtv` string, required — Loan-to-value for this market as a decimal (e.g., "0.20" = 20%)
      - `liquidationThreshold` string, required — Liquidation LTV for this market as a decimal (e.g., "0.86" = 86%)
      - `healthFactor` string, nullable, required — Health factor for this market (>1 is safe, <1 means liquidatable). Null when this market has no debt.
      - `availableToBorrowUsd` string, required — Remaining borrowing power in USD within this market
    - `pendingActions` BorrowPendingActionDto[], required — Available actions for this supply balance
      - `type` 'supply' | 'borrow' | 'repay' | 'withdraw' | 'enableCollateral' | 'disableCollateral', required — Action type — pass this value to POST /v1/actions as the action field
      - `label` string, required — Human-readable action label
      - `args` ArgumentsDto, required
        - `amount` string — Amount in human-readable units (e.g. "1.5" for 1.5 USDC). Provide either amount or amountRaw.
        - `amountRaw` string — Amount in raw token units (e.g. "1500000" for 1.5 USDC with 6 decimals). Provide either amount or amountRaw.
        - `repayAll` boolean — Repay the full outstanding debt using protocol-specific full-repay semantics. Only valid for repay actions. When true, omit amount and amountRaw.
        - `tokenAddress` string — Token address to supply/borrow/repay/withdraw
        - `collateralTokenAddress` string — Collateral token address. Required when providing collateralAmount for pool-based protocols (Aave). Inferred from marketId for isolated-market protocols (Morpho Blue).
        - `collateralAmount` string — 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.
        - `collateralAmountRaw` string — Optional collateral amount in raw token units (e.g. "50000000" for 0.5 ETH with 8 decimals). Provide either collateralAmount or collateralAmountRaw.
        - `borrowAmount` string — 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.
        - `targetLtv` string — 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.
        - `marketId` string, required — Market ID as returned by GET /v1/markets. Identifies the specific lending market for the action.
  - `debtBalances` DebtBalanceDto[], required — Debt positions
    - `marketId` string, required — Market ID
    - `tokenAddress` string, required — Token contract address
    - `tokenSymbol` string, required — Token symbol
    - `balance` string, required — Borrowed balance in human-readable token units
    - `balanceRaw` string, required — Borrowed balance in raw token units
    - `balanceUsd` string, required — Borrowed balance in USD
    - `apy` string, required — Current borrow APY as percentage
    - `pendingActions` BorrowPendingActionDto[], required — Available actions for this debt balance
      - `type` 'supply' | 'borrow' | 'repay' | 'withdraw' | 'enableCollateral' | 'disableCollateral', required — Action type — pass this value to POST /v1/actions as the action field
      - `label` string, required — Human-readable action label
      - `args` ArgumentsDto, required
        - `amount` string — Amount in human-readable units (e.g. "1.5" for 1.5 USDC). Provide either amount or amountRaw.
        - `amountRaw` string — Amount in raw token units (e.g. "1500000" for 1.5 USDC with 6 decimals). Provide either amount or amountRaw.
        - `repayAll` boolean — Repay the full outstanding debt using protocol-specific full-repay semantics. Only valid for repay actions. When true, omit amount and amountRaw.
        - `tokenAddress` string — Token address to supply/borrow/repay/withdraw
        - `collateralTokenAddress` string — Collateral token address. Required when providing collateralAmount for pool-based protocols (Aave). Inferred from marketId for isolated-market protocols (Morpho Blue).
        - `collateralAmount` string — 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.
        - `collateralAmountRaw` string — Optional collateral amount in raw token units (e.g. "50000000" for 0.5 ETH with 8 decimals). Provide either collateralAmount or collateralAmountRaw.
        - `borrowAmount` string — 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.
        - `targetLtv` string — 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.
        - `marketId` string, required — Market ID as returned by GET /v1/markets. Identifies the specific lending market for the action.

## Other responses

- `401` — Invalid or missing API key
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/yield/apis/yield-xyz-api.md) · [All operations](https://skmtc.net/yield/apis/yield-xyz-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yield/yield-xyz-api/versions/acfa80015ca5/schema)