> ## 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. # Current balance for a loan (all sub-accounts) ## OpenAPI ````yaml /api-reference/openapi.yaml get /loans/{loan_id}/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: /loans/{loan_id}/balance: get: tags: - balances summary: Current balance for a loan (all sub-accounts) operationId: getLoanBalance parameters: - $ref: '#/components/parameters/LoanIdPath' - $ref: '#/components/parameters/AsOfDate' - $ref: '#/components/parameters/TraceId' responses: '200': description: Loan balance content: application/json: schema: $ref: '#/components/schemas/LoanBalance' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - bearerAuth: - hpts:balances:read components: parameters: LoanIdPath: name: loan_id in: path required: true schema: $ref: '#/components/schemas/Uuid' AsOfDate: name: as_of_date in: query required: false description: Point-in-time balance; defaults to now. schema: type: string format: date TraceId: name: X-Trace-Id in: header required: false deprecated: true description: | **Deprecated — use `traceparent` instead (ADR-0011).** Client-supplied correlation ID. Accepted until 2026-10-01 for backward compatibility; will be removed after that date. schema: type: string pattern: ^[A-Za-z0-9\-]{8,128}$ schemas: LoanBalance: type: object required: - loan_id - currency - as_of_date - principal_outstanding_minor - interest_receivable_minor - fees_receivable_minor - total_exposure_minor additionalProperties: false properties: loan_id: $ref: '#/components/schemas/Uuid' currency: $ref: '#/components/schemas/CurrencyCode' as_of_date: type: string format: date principal_outstanding_minor: $ref: '#/components/schemas/AmountMinor' interest_receivable_minor: $ref: '#/components/schemas/AmountMinor' fees_receivable_minor: $ref: '#/components/schemas/AmountMinor' total_exposure_minor: $ref: '#/components/schemas/AmountMinor' last_activity_at: $ref: '#/components/schemas/Timestamp' Uuid: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - 11111111-1111-1111-1111-111111111111 CurrencyCode: type: string description: ISO 4217 three-letter currency code. pattern: ^[A-Z]{3}$ minLength: 3 maxLength: 3 examples: - USD - MXN - EUR 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' Timestamp: type: string format: date-time description: RFC 3339 timestamp, UTC. 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: Unauthorized: description: Missing or invalid credentials content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: Authenticated but not authorized for this scope/tenant content: application/problem+json: schema: $ref: '#/components/schemas/Problem' 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 ````