Statements
Monthly, immutable statements of your sub-account ledger.
Concepts: The object model, Positions
A statement is a fold of your append-only sub-account ledger for one calendar month. It reports the share balance each of your sub-accounts opened and closed the month with, and every settled entry in between. Once issued, a statement is never edited — a correction is a new statement whose supersedesId points at the old one.
No period-end asset valuation is included in a statement; it records shares and the per-entry asset amount only, exactly as posted to the ledger. Share figures are exact integers, given as strings — never format, float or parse one as a number.
When a statement becomes available
A statement covers a closed calendar month only — one that has fully elapsed. Your first request for a closed month issues it; every later request for that same month, from anyone reading with your credentials, returns the identical statement. Requesting the current, still-open month is refused with 400 STATEMENT_PERIOD_OPEN.
GET /statements
GET /statements · scope statement:read
| Query | Type | Notes |
|---|---|---|
month | string, YYYY-MM | A closed calendar month. Issues the statement on first read; returns the same one on every later read of that month. Omit it to list your already-issued statements instead. |
cursor | string | The nextCursor from the previous page. Omit it for the first page. Treat it as opaque. Ignored when month is set. |
limit | integer, 1-100 | Rows per page when listing. Defaults to 25. Ignored when month is set. |
curl -G https://api.threecommabank.com/api/partner/v1/statements \
-H "Authorization: Bearer $TCB_API_KEY" \
--data-urlencode "month=2026-08"{
"success": true,
"data": {
"items": [
{
"id": "3b8f2a01-7c4d-4e9a-9b12-0f6a3d8c5e21",
"periodStart": "2026-08-01",
"periodEnd": "2026-08-31",
"issuedAt": "2026-09-01T00:04:11.000Z",
"payloadHash": "0f4c8b1d92a7e35604fd1c8a37b2905e6417da8c25f0b93e71c6482da05f3b9e",
"supersedesId": null,
"supersededById": null,
"formats": ["JSON", "CSV"]
}
],
"nextCursor": null
},
"timestamp": "2026-09-08T10:15:28.402Z"
}curl -G https://api.threecommabank.com/api/partner/v1/statements \
-H "Authorization: Bearer $TCB_API_KEY" \
--data-urlencode "limit=25"GET /statements/{id}
GET /statements/{id} · scope statement:read
Returns the full statement. ?format=csv (or an Accept: text/csv request) returns the same statement as text/csv bytes instead of JSON — the same resource, a different representation.
| Query | Type | Notes |
|---|---|---|
format | json | csv | Defaults to json. |
curl https://api.threecommabank.com/api/partner/v1/statements/3b8f2a01-7c4d-4e9a-9b12-0f6a3d8c5e21 \
-H "Authorization: Bearer $TCB_API_KEY"{
"success": true,
"data": {
"id": "3b8f2a01-7c4d-4e9a-9b12-0f6a3d8c5e21",
"period": { "from": "2026-08-01", "to": "2026-08-31" },
"issuedAt": "2026-09-01T00:04:11.000Z",
"payloadHash": "0f4c8b1d92a7e35604fd1c8a37b2905e6417da8c25f0b93e71c6482da05f3b9e",
"supersedesId": null,
"supersededById": null,
"statement": {
"subAccounts": [
{
"subAccountId": "c4f81e2a-9b60-4d37-a512-8e0f3c6b7d95",
"externalRef": "tcb:default",
"vaultAddress": "0x1f2e...9a7c",
"currencyCode": "USD",
"openingShares": "800000000000000000000000000",
"closingShares": "1300000000000000000000000000",
"entries": [
{
"entryId": "9d0c7b4e-2a1f-4d8c-b6e0-3f7a9c1d5e42",
"entryType": "DEPOSIT",
"shares": "500000000000000000000000000",
"assets": "500.00",
"currencyCode": "USD",
"intentId": "8a3f5c1e-6b90-4d27-9e14-2c8f0a6d3b57",
"occurredAt": "2026-08-12T09:31:04.000Z",
"runningShares": "1300000000000000000000000000"
}
]
}
],
"notes": [
"No period-end asset valuation is included in this statement; the ledger records shares and per-entry asset amounts only.",
"Shares are exact integers; nothing here is a price or a quote."
]
}
},
"timestamp": "2026-09-08T10:15:29.014Z"
}shares, openingShares, closingShares and runningShares are exact integers in the SHARE token's own base units, given as strings. assets is a decimal string of the underlying currency amount the entry moved. Only settled entries — deposits, withdrawals, adjustments — appear; a hold that has not yet settled is never printed on a statement.
Handle the errors
| Status | Code | What to do |
|---|---|---|
| 400 | STATEMENT_PERIOD_OPEN | The requested month has not closed yet. Ask again after it ends. |
| 403 | INSUFFICIENT_SCOPE | The key lacks statement:read. |
| 404 | STATEMENT_NOT_FOUND | No statement with that id in your scope. |
| 409 | STATEMENT_NOT_READY | The requested representation has not finished rendering. Retry shortly. |
The full catalogue is in Errors. The machine-readable specification for these endpoints is openapi.partner.v1.json. Where it and this page disagree, the specification is authoritative.