curl --request POST \
--url https://api.citadel.example/api/v1/reports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"network": "mainnet",
"type": "wallet_statement",
"format": "csv",
"wallet": "user-4211",
"window_days": 7
}
'{
"id": "0199a3e1-2b3c-7d4e-8f50-61728394a5b6",
"type": "wallet_statement",
"format": "csv",
"network": "mainnet",
"status": "queued",
"wallet": {
"id": "0199a3c4-7f1e-7b11-9c2e-3f4a5b6c7d8e",
"reference": "user-4211",
"address": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF"
},
"window_days": 7,
"failure_reason": null,
"created_at": "2026-10-18T09:00:00Z",
"completed_at": null,
"file": null
}Ask for a report
Asks for a report as a file, PDF or CSV, on one network. Citadel builds it in the
background: the answer is 202 with the report queued. Follow it with
GET /reports/{id} until it is ready, then fetch the file with GET /reports/{id}/file.
A report shows the books as they stand when it is built.
type | What it holds | wallet | window_days |
|---|---|---|---|
wallet_statement | One wallet: its compliance screening, its balances, and every confirmed movement of the window, network fees included, with a running balance per asset | required | optional, 1 to 30, default 30 |
custody | The organization: its assets and their estimated USD value, its top counterparties | none | none |
overview | The organization: holdings, value per chain, inflow, outflow and fees of the last 30 days, top counterparties, concentration | none | none |
Only confirmed transfers are in a report. USD figures are reference estimates, marked as such in the file; no rate is locked with them.
A statement has a row for every change to the wallet’s balance in the window: each
transfer, and a row of its own for what a transaction moved beyond its transfers. The CSV
names each row in its kind column:
kind | The row |
|---|---|
transfer | A confirmed transfer to or from the wallet |
fee | The network fee of a transaction the wallet paid for, in the chain’s coin: one it sent, or one it sponsored. Only the payer’s statement has it, and all of it: a sponsored transaction’s fee is on the sponsor’s statement, none of it on the statement of the wallet it ran for |
stake | Coin the wallet staked (negative) or unstaked (positive) |
adjustment | Any other change the books recorded for the transaction, such as part of a transfer coming back, gas a sponsor advanced and got back, or what receiving cost a TON wallet in a transaction another wallet paid for |
The balance before the first row is what the wallet held when the window opened; the balance after the last row is what it holds now. Citadel books a transaction as one change to the balance: when a transaction has several rows, the running balance counts what came in before what went out, so every row of it reads at least the lower of the balance before the transaction and the balance after it, and never below zero. The balance after the transaction is the one on its last row.
A statement names its wallet like GET /wallets/{reference}: your reference on the
network the request names, or the wallet’s id. A wallet without an address yet (creating
or failed) and a token sub-account Citadel keeps under a wallet are refused with 422;
ask for the statement of the wallet that owns it. A retired wallet has a statement.
A refused request leaves no report behind. Sending the same request again asks for another report.
network is required. Needs the read scope: a report moves nothing and holds only what
the reads return. A key limited to vaults is refused with 403 vault_limited: the
organization-wide reports cover every vault, and a statement names the other wallets of the
organization it dealt with.
curl --request POST \
--url https://api.citadel.example/api/v1/reports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"network": "mainnet",
"type": "wallet_statement",
"format": "csv",
"wallet": "user-4211",
"window_days": 7
}
'{
"id": "0199a3e1-2b3c-7d4e-8f50-61728394a5b6",
"type": "wallet_statement",
"format": "csv",
"network": "mainnet",
"status": "queued",
"wallet": {
"id": "0199a3c4-7f1e-7b11-9c2e-3f4a5b6c7d8e",
"reference": "user-4211",
"address": "TC6A9sQD2tCSaR1wcBXZtrvGkFyoLgRHHF"
},
"window_days": 7,
"failure_reason": null,
"created_at": "2026-10-18T09:00:00Z",
"completed_at": null,
"file": null
}Authorizations
An API key minted in the console (ctd_…). Authenticates; never authorizes funds. A key
carries scopes (read, wallets.write, transactions.write, events.write,
webhooks.write, policy.write) and may be limited to vaults, to IP addresses, and in
lifetime — see Authentication.
Body
The network the data lives on. Required wherever it appears in a request — there is no
default network. One your installation does not serve: 422 network_not_served.
mainnet, testnet wallet_statement, custody, overview pdf, csv wallet_statement only, and required there: your reference for the wallet on network, or its id.
wallet_statement only: how many days the statement covers, up to when it is built. Absent or null — 30.
1 <= x <= 30Response
Queued. The report, as GET /reports/{id} reads it.
wallet_statement, custody, overview pdf, csv The network the data lives on. Required wherever it appears in a request — there is no
default network. One your installation does not serve: 422 network_not_served.
mainnet, testnet queued, running, ready, failed The statement's wallet; null for an organization-wide report.
Show child attributes
Show child attributes
The days a statement covers, up to when it was built; null for an organization-wide report.
Set when status is failed. Human-readable; not stable.
When it became ready or failed.
The file GET /reports/{id}/file streams; null until ready.
Show child attributes
Show child attributes