Async Reports

Statement and transaction reports are generated asynchronously. You start a job, poll it until it finishes, then download the resulting file(s). Reports for large periods are split into multiple parts and may be produced in more than one file format.

There are two report types, each with an identical lifecycle:

Report type	Base path	What it contains
`statements`	`/v2/account/reports/statements`	All balance changes (the same data as Account Statement)
`transactions`	`/v2/account/reports/transactions`	Ticket/transaction history, with rich filters

All endpoints below authenticate as the current account (same Bearer token as the rest of the /v2/account API). Identity is always taken from the token — any userId in a request body is ignored. Pass subAccountId to scope a report to a sub-account.

Lifecycle

POST   /v2/account/reports/{type}              → 202  { jobId, status: "running" }
GET    /v2/account/reports/{type}/{jobId}      → 200  { status, fileUrls, ... }   (poll until "success")
GET    /v2/account/reports/{type}/{jobId}/download?format=&part=   → 302 redirect to presigned S3 URL
GET    /v2/account/reports/{type}              → 200  { reports: [...] }           (list past jobs)

Job status is one of: queued, running, success, failed.

1. Generate a report

`POST /v2/account/reports/statements`

Field	Type	Required	Description
`periodStart`	String	Yes	Start of the period. `YYYY-MM-DD` or RFC3339 (e.g. `2025-06-01`).
`periodEnd`	String	Yes	End of the period (see Period rules).
`format`	String	No	One of `ofx`, `xlsx`, `pdf`, `csv`, `json`. Default `xlsx`.
`maxStatementsPerFile`	Number	No	Split output into files of at most N rows. `1`–`500000`.
`description`	String	No	Filters entries by description (partial, case-insensitive match). See Statement description filter.
`subAccountId`	String	No	Generate the report for a sub-account instead of the main account.

Statement description filter

description is a substring filter — it is not a fixed list, so any text is accepted and matches entries whose description contains it. Statement entry descriptions follow the shape:

[DEBIT|CREDIT] <event>: <detail>

The vast majority of entries are ticket movements. Useful substrings to filter on:

Substring	Matches
`Burn`	Ticket inputs (the token burned to pay a ticket).
`delivery`	Ticket outputs (the token delivered by a ticket).
`markup`	Markup deliveries.
`rebate`	Rebate deliveries.
`transfer failed`	Deliveries re-credited after an off-chain transfer failed (also `Pix failed`).
`conversion`	Token conversions (e.g. USDT → USDC).
`EoD settlement`	End-of-day settlement mints/burns.
`USDM yield`	Daily USDM yield distributions.

Common full descriptions (token varies — BRLA, USDC, USDT, EURC):

[DEBIT] Process ticket input: Burn BRLA for ticket payment
[CREDIT] Process ticket output: BRLA delivery
[CREDIT] Process ticket output: USDC markup delivery
[CREDIT] Process ticket output: BRLA delivery because Pix failed
[DEBIT] Process ticket input and output: Burn USDT for ticket payment

`POST /v2/account/reports/transactions`

Field	Type	Required	Description
`periodStart`	String	Yes	Start of the period. `YYYY-MM-DD` or RFC3339.
`periodEnd`	String	Yes	End of the period (see Period rules).
`format`	String	No	One of `xlsx`, `csv`, `json`. Default `xlsx`.
`maxRecordsPerFile`	Number	No	Split output into files of at most N records. `1`–`500000`.
`includeSubAccounts`	Boolean	No	Include all sub-account transactions in the report.
`subAccountId`	String	No	Scope the report to a single sub-account.
`status`	String	No	Filter by transaction status.
`hasFailureReason`	String	No	`"true"` / `"false"`.
`endToEndId`	String	No	Filter by PIX end-to-end ID.
`cpTaxId`	String	No	Filter by counterparty tax ID.
`minAmountIn` / `maxAmountIn`	Number	No	Filter by inbound amount range.
`minAmountOut` / `maxAmountOut`	Number	No	Filter by outbound amount range.
`coinIn` / `coinOut`	String	No	Filter by input/output coin (e.g. `BRLA`, `USDC`).
`walletIn` / `walletOut`	String	No	Filter by input/output wallet address.
`operationType`	String	No	Filter by operation type.

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/reports/transactions" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "periodStart": "2025-06-01",
    "periodEnd": "2025-06-30",
    "format": "csv",
    "includeSubAccounts": true,
    "coinOut": "BRLA"
  }'

Response — `202 Accepted`

{
  "jobId": "b3f1c9e2-8a4d-4e77-9c21-1a2b3c4d5e6f",
  "status": "running",
  "message": "Report generation started"
}

jobIds (a { format: jobId } map) may also be present when a request produces more than one job. Use jobId to poll and download.

2. Poll job status

`GET /v2/account/reports/{type}/{jobId}`

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/reports/transactions/b3f1c9e2-8a4d-4e77-9c21-1a2b3c4d5e6f" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Poll until status is success (or failed). Once succeeded, fileUrls lists every produced file, grouped by extension and split into parts.

{
  "jobId": "b3f1c9e2-8a4d-4e77-9c21-1a2b3c4d5e6f",
  "status": "success",
  "period": "2025-06-01 to 2025-06-30",
  "generatedAt": "2025-07-01T03:12:44Z",
  "fileUrls": [
    {
      "extension": "csv",
      "parts": [
        {
          "partNumber": 1,
          "url": "https://s3.eu-west-1.amazonaws.com/...&X-Amz-Signature=...",
          "sizeBytes": 148213,
          "recordCount": 2944
        }
      ]
    }
  ],
  "s3Prefix": "production/.../2025/07/01/..."
}

When a job fails, status is failed and errorMessage explains why.

The presigned url values in fileUrls are short-lived. If they expire, either poll again for fresh URLs or use the download endpoint below.

3. Download a file

`GET /v2/account/reports/{type}/{jobId}/download`

Redirects (302) to a freshly presigned S3 URL. Follow the redirect to fetch the file.

Query param	Required	Description
`format`	Conditional	File extension to download. Required when the job produced more than one format.
`part`	No	Part number for multipart reports. Default `1`.

curl -L "https://api.sandbox.avenia.io:10952/v2/account/reports/transactions/b3f1c9e2-8a4d-4e77-9c21-1a2b3c4d5e6f/download?format=csv&part=1" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -o report.csv

4. List past reports

`GET /v2/account/reports/{type}`

Query param	Description
`status`	Filter by job status.
`limit`	Maximum number of jobs to return.

{
  "reports": [
    {
      "jobId": "b3f1c9e2-8a4d-4e77-9c21-1a2b3c4d5e6f",
      "reportType": "transactions",
      "outputFormat": "csv",
      "periodStart": "2025-06-01",
      "periodEnd": "2025-06-30",
      "status": "success",
      "fileUrls": [ { "extension": "csv", "parts": [ /* ... */ ] } ],
      "createdAt": "2025-07-01T03:11:02Z",
      "updatedAt": "2025-07-01T03:12:44Z"
    }
  ]
}

Period rules

The requested period must describe fully-closed UTC days so the dataset is complete and reconcilable:

periodStart cannot be in the future.
periodEnd must be before today's midnight UTC — you cannot report on the current (still-open) day.
The period cannot exceed 12 months.

Quota

Each account may start up to 20 report requests per day. Requests beyond the quota are rejected.

Lifecycle​

1. Generate a report​

POST /v2/account/reports/statements​

Statement description filter​

POST /v2/account/reports/transactions​

cUrl Example​

Response — 202 Accepted​

2. Poll job status​

GET /v2/account/reports/{type}/{jobId}​

3. Download a file​

GET /v2/account/reports/{type}/{jobId}/download​

4. List past reports​

GET /v2/account/reports/{type}​

Period rules​

Quota​