Balances and Positions - Compass API Docs

Market data tells you what the venues offer. These endpoints tell you what each of your users actually holds, so you can build balance screens, portfolio views and activity feeds. Pass the user’s wallet address as owner; the API works out the account. No signature is needed.

Data	What you get
Balances	Every token the account holds or has held, with raw and formatted amounts, USD value and the full transfer history.
Positions	What the account has put to work, valued in USD: vault, Aave and Pendle PT positions in Earn; collateral and debt with health factor, LTV and remaining borrowing capacity in Credit; tokenized assets at their current price; open perps with entry, mark and liquidation prices.
PnL	Total deposited, current value, realized and unrealized PnL, yield earned and fees paid.
History	Every deposit, withdrawal, borrow, repayment and trade with block number and transaction hash, so you never need to index anything yourself.

Product	Balances	Positions
Earn	`GET /v2/earn/balances`	`GET /v2/earn/positions`, or `positions_all` for every chain at once
Credit	`GET /v2/credit/balances`	`GET /v2/credit/positions`, or `looped_positions` for leveraged loops
Tokenized Assets	`GET /v2/tokenized_assets/balances`	`GET /v2/tokenized_assets/positions`
Perpetual Trading	Included in `positions`: `account_value` and `withdrawable` USDC. Perps run from the user’s own Hyperliquid account, so there’s no product account to read.	`GET /v2/perpetual_trading/positions`

Example

A user’s Earn positions on Base:

curl "https://api.compasslabs.ai/v2/earn/positions?chain=base&owner=0xYourWalletAddress" \
  -H "x-api-key: $COMPASS_API_KEY"

Each position comes back with its balance, USD value, APY and a pnl object. Amounts are strings, so parse them with a decimal library rather than floats.

Next

Read Balances and Positions

The full field reference, with response examples for each product.

How Yield Accrues

How PnL is calculated and what each APY number means.