feat(apis): GET /liquidity/:account — account LP positions

[IbrahimIjai]

Context

Liquidity providers need to see all markets where they hold LP tokens, with current value and unrealised PnL, without querying each market individually.

Endpoint

GET /liquidity/:account

Response shape:

[
  {
    "market_token": "C...",
    "market": { "index_token": "C...", "long_token": "C...", "short_token": "C..." },
    "lp_balance": "5000000000",
    "lp_share_pct": "0.42",
    "value_usd": "52143.00",
    "pool_value_usd": "12400000.00",
    "unrealised_pnl_usd": "+143.00"
  }
]

Implementation notes

• Iterate all markets from reader::get_markets
• For each market call market_token::balance(account) via Stellar RPC
• Skip markets where balance is zero
• Compute value_usd from market_token_price x lp_balance
• Unrealised PnL = current value minus entry value (entry value requires tracking deposits — v1 can omit or return null)
• Cache market list for 30 seconds; LP balances fetched fresh per request (account-specific)

Acceptance criteria

• Returns empty array for account with no LP positions (not 404)
• lp_share_pct correct to 2 decimal places
• value_usd computed at current oracle price
• 404 for invalid Stellar address format
• Test with mocked market list and balances