> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compasslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto-Backed Loans Positions

> Track collateral, debt, and health factor for Credit Accounts.

## Overview

The `/v2/credit/positions` endpoint returns the current state of a Credit Account, including:

* **Collateral positions** — tokens supplied as collateral to Aave
* **Debt positions** — tokens borrowed, with interest accrued and borrow/repay history
* **Account summary** — health factor, total collateral/debt in USD, LTV, E-Mode status, and available borrow capacity
* **Borrowable tokens** — all tokens available for borrowing with maximum borrowable amounts and current APYs

This is the read counterpart to the borrow and repay transact endpoints.

## Request

```
GET /v2/credit/positions?chain={chain}&owner={owner}
```

| Parameter | Type   | Description                                                       |
| --------- | ------ | ----------------------------------------------------------------- |
| `chain`   | string | The chain (ethereum, base, or arbitrum)                           |
| `owner`   | string | The owner's wallet address (EOA that controls the Credit Account) |

## Response

### Account Summary

The `account_summary` object comes from Aave's `getUserAccountData()` and reflects the real-time on-chain state.

| Field                   | Description                                                                      |
| ----------------------- | -------------------------------------------------------------------------------- |
| `health_factor`         | Above 1 is safe. Below 1 risks liquidation. Very large values mean minimal risk. |
| `total_collateral_usd`  | Total collateral value in USD                                                    |
| `total_debt_usd`        | Total outstanding debt in USD                                                    |
| `available_borrows_usd` | How much more the user can borrow in USD                                         |
| `ltv`                   | Current loan-to-value ratio                                                      |
| `emode_category_id`     | E-Mode category ID (0 = disabled)                                                |
| `emode_label`           | Human-readable E-Mode name (null when disabled)                                  |

### Collateral Positions

The `collateral_positions` array contains one entry per reserve where the account has supplied collateral.

| Field             | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `token`           | The collateral token address (checksummed)                              |
| `symbol`          | Token symbol (e.g., USDC, WETH)                                         |
| `amount_supplied` | Current on-chain aToken balance                                         |
| `usd_value`       | Collateral value in USD                                                 |
| `supply_apy`      | Current supply APY in percentage (e.g., 4.5 means 4.5%)                 |
| `total_deposited` | Total collateral deposited over all time                                |
| `total_withdrawn` | Total collateral withdrawn over all time                                |
| `interest_earned` | Interest earned: `on_chain_balance + total_withdrawn - total_deposited` |
| `max_ltv`         | Maximum loan-to-value ratio in percentage (e.g., 80 means 80%)          |
| `events`          | Historical events for this collateral reserve                           |

### Debt Positions

The `debt_positions` array contains one entry per reserve where the account has outstanding debt.

| Field             | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `token`           | The borrow token address (checksummed)                            |
| `symbol`          | Token symbol (e.g., WETH, USDC)                                   |
| `amount_borrowed` | Current on-chain variable debt balance                            |
| `usd_value`       | Debt value in USD                                                 |
| `borrow_apy`      | Current borrow APY in percentage (e.g., 4.5 means 4.5%)           |
| `total_borrowed`  | Total amount borrowed across all borrow events                    |
| `total_repaid`    | Total amount repaid across all repay events                       |
| `interest_paid`   | Interest paid: `on_chain_balance + total_repaid - total_borrowed` |
| `events`          | Historical events for this debt reserve                           |

### Borrowable Tokens

The `borrowable_tokens` array lists all tokens available for borrowing, with the maximum amount the user can borrow based on their current collateral and available borrow capacity.

| Field                   | Description                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `token`                 | Address of the borrowable token (checksummed)                                          |
| `symbol`                | Token symbol (e.g., WETH, USDC)                                                        |
| `max_borrowable_amount` | Maximum amount that can be borrowed based on available borrow capacity and token price |
| `borrow_apy`            | Current variable borrow APY in percentage (e.g., 4.5 means 4.5%)                       |

### Net Value

The `total_usd_value` field is the net position value: total collateral USD minus total debt USD. It is `null` if token prices are unavailable.

## Example

<CodeGroup>
  ```python Python theme={"system"}
  import httpx

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

  print(f"Health Factor: {positions['account_summary']['health_factor']}")
  print(f"Collateral: ${positions['account_summary']['total_collateral_usd']}")
  print(f"Debt: ${positions['account_summary']['total_debt_usd']}")

  for pos in positions["collateral_positions"]:
      print(f"  Collateral: {pos['symbol']}: {pos['amount_supplied']}")

  for pos in positions["debt_positions"]:
      print(f"  Debt: {pos['symbol']}: {pos['amount_borrowed']} (interest: {pos['interest_paid']})")

  for token in positions["borrowable_tokens"]:
      print(f"  Can borrow: {token['symbol']}: up to {token['max_borrowable_amount']} ({token['borrow_apy']}% APY)")
  ```

  ```typescript TypeScript theme={"system"}
  const response = await fetch(
    "https://api.compasslabs.ai/v2/credit/positions?chain=base&owner=0xYourWalletAddress",
    {
      headers: { "x-api-key": "YOUR_API_KEY" },
    }
  );
  const data = await response.json();

  console.log(`Health Factor: ${data.account_summary.health_factor}`);
  console.log(`Collateral: $${data.account_summary.total_collateral_usd}`);
  console.log(`Debt: $${data.account_summary.total_debt_usd}`);

  for (const pos of data.collateral_positions) {
    console.log(`Collateral: ${pos.symbol} = ${pos.amount_supplied}`);
  }
  for (const pos of data.debt_positions) {
    console.log(`Debt: ${pos.symbol} = ${pos.amount_borrowed}`);
  }
  for (const token of data.borrowable_tokens) {
    console.log(`Can borrow: ${token.symbol} = up to ${token.max_borrowable_amount} (${token.borrow_apy}% APY)`);
  }
  ```
</CodeGroup>

## Health Factor

The health factor indicates how close an account is to liquidation:

* **> 1.5** — Healthy position with comfortable buffer
* **1.0 - 1.5** — Getting risky, consider adding collateral or repaying debt
* **\< 1.0** — Eligible for liquidation

<Warning>
  If the health factor drops below 1, the position can be liquidated by anyone on-chain. Monitor this value and alert users when it approaches dangerous levels.
</Warning>