# Points Balance Protocol (Frontend <-> Backend)

This document defines the read-only points balance contract for authenticated users.

Protocol verification status:

- Backend route source: `backend/src/v1/points/router.py`
- Backend service source: `backend/src/v1/points/service.py`
- Response schema source: `backend/src/v1/points/schemas.py`

## Compatibility strategy

- Additive evolution only.
- Existing response fields are stable and must remain backward-compatible.

## Route

- `GET /api/v1/points/balance`

## Authorization

- Requires authenticated session.
- User identity is derived from verified backend auth context.

## Response (200)

```json
{
  "balance": 120,
  "frozenBalance": 20,
  "availableBalance": 100,
  "runCost": 20,
  "canRun": true
}
```

Field rules:

- `balance`: integer `>= 0`
- `frozenBalance`: integer `>= 0`
- `availableBalance`: integer `>= 0`, computed as `max(balance - frozenBalance, 0)`
- `runCost`: integer `> 0`, current value `20`
- `canRun`: boolean, equivalent to `availableBalance >= runCost`

## Error contract linkage

- RFC7807 + extension `code`, optional `params`.
- Shared registry: `docs/protocols/common/http-error-codes.md`.