eryao/docs/protocols/points/points-balance-protocol.md

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
• Related redeem protocol: docs/protocols/points/points-redeem-code-protocol.md

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)

{
  "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.