Export reference

Every request must include a valid JSON Web Token (JWT) in the Authorization header:

Authorization: Bearer <jwt>

The service uses a user-based authentication model. There's no separate machine credential flow: you must register even bot and service accounts as users with the appropriate roles in each domain they need to access. This ensures every export traces back to a specific, verifiable identity.

The token subject identifies the requesting user in providerId:loginId form. The service records this identity as the request author in every export's metadata.

Authorization is target-domain-only. To generate a report for a domain, all of the following must be true:

1. You have a profile in the exact target domain.
2. Your user account is unlocked.
3. The target domain is unlocked.
4. One of your roles grants read access to the relevant entity type in that domain.

The entity type depends on the report:

The service verifies domain access before running any data query. If you lack access, it contacts neither the balance source nor the database.

A profile in a parent domain does not grant access to its children. You must hold a profile with a matching role in each domain you want to export. This prevents broad, unintended access through high-level parent profiles.

When you set includeChildDomains to true, the service resolves the full domain tree and checks each child domain independently, using the same target-domain-only rule. It includes children you can access and silently omits children you can't access. You receive a valid report containing only the domains you're entitled to, with no error about the domains it excluded.

Each request returns the complete report file in one synchronous response. The service does not paginate results. To keep reports within the operational limits, narrow the scope with filters or a shorter date range and split large exports into several requests.

Both endpoints accept POST requests with a Content-Type of application/json.

If you submit the same parameters again within 60 seconds while a previous export is still processing, the service returns 429. This prevents an accidental double-submission from triggering redundant work.

You can have at most 2 exports processing at any time. A third concurrent request returns 429. Wait for an in-flight export to finish, then retry.

Select the format with the format field in the request body.

The service encodes CSV files as UTF-8 with a byte order mark (BOM) for spreadsheet compatibility, and uses \r\n (CRLF) line endings. The structure is:

All financial values are quoted strings (for example, "0.000000000000000001"). This prevents spreadsheet software and CSV parsers from silently truncating high-precision decimals.

JSON responses wrap the data in a metadata envelope:

{
  "metadata": {
    "exportId": "uuid",
    "requestAuthor": "providerId:loginId",
    "generatedAt": "ISO-8601",
    "filters": { },
    "recordCount": 1234,
    "controlTotals": { }
  },
  "data": [ ]
}

The metadata also carries the report's time parameters: asOfTimestamp for the Position Report, and dateRangeStart and dateRangeEnd for the Movement Report.

Financial values in JSON are strings, never bare numbers. Always parse them as strings.

The service exports every financial value as a decimal string in the asset's native unit, with precision matching the asset's decimal places. It never exports raw blockchain denominations (except the Movement Report's explicit rawTransactionValue column) or scientific notation.

The service rounds down, consistent with banking practice: an export never reports more value than actually exists.

Errors return a standard HTTP status code with a client-safe JSON body. Error messages never expose internal details such as query fragments, stack traces, service names, or file paths. The service logs detailed diagnostics on the server against the export ID for correlation.

Every error body carries a numeric statusCode, a short error label, and a message:

{
  "message": "Access denied",
  "error": "Forbidden",
  "statusCode": 403
}

For 400 validation failures, message is an array of one or more client-safe validation strings that name the offending field:

{
  "message": ["asOfTimestamp must not be in the future"],
  "error": "Bad Request",
  "statusCode": 400
}

Every message value is client-safe: it never exposes internal details such as query fragments, stack traces, service names, or file paths.