Customers
Link your customer identity and inspect recorded activity.
Partner APINamespace external_id by your partner: uniqueness is global. Creating an existing external ID returns an error; creation is not an upsert. See customer attribution.
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.
Create an attributed end-user
POST /users
Access: partner:read.
SDK methods: TypeScript client.users.create(…); Python client.users.create(…).
Request body
Schema: CreateUserInputDto
Request example
curl --fail-with-body -X POST "$THESAUROS_API_BASE/users" \
-H "Authorization: Bearer $THESAUROS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"external_id":"docs-example-customer","label":"Example customer","wallets":["0x0000000000000000000000000000000000000001"]}'
Response · 201
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
UserRecord | Yes |
View example response
{
"object": "user",
"data": {
"id": "usr_1bb75cc43c5b5ab6",
"object": "user",
"external_id": "docs-example-customer",
"label": "Example customer",
"email": null,
"metadata": {},
"wallets": [
"0x0000000000000000000000000000000000000001"
],
"status": "active",
"created_at": "2026-09-07T14:42:45.380Z",
"updated_at": "2026-09-07T14:42:45.380Z"
}
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Per-user event ledger (deposits, withdrawals, rebalances, yield accruals)
GET /users/{id}/ledger
Access: partner:read.
SDK methods: TypeScript client.users.ledger(…); Python client.users.ledger(…).
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes | |
| limit | query | string | No | |
Request example
curl --fail-with-body -X GET "$THESAUROS_API_BASE/users/usr_seed_nova/ledger" \
-H "Authorization: Bearer $THESAUROS_API_KEY"
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
UserLedgerEvent[] | Yes |
View example response
{
"object": "list",
"data": [
{
"id": "evt_seed_gamma_dep",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_gamma",
"asset": "USDC",
"type": "deposit",
"amount": 50000,
"apy": 0.068,
"vault_id": "vault_morpho_base_usdc",
"note": "Initial deposit routed to vault",
"at": "2026-07-15T12:00:00.000Z"
},
{
"id": "evt_seed_alpha_dep",
"object": "ledger_entry",
"user_id": "usr_seed_nova",
"position_id": "pos_seed_alpha",
"asset": "USDC",
"type": "deposit",
"amount": 25000,
"apy": 0.052,
"vault_id": "vault_aave_base_usdc",
"note": "Initial deposit routed to vault",
"at": "2026-06-20T12:00:00.000Z"
}
]
}
For failed requests, inspect error.code, error.message and the request ID. Error handling.