Show positions and activity

Use the position for the current state and the ledger for the story of how it changed. Keep confirmed wallet transactions connected to those records where your integration requires settlement evidence.

Read a customer's positions

curl --fail-with-body \
  "$THESAUROS_API_BASE/partner/user/$THESAUROS_USER_ID/positions" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"

Each position includes identifiers, asset, vault, principal, rate, status and calculation fields such as current_value and accrued_yield. The API requires the user to be attributed to the calling partner.

An empty list is a valid result for a user without positions. Use it to offer the next product action rather than displaying a system error.

Build the activity view

curl --fail-with-body \
  "$THESAUROS_API_BASE/users/$THESAUROS_USER_ID/ledger?limit=50" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"

The user ledger returns recent events, newest first. It includes event type, amount, timestamp, position and available vault context. This endpoint uses a bounded limit; it does not expose the cursor contract used by the separate reconciliation ledger.

Use each total for its intended purpose

/partner/deposits aggregates the open-position principal selected by its calculation. /partner/withdrawals aggregates withdrawal information from position records. These are summaries, not a universal append-only transaction history. Use the event ledger for individual activity and the agreed settlement source for transaction accounting.

Keep customer states explicit

A pending transaction, an active position and a withdrawal in progress are different states. Preserve the last confirmed value when a refresh fails, indicate that the refresh is unavailable, and allow the user to inspect the relevant activity.

The reporting guide explains how to connect those states to the operational view.