Subject Realtime Balance

Read the realtime balance of the payer account resolved from the token subject.

GET /v1/subject/realtime/balance

Authentication

Use a Subject Token with the analysis rule. Tenant, project, subject type and subject ID come from the token. Obtain it through Grant Subject Token. Missing, invalid or expired tokens return 401; missing analysis returns 403.

Authorization: Bearer <subject-token>

Request Body

The request body is empty. All supported query parameters are listed below.

Query Parameters

Field	Contract
`currency`	Required non-blank currency, e.g. `USD`; normalized to uppercase.

Do not send account_id: any non-empty value returns 403. Subject identity is always taken from the token; subject query parameters do not switch it. The service resolves the subject’s current payer for the requested currency. Missing routing or wallet data causes a balance lookup error.

This is an account balance, not a subject-only spending total. Subjects sharing a payer see the same account funds. Token metric restrictions do not redact the balance. The response contains no usage-limit windows; use Get Subject Realtime Limits for usage controls. Balances can change between reads and do not reserve funds.

Example

curl 'http://127.0.0.1:8080/v1/subject/realtime/balance?currency=USD' \
  -H 'Authorization: Bearer <subject-token>'

Response

200 OK

{
  "tenant_id": "tenant_123",
  "project_id": "proj_demo",
  "account_id": "acct_001",
  "currency": "USD",
  "balance": "12",
  "available_balance": "17",
  "cash_balance": "10",
  "cash_available_balance": "15",
  "voucher_available_balance": "2",
  "credit_limit": "5"
}

Field	Contract
`tenant_id / project_id`	Owning tenant and token project.
`account_id`	Resolved payer account; may be shared by multiple subjects.
`currency`	Normalized currency.
`balance`	Realtime cash balance plus currently available voucher funds.
`available_balance`	Cash available balance including credit capacity, plus currently available vouchers.
`cash_balance`	Optional cash balance component.
`cash_available_balance`	Optional available cash component, including credit capacity.
`voucher_available_balance`	Optional currently available voucher component; expired or revoked vouchers are excluded.
`credit_limit`	Account cash credit limit. All balances are decimal strings.

Errors

Errors return an HTTP status and {"error":"<message>"}. The error field is a public English string; internal causes are retained only in server logs.

Status	Meaning
`400`	Required currency is missing.
`401`	Subject Token is missing or invalid.
`403`	The token lacks the `analysis` rule, or a non-empty `account_id` was supplied.
`404`	The token’s subject has no route (`subject route not found`), or the routed account has no wallet in that project and currency (`account wallet not found`).
`500`	A database operation failed or stored balance data could not be decoded.
`503`	The Subject Token service, required cache, or wallet lock is unavailable, or cache state could not be restored.

{"error":"subject route not found"}