GET /api/vaults/:vaultId/broker-history — Conduct Record

Reconstructs the broker’s public transaction history, scores the default ordering against the fair sequence, and returns a reputation grade with findings.

Use this endpoint to examine what a vault manager actually did with their cover pool. The response reconstructs the full default and impairment history from public ledger transactions, computes what the fair declaration order would have paid depositors, and grades the manager’s conduct against that benchmark. If two or more distressed loans are currently standing, it also recommends which to declare next to maximise depositor recovery.

Parameters

vaultId · string · required

64-character hex object ID of the Vault ledger entry. The first LoanBroker associated with the vault is used. Case insensitive.

This route is cached for 15 seconds per broker — reconstructing the history requires many ledger round-trips.

Request

curl -s http://localhost:8787/api/vaults/24EAA01AD4CE70D8ABB4ACB4255DC4C216B8AF3B9E7315DB8052BFC1E5810089/broker-history

Response

{
  "serverTime": "2026-09-12T22:20:22Z",
  "ledgerIndex": 5263343,
  "loanBrokerId": "8DB104980C31CBE9F196508E7D748E8C31FB783CD4E0A3620AE0B476CBDEA3FA",
  "owner": "rD26gw5goDqU784caePMoA82givcJBjStk",
  "events": [
    {
      "kind": "default",
      "at": "2026-09-12T21:11:02Z",
      "hash": "FB23EC5313F85FA157D56966E0B0B1665068905988D925C70BB0E7C35C3B221B",
      "loanId": "3D830C8049389AD0E7037933D21443635F35077D3A462A2C9783647354A644FE",
      "brokerStateKnown": true,
      "debtBefore": "40000000",
      "debtAfter": "10000000",
      "coverBefore": "10000000",
      "coverAfter": "9600000",
      "coverConsumed": "400000",
      "principal": "30000000",
      "exposure": "30000000"
    },
    {
      "kind": "default",
      "at": "2026-09-12T21:11:10Z",
      "hash": "DE49DF0D6136B96AD28B253CD32100E5715078FD2D0AE6D1DB747AFECB803D1F",
      "loanId": "74402C23FE8E2B30ACAC4A5001AF8D491DFC8A38924125798511618331B452C7",
      "brokerStateKnown": true,
      "debtBefore": "10000000",
      "debtAfter": "0",
      "coverBefore": "9600000",
      "coverAfter": "9500000",
      "coverConsumed": "100000",
      "principal": "10000000",
      "exposure": "10000000"
    }
  ],
  "ordering": {
    "applicable": true,
    "defaultCount": 2,
    "actualCoverPaid": "500000",
    "bestPossible": "700000",
    "worstPossible": "500000",
    "costToDepositors": "200000",
    "spread": "200000",
    "fairness": "0.0000",
    "fairOrder": ["10000000", "30000000"]
  },
  "reputation": {
    "grade": "E",
    "score": 25,
    "observations": {
      "defaults": 2,
      "impairments": 0,
      "defaultsWithoutPriorImpairment": 2,
      "coverWithdrawals": 0,
      "eventsRetained": 3
    },
    "findings": [
      {
        "code": "ORDERING_SELF_SERVING",
        "detail": "Declared losses in an order close to the one that minimises their own first-loss contribution (sequence score 0.0000). The choice cost investors 0.200000 XRP against the fair order."
      },
      {
        "code": "DEFAULT_WITHOUT_IMPAIRMENT",
        "detail": "2 exposures were written off with no prior warning, so the loss was never signalled before it was taken."
      }
    ],
    "caveat": "Reconstructed from the public record only, which is retained for roughly 29 days. Conduct before that window is not visible here."
  },
  "recommendation": {
    "applicable": false,
    "reason": "fewer than two distressed loans",
    "candidates": 0
  }
}

Response Fields

loanBrokerId · string

64-character hex object ID of the LoanBroker whose history was reconstructed.

owner · string

XRPL address of the vault manager who controls this broker.

events · array

All default, impairment, and cover-deposit events found in the broker’s public transaction history, in chronological order.

Show event fields

kind · string

Event type: "default", "impairment", or "cover_deposit".

at · string

ISO 8601 timestamp of the transaction.

hash · string

64-character hex transaction hash.

loanId · string

64-character hex loan object ID. Present on default and impairment events.

brokerStateKnown · boolean

Whether the broker’s book state before and after this event could be reconstructed. false for impairments, because LoanImpair does not touch the LoanBroker object.

debtBefore · string | null

Total broker debt before this event, in drops. null when brokerStateKnown is false. See contract 2.

debtAfter · string | null

Total broker debt after this event, in drops. null when brokerStateKnown is false.

coverBefore · string | null

Cover available before this event, in drops. null when brokerStateKnown is false.

coverAfter · string | null

Cover available after this event, in drops. null when brokerStateKnown is false.

coverConsumed · string

Cover liquidated by this event, in drops. Always present; "0" for impairments and cover deposits.

principal · string

Loan principal involved in this event, in drops.

exposure · string

Total exposure written off, in drops.

ordering · object

Analysis of how the manager’s declaration order compared to the sequence most beneficial to depositors.

Show ordering fields

applicable · boolean

true when at least two defaults are present. With only one default, no sequence comparison is possible.

actualCoverPaid · string

Total cover liquidated in the observed sequence, in drops.

bestPossible · string

Cover that would have been liquidated in the depositor-best sequence, in drops.

worstPossible · string

Cover that would have been liquidated in the depositor-worst sequence, in drops.

costToDepositors · string

bestPossible - actualCoverPaid: the cover depositors lost due to the observed ordering, in drops.

spread · string

bestPossible - worstPossible: the maximum possible ordering effect, in drops.

fairness · string

Normalised fairness score between "0.0000" (investor-worst) and "1.0000" (investor-best). Defined as "1.0000" when bestPossible equals worstPossible.

fairOrder · array

The depositor-optimal sequence: principal amounts in the order they should have been declared.

reputation · object

Composite reputation grade and supporting findings.

Show reputation fields

grade · string

Reputation letter grade from "A" (excellent) to "E" (poor).

score · number

Numeric score underlying the grade.

observations · object

Counts of observed events: defaults, impairments, defaultsWithoutPriorImpairment, coverWithdrawals, eventsRetained.

findings · array

Specific conduct issues identified.

Show finding fields

code · string

Machine-readable finding code, e.g. "ORDERING_SELF_SERVING", "DEFAULT_WITHOUT_IMPAIRMENT", "COVER_WITHDRAWAL_AFTER_DISTRESS".

detail · string

Plain-English explanation of the finding, including quantified impact where available.

caveat · string

Statement of the data window limitation. XRPL retains transaction history for approximately 29 days; conduct before that window is not visible.

recommendation · object

Forward-looking advice on which distressed loan to declare next.

Show recommendation fields

applicable · boolean

true only when two or more distressed loans are currently standing.

reason · string

Explanation of why a recommendation was or was not produced.

candidates · number

Number of distressed loans currently eligible for declaration.

The cover liquidated on any one default is T(p) = min(⌈D × c_min × c_liq⌉, p, C) where D is the broker’s total book — not the principal of the exposure that defaulted — and D decrements as each default lands. Declaring the largest exposure first consumes the least first-loss capital. In the captured example, declaring 30 XRP first then 10 XRP consumed 500 000 drops of cover; the reverse order would have consumed 700 000. The 200 000 drop difference falls on unit holders despite identical total losses.

LoanManage carries no LoanBrokerID, and an impairment does not touch the LoanBroker object at all — so a naive filter over account_tx silently drops every impairment. The join that recovers them is Loan.FinalFields.LoanBrokerID in the same transaction’s metadata. Without this join, every unsignalled default looks like the manager was penalised for disclosing; with it, the record is complete.