Read Balances and Positions

Each product has two read endpoints for its account. Both take the user’s wallet address as owner, so you never need to store the account address, and neither needs a signature.

balances lists every token the account holds or has held, with raw and formatted amounts, USD value and transfer history. Use it for balance screens and activity feeds, and to see how much is ready to withdraw.
positions lists what the account has put to work (vault deposits, loans, tokenized assets), valued in USD with PnL. Use it for portfolio screens.

Product	Balances	Positions
Earn	`GET /v2/earn/balances`	`GET /v2/earn/positions`
Credit	`GET /v2/credit/balances`	`GET /v2/credit/positions`
Tokenized Assets	`GET /v2/tokenized_assets/balances`	`GET /v2/tokenized_assets/positions`

Two more views build on these: GET /v2/earn/positions_all returns Earn positions on Ethereum, Base, Arbitrum and HyperEVM in one call, and GET /v2/credit/looped_positions groups leveraged loops into whole positions. Perpetual Trading has its own positions endpoint for the user’s Hyperliquid account. It returns the open positions plus account_value and withdrawable, the USDC the user can take out, so it doubles as the balance read.

Balances

import httpx

response = httpx.get(
    "https://api.compasslabs.ai/v2/earn/balances",
    params={"chain": "base", "owner": "0xYourWalletAddress"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
balances = response.json()

usdc = balances["balances"].get("USDC", {}).get("balance_formatted", "0")  # e.g. "25.318402"

const params = new URLSearchParams({ chain: "base", owner: "0xYourWalletAddress" });
const response = await fetch(
  `https://api.compasslabs.ai/v2/earn/balances?${params}`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const balances = await response.json();

const usdc = balances.balances.USDC?.balance_formatted ?? "0"; // e.g. "25.318402"

The response, shortened to one token and one transfer:

{
  "earn_account_address": "0xYourEarnAccountAddress",
  "balances": {
    "USDC": {
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "token_symbol": "USDC",
      "token_decimals": 6,
      "balance": "25318402",
      "balance_formatted": "25.318402",
      "usd_value": "25.32",
      "transfers": [
        {
          "from_address": "0xYourWalletAddress",
          "to_address": "0xYourEarnAccountAddress",
          "amount": "100000000",
          "amount_formatted": "100",
          "block_number": 43830869,
          "block_timestamp": "2026-09-01T15:04:45Z",
          "transaction_hash": "0x9499...417a",
          "direction": "in"
        }
      ]
    }
  },
  "total_usd_value": "25.32"
}

Field	Description
`balances`	One entry per token, keyed by symbol.
`balance` / `balance_formatted`	The raw on-chain amount, and the same amount in token units.
`usd_value`	The balance in USD, or `null` if there’s no price for the token.
`transfers`	Every transfer in or out of the account for this token. `direction` is `in` or `out`.
`total_usd_value`	The sum of all priced balances.

Positions

response = httpx.get(
    "https://api.compasslabs.ai/v2/earn/positions",
    params={"chain": "base", "owner": "0xYourWalletAddress"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
positions = response.json()

for vault in positions["vaults"]:
    pnl = vault["pnl"] or {}  # null when the position can't be priced
    print(vault["vault_name"], vault["usd_value"], pnl.get("total_pnl"))

const params = new URLSearchParams({ chain: "base", owner: "0xYourWalletAddress" });
const response = await fetch(
  `https://api.compasslabs.ai/v2/earn/positions?${params}`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const positions = await response.json();

for (const vault of positions.vaults) {
  console.log(vault.vault_name, vault.usd_value, vault.pnl?.total_pnl);
}

The response, shortened to one vault position:

{
  "vaults": [
    {
      "type": "VAULT",
      "vault_address": "0xVaultAddress",
      "vault_name": "Example USDC Vault",
      "underlying_symbol": "USDC",
      "underlying_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "balance": "75.41821",
      "usd_value": "75.42",
      "pnl": {
        "total_deposited": "75",
        "current_value": "75.41821",
        "unrealized_pnl": "0.41821",
        "realized_pnl": "0",
        "total_pnl": "0.41821",
        "total_pnl_percent": "0.56"
      },
      "apy_7d": "5.12",
      "apy_30d": "4.87",
      "apy_90d": "4.95"
    }
  ],
  "aave": [],
  "pendle_pt": [],
  "total_usd_value": "75.42"
}

Each Earn position also lists its deposits and withdrawals (Credit and Tokenized Assets positions have events), so you can show a full history without indexing anything yourself.

What each product returns

Product	`positions` returns
Earn	`vaults`, `aave` and `pendle_pt` lists. Each position has its `balance` in the underlying token, `usd_value`, APY, deposit and withdrawal history, and `pnl`. Plus `total_usd_value`.
Credit	`collateral_positions` and `debt_positions` with interest earned and paid, an `account_summary` with the health factor and LTV, and `borrowable_tokens` with how much more the account can borrow. Euler positions get one summary per sub-account in `euler_account_summaries`. `total_usd_value` is collateral minus debt.
Tokenized Assets	`positions` with each asset’s balance, current price, `balance_usd` and `pnl`, plus `total_usd` and an account-level `pnl`.
Perpetual Trading	`positions` with size, side, entry and mark price, liquidation price, leverage, unrealized PnL and accrued funding, plus `account_value` and `withdrawable`.

PnL

Earn and Tokenized Assets positions carry a pnl object:

Field	Meaning
`total_deposited`	Everything put into the position, over all time.
`current_value`	What the position is worth now.
`unrealized_pnl`	`current_value` minus the cost of what’s still held.
`realized_pnl`	Profit or loss already taken out through withdrawals or sales.
`total_pnl`	`unrealized_pnl + realized_pnl`.
`total_pnl_percent`	`total_pnl / total_deposited × 100`.

Earn reports PnL in the position’s own asset: the underlying token for vaults and Aave, and SY units for Pendle PT. Tokenized Assets reports it in USD. Credit reports interest_earned on collateral and interest_paid on debt instead. See How Yield Accrues for how these numbers are calculated, with a worked example.

Good to know

Amounts are strings, so they keep full precision. Parse them with a decimal library, not floats.
USD values can be null when a token has no price. Totals only add up the priced items.
Symbols aren’t unique on-chain. If two tokens share a symbol, their keys become SYMBOL (0xAddress). Match on token_address when it matters.
Tokenized Assets balances is the full ledger. It includes tokens the account no longer holds and its USDC funding, while positions only lists what’s still held.
Pick the chain. Earn and Credit need chain. Tokenized Assets defaults to ethereum, so pass base or bsc for holdings there.

How Yield Accrues

How each position earns, how PnL is calculated, and what the APY numbers mean.

Get Started

Products

Data

Account Lifecycle

Platform Concepts

Developer Tools

Resources

Balances

Positions

What each product returns

PnL

Good to know

Next

How Yield Accrues

​Balances

​Positions

​What each product returns

​PnL

​Good to know

​Next

How Yield Accrues

Balances

Positions

What each product returns

PnL

Good to know

Next