Get Realtime Wallet Amount

Returns the account-owned realtime wallet balance. When the request identifies a subject, Meterry resolves only subject -> billing account; it does not load usage-limit policy, limit windows, or reset state.

GET /v1/projects/:project_id/wallets/realtime/amount

Authentication

Authorization: Bearer <api-key>

Path Parameters

Field	Required	Type	Description
`project_id`	Yes	string	Project that owns the account or subject route.

Request

This endpoint has no request body. Supply its input as query parameters.

Field	Required	Type	Description
`account_id`	Conditional	string	Billing account ID. Use this for a direct account lookup.
`subject_type`	Conditional	string	Subject type, for example `user` or `api_key`. Required with `subject_id` when `account_id` is omitted.
`subject_id`	Conditional	string	Subject ID. Required with `subject_type` when `account_id` is omitted.
`currency`	Yes	string	ISO-style wallet currency. The server normalizes it to uppercase.

Provide account_id, or provide both subject_type and subject_id. If both forms are sent, account_id is the wallet identity used for the amount lookup.

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/wallets/realtime/amount?subject_type=user&subject_id=user_123&currency=usd' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "account_id": "acct_org_001",
  "currency": "USD",
  "balance": "982.45",
  "available_balance": "1082.45",
  "cash_balance": "900.00",
  "cash_available_balance": "1000.00",
  "voucher_available_balance": "82.45",
  "credit_limit": "100.00"
}

Field	Type	Description
`tenant_id`	string	Tenant that owns the wallet.
`project_id`	string	Project that owns the wallet.
`account_id`	string	Billing account whose funds are returned.
`currency`	string	Normalized wallet currency.
`balance`	decimal string	Combined cash and currently available voucher balance.
`available_balance`	decimal string	Combined funds available for future usage, including credit limit where applicable.
`cash_balance`	decimal string	Cash wallet balance before voucher funds.
`cash_available_balance`	decimal string	Cash funds available before voucher funds.
`voucher_available_balance`	decimal string	Available voucher funds included in the combined values.
`credit_limit`	decimal string	Configured cash credit limit.

All money values are decimal strings. This endpoint never includes limits; use Get Subject Realtime Limits for subject limit usage.

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`	Missing currency or account/subject identity, or an incomplete subject pair.
`404`	The subject route does not exist (`subject route not found`), or the account has no wallet for this project and currency (`account wallet not found`).
`500`	A database operation failed or stored balance data could not be decoded.
`503`	A required cache or wallet lock is unavailable, or its state could not be restored.

{"error":"account wallet not found"}

Authentication and authorization failures follow the HTTP entry error contract.