Connect your customers

Attribution connects a user's records to your partner account. It makes customer activity, account reporting and partner economics accessible in the same integration.

Create an attributed user

Call POST /users with your partner-scoped key. The backend binds the new user to the partner associated with that credential.

curl --fail-with-body -X POST "$THESAUROS_API_BASE/users" \
  -H "Authorization: Bearer $THESAUROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"walletco-customer-42","label":"Example customer","wallets":["0x0000000000000000000000000000000000000001"]}'

external_id is your customer identifier. Save the returned data.id in your backend and use it for subsequent position and ledger lookups.

Choose a stable identifier

The current backend checks external_id across its user store. Namespace the identifier for your product, such as walletco-customer-42, and keep it stable across retries. Duplicate creation returns a validation error; it is not an upsert operation.

Before repeating a creation request after an uncertain network result, check the attributed users returned by GET /partner/users for your external identifier.

Wallets and metadata

Wallet inputs must be hexadecimal EVM addresses. The record can also include a label, email and metadata. Send the fields your product needs; the user record is a reporting identity and does not establish ownership of a wallet or permission to transact from it.

Read the linked activity

• GET /partner/users lists your attributed users.
• GET /partner/user/{id}/positions returns positions for a user attributed to your partner.
• GET /users/{id}/ledger returns that user's recorded events.

Requests for a user outside the calling partner's attribution fail. Preserve that boundary when serving data to your own frontend.