> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarivo.co/llms.txt > Use this file to discover all available pages before exploring further. # General-ledger account balance ## OpenAPI ````yaml /api-reference/openapi.yaml get /accounts/{account_code}/balance openapi: 3.1.0 info: title: High-Performance Transaction System (HPTS) API version: 1.0.0 summary: Append-only ledger posting and balance retrieval API for lending. description: > HPTS is the sole programmatic interface to the lending ledger. All money-movement events — payments, disbursements, daily accruals, reversals — are posted through this API. All balance and history reads are served through this API. ## Invariants enforced by this API 1. **Append-only.** No mutation endpoints exist. Corrections are reversals. 2. **Double-entry.** Every posting produces balanced journal lines. 3. **Idempotent writes.** Every `POST` requires an `Idempotency-Key` header. 4. **Tenant-isolated.** Every request is scoped to one tenant via JWT claims. 5. **Mutual authentication for B2B.** Partner endpoints require mTLS + OAuth. ## Idempotency contract - Clients MUST send `Idempotency-Key` on every `POST`. - Keys are scoped per tenant and retained for 24 hours minimum. - Same key + same payload → returns the original result with HTTP 200. - Same key + different payload → HTTP 422 with `idempotency_mismatch`. - Concurrent requests with the same in-flight key → HTTP 409 with `idempotency_in_progress`. ## Error format All errors follow RFC 7807 Problem Details with an optional `errors[]` array for field-level validation issues. contact: name: HPTS Platform Team email: platform-hpts@example.com license: name: Proprietary x-audience: internal, b2b-partners x-api-id: hpts-core-v1 x-tagGroups: - name: Core Write (Go Lambda) tags: - payments - disbursements - accruals - reversals - name: Read / BFF (TypeScript Lambda) tags: - balances - journal - reconciliation - name: Operations tags: - health x-api-slo: p99_latency_ms: core_write_endpoints: 100 bff_read_endpoints: 300 availability_pct: 99.95 servers: - url: https://ledger.clarivo.co/v1 description: Production - url: https://ledger.staging.clarivo.co/v1 description: Staging - url: https://ledger.dev.clarivo.co/v1 description: Development - url: https://partner.hpts.example.com/v1 description: B2B partner endpoint (mTLS required) - url: http://localhost:3000/v1 description: Local (cmd/server) - url: http://localhost:4010/v1 description: Local Prism mock security: - bearerAuth: [] tags: - name: payments description: Payment lifecycle — high-throughput Go Lambda. x-stack: go - name: disbursements description: Loan disbursement postings — Go Lambda. x-stack: go - name: accruals description: Batch interest accrual — Go Lambda. x-stack: go - name: reversals description: Journal entry reversal postings — Go Lambda. x-stack: go - name: balances description: Balance queries (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: journal description: Journal entry retrieval (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: reconciliation description: Reconciliation status (BFF) — Node/TypeScript Lambda. x-stack: typescript - name: health description: Operational health endpoints. paths: /accounts/{account_code}/balance: get: tags: - balances summary: General-ledger account balance operationId: getAccountBalance parameters: - name: account_code in: path required: true schema: type: string pattern: ^[0-9]{4}$ description: Four-digit GL account code (e.g. `1100` for Principal Receivable) - $ref: '#/components/parameters/Currency' - $ref: '#/components/parameters/Layer' - $ref: '#/components/parameters/AsOfDate' responses: '200': description: Account balance content: application/json: schema: $ref: '#/components/schemas/AccountBalance' '404': $ref: '#/components/responses/NotFound' security: - bearerAuth: - hpts:balances:read components: parameters: Currency: name: currency in: query required: true schema: $ref: '#/components/schemas/CurrencyCode' Layer: name: layer in: query required: false schema: $ref: '#/components/schemas/EntryLayer' AsOfDate: name: as_of_date in: query required: false description: Point-in-time balance; defaults to now. schema: type: string format: date schemas: AccountBalance: type: object required: - account_code - currency - layer - as_of_date - dr_balance_minor - cr_balance_minor - normal_balance_minor additionalProperties: false properties: account_code: $ref: '#/components/schemas/AccountCode' account_name: type: string currency: $ref: '#/components/schemas/CurrencyCode' layer: $ref: '#/components/schemas/EntryLayer' as_of_date: type: string format: date dr_balance_minor: $ref: '#/components/schemas/AmountMinor' cr_balance_minor: $ref: '#/components/schemas/AmountMinor' normal_balance_minor: $ref: '#/components/schemas/AmountMinor' CurrencyCode: type: string description: ISO 4217 three-letter currency code. pattern: ^[A-Z]{3}$ minLength: 3 maxLength: 3 examples: - USD - MXN - EUR EntryLayer: type: string enum: - SETTLED - PENDING - ENCUMBRANCE default: SETTLED AccountCode: type: string pattern: ^[0-9]{4}$ description: Four-digit GL account code. examples: - '1000' - '1100' - '1200' AmountMinor: type: string description: | Non-negative integer amount in the currency's minor unit, serialized as a string to preserve precision (JS numbers cannot safely represent values above 2^53). BIGINT on the wire, BIGINT in the database. pattern: ^(0|[1-9][0-9]{0,18})$ minLength: 1 maxLength: 19 examples: - '88849' - '10000000' Problem: type: object required: - type - title - status additionalProperties: true properties: type: type: string format: uri description: URI identifying the problem type. examples: - https://errors.hpts.example.com/bad_request title: type: string description: Human-readable summary, same across occurrences. status: type: integer minimum: 400 maximum: 599 detail: type: string description: Human-readable explanation specific to this occurrence. instance: type: string format: uri description: URI identifying this specific occurrence. trace_id: type: string description: Distributed-trace ID for cross-system correlation. responses: NotFound: description: Resource not found (or not visible to this tenant) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: bearerAuth: type: oauth2 description: | OAuth2 JWT bearer tokens. Tokens are validated at API Gateway via a Lambda Authorizer that verifies signature against the issuer's JWKS, checks `iss`, `aud`, `exp`, `nbf`, and the `tenant_id` custom claim. Granular scopes are required per operation. flows: clientCredentials: tokenUrl: https://auth.example.com/oauth2/token scopes: hpts:payments:write: Post payment events hpts:disbursements:write: Post disbursement events hpts:accruals:write: Post batch accruals hpts:reversals:write: Post reversals (privileged; audited) hpts:ledger:read: Read journal entries hpts:balances:read: Read balances hpts:loans:read: Read loan metadata hpts:reconciliation:read: Read reconciliation reports hpts:admin:*: Administrative operations authorizationCode: authorizationUrl: https://auth.example.com/oauth2/authorize tokenUrl: https://auth.example.com/oauth2/token refreshUrl: https://auth.example.com/oauth2/token scopes: hpts:balances:read: Read balances hpts:ledger:read: Read journal entries ````