Reporting and Exports

Reporting pulls records back out of the platform for reconciliation, compliance, and tax filing. Three read-only surfaces do this: the reports namespace queries the audit trail, the revenue namespace reads the fee revenue a workspace earns, and the treasury tax surface exports confirmed treasury transfers as 1099 and per-transfer files. Every one of these is a read or a download; none of them move value or change state. All are tenant-scoped, so a report only ever returns the calling tenant's own data.

Three Reporting Surfaces

The reporting surfaces are read-only and split by what they answer. The audit reads tell 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

All three reject a partner-scoped caller with partner_scope_denied. Partner scope is an internal platform scope above tenants; integrators do not use it. 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 reports namespace exposes a single query today: read the tenant's audit trail with GET /v1/reports/audit. It returns a cursor-paginated list of recorded actions and takes 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.

Route	Returns
`GET /v1/revenue/setup-status`	Whether revenue is wired: an active designated revenue treasury and a committed earned-fee schedule must both be present before earned revenue flows.
`GET /v1/revenue/summary`	Per-token earned totals for the workspace, with an optional `date_from` and `date_to` window.
`GET /v1/revenue/logs`	One row per earned fee event, cursor-paginated, filterable by `token` and date range, sortable by `date` or `amount`.
`GET /v1/revenue/logs.csv`	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.

Route	Shape	Role
`GET /v1/treasury/tax/1099-summary`	JSON summary of reportable counterparties for a year, each with a USD total and a transaction count.	Treasury admin
`GET /v1/treasury/tax/1099-misc.csv`	CSV, one row per reportable counterparty, with legal name, display name, tax id, tax id type, classification, total, and count.	Treasury admin
`GET /v1/treasury/tax/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, Scope, and Errors

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 route is tenant-scoped and returns only the calling tenant's data. A caller without the right permission, role, or feature is rejected rather than handed a filtered view.

Code	When
`unauthorized`	No valid authentication on the request.
`partner_scope_denied`	A partner-scoped key called a tenant-scoped report.
`role_denied`	The caller does not hold `report.read` for the audit query.
`treasury_role_denied`	The caller holds no treasury role high enough for the tax export.
`feature_not_enabled`	The `revenue_controls` or `treasury` feature is off for the tenant.
`validation_failed`	A malformed year, date, or filter value.

See Errors and Correlation IDs for the full catalog and how to correlate a failed report call.

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.

For the exact request and response shapes, see the operations list or try the calls live in the interactive reference.

Was this helpful?