> ## 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.

# API Reference

> High-Performance Transaction System (HPTS) — lending ledger API

## Overview

HPTS is the sole programmatic interface to the Clarivo 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.

**Base URL:** `https://ledger.clarivo.co/v1`

## Core invariants

| # | Invariant               | Detail                                                  |
| - | ----------------------- | ------------------------------------------------------- |
| 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 auth for B2B** | Partner endpoints require mTLS + OAuth.                 |

## Authentication

All endpoints are secured with OAuth 2.0 bearer tokens. Tokens are validated at the API
Gateway via a Lambda Authorizer that checks signature, `iss`, `aud`, `exp`, `nbf`, and
the `tenant_id` custom claim. Each operation requires a specific scope.

```http theme={null}
Authorization: Bearer <access_token>
```

B2B partner endpoints additionally require mutual TLS — present a client certificate
issued by AWS Private CA alongside your bearer token.

## Idempotency

Every `POST` request **must** include an `Idempotency-Key` header.

* Keys are scoped per tenant and retained for **24 hours minimum**.
* Same key + same payload → returns the original result (`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`.

**Recommended key format:** `<event_type>:<resource_id>:<natural_key>`

```
payment:loan_42:proc_txn_abc123
accrual:prog_7:2026-04-15
```

## Errors

All errors follow [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) with
`Content-Type: application/problem+json`. Field-level validation failures include an
optional `errors[]` array with `field`, `code`, and `message`.