Skip to main content
GET
Get the client-level portfolio insight report (BETA)

Authorizations

x-api-key
string
header
required

Query Parameters

customer_id
string

Scope the whole report to one customer (drill-down). An unknown or foreign customer is a 404, mirroring the customer report.

wallet_id
string

Keep only items whose evidence references this wallet.

kind
string[]

Keep only items of these kinds (comma-separated, e.g. kind=volume_anomaly,recipient_dormant; open set — an unrecognized value simply matches nothing).

severity
string[]

Keep only items of these severities (comma-separated, e.g. severity=critical,warn). Values are info, warn, critical; anything else is a 400.

responsibility
string[]

Keep only items carrying one of these grouping labels (comma-separated).

window_days
integer
default:14

Report window in days — the lookback for trends/series and the horizon for upcoming obligations.

Required range: 1 <= x <= 90

Response

The client's portfolio insight report

The deterministic, read-only portfolio insight report for the calling client. Computed on demand across the client's own customers (never cross-tenant); nothing is stored.

generated_at
integer<int64>
required
window_days
integer
required
snapshot
object
required

Typed FACTS about the client's whole book — rendered directly, not narrated. total_usd covers indexed funding-wallet balances and is present only when the balance index is configured; it degrades to absent, never to an error. balances (per wallet × asset) is present only when the report is scoped to one customer (?customer_id=), so a drill-down can show that customer's holdings overall, by asset and by wallet.

facets
object
required

The values present in the report BEFORE the item filters (kind, severity, responsibility) were applied — so a UI can offer every option a client could pick even while a filter is active. assets are the assets moving in the window (metrics + series).

series
object
required

Daily time series for charts. Map keys are an OPEN set named <metric> for counts and <metric>.<ASSET> for amounts — emitted today: executed_payments, failed_payments, executed_volume.<ASSET> (lookback over the report window) and upcoming_obligations.<ASSET> (forward-looking: open payments due per day from now through the next window_days; an OVERDUE open payment is not plotted here — it is counted in snapshot.upcoming, which spans everything due through the horizon, and surfaces as a payment_at_risk item). Clients must ignore keys they do not recognize.

insights
object[]
required

Observations across the book (always present, possibly empty).

suggestions
object[]
required

Advisory recommendations (always present, possibly empty). Non-binding — acting on one is a separate, human-gated step.

customers
object[]
required

Per-customer roll-up for the drill-down table, sorted worst-first (critical count, then warn, then activity).