Customers
Link your customer identity and inspect recorded activity.
SandboxThis is the simulated Earn API. Position creation and withdrawal change sandbox records; they do not sign a wallet transaction.
Authentication · Errors · Amounts and units
Create an end-user
POST /users
Maps one of your customers to a Thesauros user via external_id (unique) and links their wallets.
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| Idempotency-Key | header | string | No | Client-generated key. Retries with the same key replay the original response. |
Request body
Schema: CreateUserRequest
Response · 201
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
User | Yes | |
meta |
object |
No |
For failed requests, inspect error.code, error.message and the request ID. Error handling.
List end-users
GET /users
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| status | query | "active", "disabled" | No | Filter by status |
| wallet | query | string | No | Filter by linked wallet |
| limit | query | integer | No | Page size (1-500, default 100) |
| cursor | query | string | No | Opaque cursor returned as meta.next_cursor |
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
"list" |
Yes | |
data |
User[] | Yes | |
meta |
ListMeta | Yes |
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Get an end-user
GET /users/{id}
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes | User id |
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
User | Yes | |
meta |
object |
No |
For failed requests, inspect error.code, error.message and the request ID. Error handling.
Update an end-user
PATCH /users/{id}
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes | User id |
Request body
Schema: UpdateUserRequest
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
string |
Yes | |
data |
User | Yes | |
meta |
object |
No |
For failed requests, inspect error.code, error.message and the request ID. Error handling.
A user's positions
GET /users/{id}/positions
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes | User id |
| limit | query | integer | No | Page size (1-500, default 100) |
| cursor | query | string | No | Opaque cursor returned as meta.next_cursor |
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
"list" |
Yes | |
data |
Position[] | Yes | |
meta |
ListMeta | Yes |
For failed requests, inspect error.code, error.message and the request ID. Error handling.
A user's reconciliation ledger
GET /users/{id}/ledger
Parameters
| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes | User id |
| asset | query | "USDC", "USDT" | No | Filter by asset |
| type | query | "deposit", "withdraw", "close", "accrual" | No | Filter by entry type |
| limit | query | integer | No | Page size (1-500, default 100) |
| cursor | query | string | No | Opaque cursor returned as meta.next_cursor |
Response · 200
| Field | Type | Required | Description |
|---|---|---|---|
object |
"list" |
Yes | |
data |
LedgerEntry[] | Yes | |
meta |
ListMeta | Yes |
For failed requests, inspect error.code, error.message and the request ID. Error handling.