Holdings & Positions

Use these endpoints to monitor a user's mUSD, wallet token balances, and exchangeBalance.

userId is currently the user's wallet address (trimmed, lowercased).

For API-level interpretation of mUsdBalance, walletBalance, and exchangeBalance, read getting-started/trader-questions.md.

Endpoints

Method	Path	Description
GET	/api/v1/users/{userId}	User info
GET	/api/v1/users/{userId}/balance	Cash and token balances
GET	/api/v1/users/{userId}/positions	Stock positions

Query user info

GET /api/v1/users/{userId}

Response data:

Field	Type	Description
userId	string	User ID (wallet address).
userAddress	string	Wallet address.

Query balances

GET /api/v1/users/{userId}/balance

Parameter	Type	Required	Default	Description
spenderAddress	string	No	0x000...000	Spender for allowance query.

Response data:

Field	Type	Description
chainId	number	Chain ID.
productType	string	Product type.
address	string	User wallet.
mUsdBalance	string	mUSD.
tokenBalances	array	Token list.

tokenBalances item

Field	Type	Description
address	string	Token address.
name	string	Token name.
symbol	string	Token symbol.
stockSymbol	string / null	Stock symbol (stock tokens).
isStock	boolean	Stock token flag.
decimals	number	Decimals.
price	number / null	Price (stock tokens).
walletBalance	string	Wallet balance (human-readable).
walletAllowance	string	Allowance to spender.
exchangeBalance	string	API view of Stock.stockBalance; used by plain sells.
logoUrl	string	Logo URL.

Query positions

GET /api/v1/users/{userId}/positions

Same query parameters as /balance. Returns data as a tokenBalances array.

Use spenderAddress when checking deposit allowance — see cash/deposits.md.