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

# get_positions

> Read a wallet's open and closed positions from chain state.

Reads a wallet's leverage positions directly from chain state (read-only).

## Input

<ParamField path="userAddress" type="string" required>Wallet address to read positions for.</ParamField>

<ParamField path="chainId" type="integer" default="1" />

## Output

Each position carries:

| Field                                              | Meaning                                                                    |
| -------------------------------------------------- | -------------------------------------------------------------------------- |
| `id`                                               | On-chain index — feeds [`build_manage_tx`](/agents/tools/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.                                                   |

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

## Example

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

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