Reporting and Exports

Reporting pulls records back out of the platform for reconciliation, compliance, and tax filing. The management Console provides tenant-scoped audit views, earned-revenue views, and treasury tax exports. These management capabilities are not currently published as customer API or @xkova/sdk operations.

Three Reporting Views

The Console reporting views are read-only and split by what they answer. The audit view tells you what happened, the revenue reads tell you what a workspace earned, and the tax exports assemble what a workspace paid out to its counterparties for the year.

Surface	Reads	Formats	Access
Audit reports	Recorded actions across the tenant	JSON	The `report.read` permission
Revenue reads	Fee revenue the active workspace earns	JSON and CSV	The `revenue_controls` feature
Treasury tax exports	Confirmed treasury transfers to counterparties	JSON and CSV	A treasury role plus the `treasury` feature

These views are available to authorized management Console users. Their private routes are intentionally absent from the customer API reference and @xkova/sdk.

See Authorization and RBAC for how roles map to permissions, and Entitlements and Feature Gates for how the feature flags above are resolved.

Audit Reports

The management Console provides a cursor-paginated view of recorded tenant actions and a filter set for narrowing to the events a report needs.

Filter	Effect
`category`	The event family (for example a payment, treasury, or compliance action).
`action`	The specific action recorded.
`actor_id`	Who took the action.
`target_type` and `target_id`	The resource the action touched.
`correlation_id`	The full audit footprint of one request, for tracing an incident.
`date_from` and `date_to`	An ISO-8601 time window.

Results sort by occurred_at, newest first by default, and you can flip order to asc. Paging uses the standard cursor contract with next_cursor and has_more; see Pagination and Cursors. Reading this surface requires the report.read permission, which owner and admin roles hold, along with the compliance officer role.

This is the query surface over the audit trail. For the event model itself, what an audit event records, which actions are audited, and how the authority exercised is stamped on each row, see Audit Log.

Revenue Reads

The revenue namespace reads the fee revenue a workspace earns. Earned revenue is the fee flowing to the workspace's own beneficiaries; it is disjoint from the platform fee a tenant pays, which lives under a separate billing surface. The fee mechanics behind these totals are covered in Fee Schedules. This namespace is gated by the revenue_controls feature and is tenant-scoped.

Console view or export	Returns
Setup readiness	Whether revenue is wired: an active designated revenue treasury and a committed earned-fee schedule must both be present before earned revenue flows.
Revenue summary	Per-token earned totals for the workspace, with an optional `date_from` and `date_to` window.
Revenue log	One row per earned fee event, cursor-paginated, filterable by `token` and date range, sortable by `date` or `amount`.
Revenue CSV export	The same filtered rows as the log query, but the full dataset with no pagination, as a CSV download.

Each log row carries the settlement details of a single earned fee: the date, the transaction hash, the originating payment, the token and its beneficiary, and the amount. The summary rolls those rows up to one earned total per token. Both are backed by the on-chain fee events scoped to the workspace, so the numbers reconcile against settlement rather than an internal estimate.

Treasury Tax Exports

The treasury tax surface assembles the confirmed treasury transfers a workspace sent to its counterparties into year-end tax files. It reads only confirmed transfers of kind transfer inside the requested window, using UTC year boundaries. Only stablecoin assets contribute to the USD totals, since the export assumes one-to-one stablecoin parity; a non-stable asset transfer is recorded but excluded from the tax total. The surface is gated by the treasury feature.

Console export	Shape	Role
1099 summary	JSON summary of reportable counterparties for a year, each with a USD total and a transaction count.	Treasury admin
1099 CSV	CSV, one row per reportable counterparty, with legal name, display name, tax id, tax id type, classification, total, and count.	Treasury admin
Transactions CSV	CSV, one row per confirmed transfer in a date range, optionally filtered to a single counterparty. No aggregation.	Treasury viewer or higher

Who Is Reportable

A counterparty appears in the 1099 summary and the 1099 CSV only when its stablecoin transfers for the year total at least 600 USD, the federal 1099-MISC reporting floor for non-employee compensation. A transfer that is not mapped to a counterparty, and any counterparty below the floor, is omitted from the 1099 files. Those transfers still appear in the transactions CSV, which is the unfiltered per-transfer record. Populate a counterparty's legal name, tax id, and classification so the 1099 rows carry the fields a filing needs; the tax id type is one of ein, ssn, foreign, or none. See Treasury for how counterparties are managed.

Date Windows

The 1099 routes take a single year and derive the UTC year boundary themselves. The transactions CSV takes an explicit from and to, where from is inclusive and to is exclusive. To pull the full 2026 calendar year, pass from=2026-01-01 and to=2027-01-01.

Exports and Scope

The CSV exports are recorded actions in their own right: downloading a revenue log CSV, a 1099 CSV, or a transactions CSV writes a data-access audit event, so a report pull is itself auditable. Every reporting capability is tenant-scoped and returns only that tenant's data. A Console user without the required role or enabled feature is rejected rather than handed a filtered view.

Audit Log: the event model behind the audit report query.
Fee Schedules: how earned revenue is priced and accrued.
Treasury: the treasury transfers and counterparties the tax exports read.
Entitlements and Feature Gates: how the revenue and treasury features are resolved.

Programmatic reporting is not part of the current customer operation manifest. Do not infer a customer endpoint from the Console capability described here.

Was this helpful?