API Reference

Get position

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

GET /api/positions?wallet={stacks_address}

Query parameters

string

required

A Stacks mainnet address (starts with SP). Validated server-side.

Response

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

number | null

The health factor. null means the wallet has no debt (not at liquidation risk).

number

Total collateral value in USD, at live oracle prices.

number

Total borrowed value in USD.

number | null

sBTC price at which the health factor hits 1.0. null when not applicable.

Errors

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

Getting Started

Core Concepts

Integration

API Reference

Get position

Query parameters

Response

Errors

​Get position

​Query parameters

​Response

​Errors

Get position

Query parameters

Response

Errors