Reconciliation
Connect user balances, ledger movements and daily snapshots.
Partner APIThe report method is administrative. Partner keys can read their scoped balances, ledger and snapshots. See reconciliation before building an accounting workflow.
Authentication · Errors · Amounts and units
Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.
Recorded balances by user and asset
GET /reconciliation/balances
Scope: partner:read only. Active positions of the calling partner, grouped by user and asset.
Access: read, partner:read.
SDK methods: TypeScript client.reconciliation.balances(…); Python client.reconciliation.balances(…).
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| asset | query | "USDC", "USDT0" | No | Filter by asset symbol. |
| user_id | query | string | No | Restrict to one end-user (usr_…). |
| position_id | query | string | No | Restrict to one position (pos_…). |
Request example
bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/reconciliation/balances" \
-H "Authorization: Bearer $THESAUROS_API_KEY"
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
BalanceDto[] | Yes |
View example response
json
{
"object": "list",
"data": [
{
"object": "balance",
"user_id": "usr_seed_nova",
"asset": "USDC",
"principal": 75000,
"current_value": 75785.84,
"accrued_yield": 785.84,
"positions": 2
},
{
"object": "balance",
"user_id": "usr_seed_orbit",
"asset": "USDT0",
"principal": 10000,
"current_value": 10133.5,
"accrued_yield": 133.5,
"positions": 1
}
]
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Movement rows with running balance
GET /reconciliation/ledger
Scope: partner:read only. Deposits, withdrawals, closes and an accrual row per position (settled: false while the position is open). Paginated via limit/cursor.
Access: read, partner:read.
SDK methods: TypeScript client.reconciliation.ledger(…); Python client.reconciliation.ledger(…).
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| asset | query | "USDC", "USDT0" | No | Filter by asset symbol. |
| user_id | query | string | No | Restrict to one end-user (usr_…). |
| position_id | query | string | No | Restrict to one position (pos_…). |
| limit | query | string | No | Page size, 1–200 (default 50). |
| cursor | query | string | No | Opaque cursor from the previous page’s meta.next_cursor. Omit for the first page. |
| type | query | "deposit", "withdraw", "close", "accrual" | No | Filter to one movement type. |
Request example
bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/reconciliation/ledger" \
-H "Authorization: Bearer $THESAUROS_API_KEY"
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
LedgerEntryDto[] | Yes | |
meta |
ListMetaDto | Yes |
View example response
json
{
"object": "list",
"data": [
{
"id": "led_evt_seed_alpha_dep",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_alpha",
"wallet": "0x8a3f1c9e2b7d4065a1c8e9f0b2d4c6a8e1f3b5d7",
"asset": "USDC",
"vault_id": "vault_aave_base_usdc",
"at": "2026-06-20T12:00:00.000Z",
"type": "deposit",
"amount": 25000,
"balance_after": 25000,
"settled": true,
"ref": "evt_seed_alpha_dep"
},
{
"id": "led_evt_seed_beta_dep",
"object": "ledger_entry",
"user_id": "usr_seed_orbit",
"position_id": "pos_seed_beta",
"wallet": "0x1b2c3d4e5f60718293a4b5c6d7e8f90123456789",
"asset": "USDT0",
"vault_id": "vault_plasma_usdt0",
"at": "2026-07-05T12:00:00.000Z",
"type": "deposit",
"amount": 10000,
"balance_after": 10000,
"settled": true,
"ref": "evt_seed_beta_dep"
},
{
"id": "led_evt_seed_gamma_dep",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_gamma",
"wallet": "0x8a3f1c9e2b7d4065a1c8e9f0b2d4c6a8e1f3b5d7",
"asset": "USDC",
"vault_id": "vault_morpho_base_usdc",
"at": "2026-07-15T12:00:00.000Z",
"type": "deposit",
"amount": 50000,
"balance_after": 50000,
"settled": true,
"ref": "evt_seed_gamma_dep"
},
{
"id": "led_pos_seed_alpha_accrual",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_alpha",
"wallet": "0x8a3f1c9e2b7d4065a1c8e9f0b2d4c6a8e1f3b5d7",
"asset": "USDC",
"vault_id": "vault_aave_base_usdc",
"at": "2026-07-26T12:00:00.000Z",
"type": "accrual",
"amount": 281.77,
"balance_after": 25281.77,
"settled": false,
"ref": "pos_seed_alpha"
},
{
"id": "led_pos_seed_beta_accrual",
"object": "ledger_entry",
"user_id": "usr_seed_orbit",
"position_id": "pos_seed_beta",
"wallet": "0x1b2c3d4e5f60718293a4b5c6d7e8f90123456789",
"asset": "USDT0",
"vault_id": "vault_plasma_usdt0",
"at": "2026-07-27T12:00:00.000Z",
"type": "accrual",
"amount": 133.5,
"balance_after": 10133.5,
"settled": false,
"ref": "pos_seed_beta"
},
{
"id": "led_pos_seed_gamma_accrual",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_gamma",
"wallet": "0x8a3f1c9e2b7d4065a1c8e9f0b2d4c6a8e1f3b5d7",
"asset": "USDC",
"vault_id": "vault_morpho_base_usdc",
"at": "2026-07-27T12:00:00.000Z",
"type": "accrual",
"amount": 504.07,
"balance_after": 50504.07,
"settled": false,
"ref": "pos_seed_gamma"
}
],
"meta": {
"total": 6,
"limit": 50,
"has_more": false,
"next_cursor": null
}
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Daily balance snapshots for period accounting
GET /reconciliation/snapshots
Scope: partner:read only. One row per day in [from, to] (default: trailing 30 days).
Access: read, partner:read.
SDK methods: TypeScript client.reconciliation.snapshots(…); Python client.reconciliation.snapshots(…).
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| asset | query | "USDC", "USDT0" | No | Filter by asset symbol. |
| from | query | string | No | Window start, ISO 8601. Default: 29 days before to. |
| to | query | string | No | Window end, ISO 8601. Default: now. |
Request example
bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/reconciliation/snapshots" \
-H "Authorization: Bearer $THESAUROS_API_KEY"
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
BalanceSnapshotDto[] | Yes |
View example response
json
{
"object": "list",
"data": [
{
"object": "balance_snapshot",
"date": "2026-08-09",
"t": 1786233600000,
"principal": 85000,
"value": 85476.36,
"accrued": 476.36,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75404.52,
"accrued": 404.52
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10071.84,
"accrued": 71.84
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-10",
"t": 1786320000000,
"principal": 85000,
"value": 85491.31,
"accrued": 491.31,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75417.39,
"accrued": 417.39
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10073.92,
"accrued": 73.92
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-11",
"t": 1786406400000,
"principal": 85000,
"value": 85506.27,
"accrued": 506.27,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75430.27,
"accrued": 430.27
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10076,
"accrued": 76
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-12",
"t": 1786492800000,
"principal": 85000,
"value": 85521.23,
"accrued": 521.23,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75443.15,
"accrued": 443.15
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10078.08,
"accrued": 78.08
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-13",
"t": 1786579200000,
"principal": 85000,
"value": 85536.19,
"accrued": 536.19,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75456.03,
"accrued": 456.03
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10080.16,
"accrued": 80.16
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-14",
"t": 1786665600000,
"principal": 85000,
"value": 85551.15,
"accrued": 551.15,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75468.9,
"accrued": 468.9
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10082.25,
"accrued": 82.25
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-15",
"t": 1786752000000,
"principal": 85000,
"value": 85566.11,
"accrued": 566.11,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75481.78,
"accrued": 481.78
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10084.33,
"accrued": 84.33
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-16",
"t": 1786838400000,
"principal": 85000,
"value": 85581.06,
"accrued": 581.06,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75494.65,
"accrued": 494.65
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10086.41,
"accrued": 86.41
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-17",
"t": 1786924800000,
"principal": 85000,
"value": 85596.02,
"accrued": 596.02,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75507.53,
"accrued": 507.53
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10088.49,
"accrued": 88.49
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-18",
"t": 1787011200000,
"principal": 85000,
"value": 85610.99,
"accrued": 610.99,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75520.41,
"accrued": 520.41
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10090.58,
"accrued": 90.58
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-19",
"t": 1787097600000,
"principal": 85000,
"value": 85625.95,
"accrued": 625.95,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75533.29,
"accrued": 533.29
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10092.66,
"accrued": 92.66
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-20",
"t": 1787184000000,
"principal": 85000,
"value": 85640.9,
"accrued": 640.9,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75546.16,
"accrued": 546.16
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10094.74,
"accrued": 94.74
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-21",
"t": 1787270400000,
"principal": 85000,
"value": 85655.86,
"accrued": 655.86,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75559.04,
"accrued": 559.04
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10096.82,
"accrued": 96.82
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-22",
"t": 1787356800000,
"principal": 85000,
"value": 85670.82,
"accrued": 670.82,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75571.92,
"accrued": 571.92
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10098.9,
"accrued": 98.9
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-23",
"t": 1787443200000,
"principal": 85000,
"value": 85685.78,
"accrued": 685.78,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75584.79,
"accrued": 584.79
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10100.99,
"accrued": 100.99
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-24",
"t": 1787529600000,
"principal": 85000,
"value": 85700.75,
"accrued": 700.75,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75597.68,
"accrued": 597.68
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10103.07,
"accrued": 103.07
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-25",
"t": 1787616000000,
"principal": 85000,
"value": 85715.7,
"accrued": 715.7,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75610.55,
"accrued": 610.55
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10105.15,
"accrued": 105.15
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-26",
"t": 1787702400000,
"principal": 85000,
"value": 85730.66,
"accrued": 730.66,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75623.43,
"accrued": 623.43
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10107.23,
"accrued": 107.23
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-27",
"t": 1787788800000,
"principal": 85000,
"value": 85745.62,
"accrued": 745.62,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75636.3,
"accrued": 636.3
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10109.32,
"accrued": 109.32
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-28",
"t": 1787875200000,
"principal": 85000,
"value": 85760.58,
"accrued": 760.58,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75649.18,
"accrued": 649.18
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10111.4,
"accrued": 111.4
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-29",
"t": 1787961600000,
"principal": 85000,
"value": 85775.53,
"accrued": 775.53,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75662.05,
"accrued": 662.05
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10113.48,
"accrued": 113.48
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-30",
"t": 1788048000000,
"principal": 85000,
"value": 85790.5,
"accrued": 790.5,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75674.94,
"accrued": 674.94
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10115.56,
"accrued": 115.56
}
]
},
{
"object": "balance_snapshot",
"date": "2026-08-31",
"t": 1788134400000,
"principal": 85000,
"value": 85805.45,
"accrued": 805.45,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75687.81,
"accrued": 687.81
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10117.64,
"accrued": 117.64
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-01",
"t": 1788220800000,
"principal": 85000,
"value": 85820.42,
"accrued": 820.42,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75700.69,
"accrued": 700.69
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10119.73,
"accrued": 119.73
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-02",
"t": 1788307200000,
"principal": 85000,
"value": 85835.37,
"accrued": 835.37,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75713.56,
"accrued": 713.56
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10121.81,
"accrued": 121.81
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-03",
"t": 1788393600000,
"principal": 85000,
"value": 85850.33,
"accrued": 850.33,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75726.44,
"accrued": 726.44
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10123.89,
"accrued": 123.89
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-04",
"t": 1788480000000,
"principal": 85000,
"value": 85865.28,
"accrued": 865.28,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75739.31,
"accrued": 739.31
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10125.97,
"accrued": 125.97
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-05",
"t": 1788566400000,
"principal": 85000,
"value": 85880.25,
"accrued": 880.25,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75752.2,
"accrued": 752.2
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10128.05,
"accrued": 128.05
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-06",
"t": 1788652800000,
"principal": 85000,
"value": 85895.21,
"accrued": 895.21,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75765.07,
"accrued": 765.07
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10130.14,
"accrued": 130.14
}
]
},
{
"object": "balance_snapshot",
"date": "2026-09-07",
"t": 1788739200000,
"principal": 85000,
"value": 85910.17,
"accrued": 910.17,
"positions": 3,
"users": 2,
"by_asset": [
{
"asset": "USDC",
"principal": 75000,
"value": 75777.95,
"accrued": 777.95
},
{
"asset": "USDT0",
"principal": 10000,
"value": 10132.22,
"accrued": 132.22
}
]
}
]
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Recorded accounting vs observed on-chain balances
GET /reconciliation/report
Scope: admin read only (protocol-wide by design). Needs MONITOR_API_URL configured — otherwise returns the same shape with status: "unavailable" and the chain side nulled.
Access: read.
SDK methods: TypeScript client.reconciliation.report(…); Python client.reconciliation.report(…).
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| asset | query | "USDC", "USDT0" | No | Filter by asset symbol. |
Request example
bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/reconciliation/report" \
-H "Authorization: Bearer $THESAUROS_API_KEY"
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
ReconciliationReportDto | Yes |
View example response
json
{
"object": "reconciliation",
"data": {
"object": "reconciliation",
"as_of": "2026-09-07T14:42:46.281Z",
"scope": "protocol",
"status": "unavailable",
"unavailable_reason": "MONITOR_API_URL is not configured",
"recorded_total": 85919.34,
"onchain_total": null,
"discrepancy": null,
"diff_bps": null,
"tolerance_bps": 10,
"positions": 3,
"observed_at": null,
"observed_networks": [],
"breakdown": [
{
"asset": "USDC",
"recorded": 75785.84,
"onchain": null,
"discrepancy": null,
"diff_bps": null,
"observed": false
},
{
"asset": "USDT0",
"recorded": 10133.5,
"onchain": null,
"discrepancy": null,
"diff_bps": null,
"observed": false
}
],
"open_discrepancies": []
}
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.