get_positions

Reads a wallet’s leverage positions — and, on Robinhood Chain, its open stock + yield equity vaults — directly from chain state (read-only).

Input

string

required

Wallet address to read positions for.

integer

default:"1"

Output

Each position carries:

Field	Meaning
`id`	On-chain index — feeds `build_manage_tx`.
`positionId`	Globally-unique `${chainId}-${strategyId}-${id}`.
`open` / `liquidated`	Lifecycle flags.
`amountLeveragedCollateral`, `amountLoan`	Collateral and debt.
`ltv` / liquidation LTV + headroom	Current risk.
`leverage`, `netValueUsd`, `currentLeverageApyPct`	Live position economics (the APY includes any collateral-side incentive, as the strategy’s ladder does).
`amountDepositedInLoanToken`	The on-chain deposit basis in loan-token units (not a USD cost basis).
`exitLiquidity`	Can this position actually be unwound? See below.

Exit health (per position)

Closing swaps the full leveraged collateral, so exit health is measured against the whole position — not your equity:

"exitLiquidity": {
  "tier": "good",                 // deep | good | limited | thin | unknown
  "cleanExitSize": "$500K+",      // largest notional that exits cleanly
  "unwindSizeUsd": 264.2,         // this position's full unwind notional
  "exceedsCleanExitSize": false,  // ← act on this
  "noSwapRoute": false            // hard flag: collateral currently unswappable
}

Poll this on open positions. A market can be deep while your position still exceeds the depth that exits cleanly — exceedsCleanExitSize: true means expect slippage on close. If a route disappears entirely, you can still exit in-kind (repay + remove_collateral need no swap) — see Oracle & exit liquidity.

{
  "chainId": 1,
  "userAddress": "0x…",
  "positions": [
    { "id": 0, "positionId": "1-0x3274…-0", "open": true, "leverage": "3.0", "currentLeverageApyPct": "5.64" }
  ]
}

Example

const { positions } = await call("get_positions", { userAddress: "0x…" });

Equity vaults (`equityPositions`)

A vault is two legs the user holds directly: the stock as their own Morpho collateral with USDG debt, and the Spiral yield loop that debt funds. get_positions re-assembles them and removes the vault’s yield loop(s) from positions. yieldLoopMatch says how the loop was attributed:

`yieldLoopMatch`	Meaning
`tagged`	The app recorded the loop for this vault when it was opened (the primary signal).
`basis`	Exactly one open loop’s deposit basis matches the vault’s stock debt.
`mixed`	Some loops tagged, the rest matched on basis (stacked opens).
`ambiguous`	More than one loop could be the leg. Nothing is claimed: the candidates are listed in `ambiguousYieldLoopIds` and stay in `positions`; `build_equity_exit_tx` then needs `yieldPositionIds`.
`none`	The stock leg is open but no loop matches.

"equityPositions": [
  {
    "strategyId": "equity-0x50bc…",
    "curator": "Longbow",
    "stock": {
      "symbol": "SPY", "collateral": "1.291249", "collateralUsd": "990.02", "priceUsd": "766.6309",
      "debtUsdg": "494.960000", "ltvPct": "50.00", "liquidationLtvPct": "62.50", "ltvHeadroomPct": "12.50",
      "liquidationPriceUsd": "613.3047", "priceDropToLiquidationPct": "20.00", "borrowApyPct": "0.06"
    },
    "yieldLoops": [ { "id": 3, "collateralSymbol": "syrupUSDG", "ltvPct": "90.48", "currentLeverageApyPct": "40.79" } ],
    "yieldLoopMatch": "basis",
    "netValueUsd": "984.11",
    "currentNetApyPct": "20.37"
  }
]

A vault’s yield loop cannot be managed alone: build_manage_tx refuses every action on it, because closing it by itself would leave the stock leg standing with its debt. Unwind the whole vault with build_equity_exit_tx.

No cost-basis or realized P&L — those require off-chain history. Positions are read live from chain and returned newest-first.

Introduction

Connect a client

Concepts

Tools

Guides

Reference

Input

Output

Exit health (per position)

Example

Equity vaults (`equityPositions`)

​Input

​Output

​Exit health (per position)

​Example

​Equity vaults (equityPositions)

Input

Output

Exit health (per position)

Example

Equity vaults (`equityPositions`)