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

# API Reference

> The live position endpoint

## Get position

Reads a wallet's Zest position from mainnet and returns its computed health factor.

```http theme={null}
GET /api/positions?wallet={stacks_address}
```

### Query parameters

<ParamField query="wallet" type="string" required>
  A Stacks mainnet address (starts with `SP`). Validated server-side.
</ParamField>

### Response

```json theme={null}
{
  "wallet": "SP2GHQRCRMYY4S8PMBR49BEKX144VR437YT42SF3B",
  "hasPosition": true,
  "hf": null,
  "collateralUSD": 12.51,
  "debtUSD": 0,
  "collateralRows": [
    { "symbol": "sbtc-token", "amount": 0.00019401, "usd": 12.51 }
  ],
  "debtRows": [],
  "liqPrice": null
}
```

<ResponseField name="hf" type="number | null">
  The health factor. `null` means the wallet has no debt (not at liquidation risk).
</ResponseField>

<ResponseField name="collateralUSD" type="number">
  Total collateral value in USD, at live oracle prices.
</ResponseField>

<ResponseField name="debtUSD" type="number">
  Total borrowed value in USD.
</ResponseField>

<ResponseField name="liqPrice" type="number | null">
  sBTC price at which the health factor hits `1.0`. `null` when not applicable.
</ResponseField>

### Errors

| Status | Meaning                                 |
| ------ | --------------------------------------- |
| `400`  | Invalid Stacks address                  |
| `502`  | Upstream read failed or Hiro rate limit |