Leveraged Looping

A leveraged loop supplies collateral, borrows against it, swaps the borrowed token back into collateral and supplies that too, repeating until the position reaches the leverage the user asked for. Done by hand, that’s a dozen transactions, each with its own liquidation risk. Looping does the whole thing in one transaction: if any step fails, nothing happens. Unwinding runs the same loop in reverse, also in one transaction. Looping works on Aave V3, Morpho Blue and Euler V2, on Ethereum, Base, Arbitrum, HyperEVM and BNB Smart Chain. It uses the same Credit Account and the same market identifiers as Crypto-Backed Loans.

Before you start

An API key. See the Quick Start.
A Credit Account for the user, holding the collateral token. The loop never pulls from the user’s wallet, so the account must already hold initial_collateral_amount. See Create an Account and Fund an Account.

1. Pick a market

Name the market the same way as for a loan: token symbols on Aave, a market_id on Morpho, or collateral_vault and borrow_vault on Euler. See Pick a market for the endpoints that list them. Two things to check before offering a market: loan_to_value can’t exceed the market’s limit (the reserve LTV on Aave, lltv on Morpho, the collateral’s borrow_ltv on Euler), and the market’s available_liquidity must cover the loop’s total borrow.

2. Preview

Call loop with preview: true to see the projected position without building anything. Use it on every change while the user adjusts leverage. This previews a 2x WETH position on Aave, borrowing USDC at 70% LTV against 1 WETH:

import os
from compass_api_sdk import CompassAPI

compass = CompassAPI(api_key_auth=os.environ["COMPASS_API_KEY"])

preview = compass.credit.credit_loop(
    owner="0xYourWalletAddress",
    chain="ethereum",
    protocol="AAVE",
    collateral_token="WETH",
    borrow_token="USDC",
    initial_collateral_amount="1",
    multiplier=2,
    loan_to_value=70,
    max_slippage_percent=0.5,
    preview=True,
).preview

print(f"Leverage: {preview.achieved_multiplier}x")
print(f"Health factor: {preview.projected_health_factor}")
print(f"Entry cost: {preview.estimated_swap_cost} WETH")

import { CompassApiSDK } from "@compass-labs/api-sdk";

const compass = new CompassApiSDK({ apiKeyAuth: process.env.COMPASS_API_KEY });

const { preview } = await compass.credit.creditLoop({
  owner: "0xYourWalletAddress",
  chain: "ethereum",
  protocol: "AAVE",
  collateralToken: "WETH",
  borrowToken: "USDC",
  initialCollateralAmount: "1",
  multiplier: 2,
  loanToValue: 70,
  maxSlippagePercent: 0.5,
  preview: true,
});

console.log(`Leverage: ${preview?.achievedMultiplier}x`);
console.log(`Health factor: ${preview?.projectedHealthFactor}`);
console.log(`Entry cost: ${preview?.estimatedSwapCost} WETH`);

curl -X POST "https://api.compasslabs.ai/v2/credit/loop" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "chain": "ethereum",
    "protocol": "AAVE",
    "collateral_token": "WETH",
    "borrow_token": "USDC",
    "initial_collateral_amount": "1",
    "multiplier": 2,
    "loan_to_value": 70,
    "max_slippage_percent": 0.5,
    "preview": true
  }'

Field	Description
`initial_collateral_amount`	Collateral already in the Credit Account, in token units.
`multiplier`	Target leverage. Total collateral ends up at `multiplier` times the initial amount.
`loan_to_value`	How much to borrow against the collateral on each round, in percent.
`max_slippage_percent`	The most each swap may slip, in percent. Defaults to `0.5`.
`preview`	`true` returns the projection only. `false` builds the transaction.

Preview field	Meaning
`iterations`	How many supply, borrow and swap rounds the transaction contains.
`achieved_multiplier`	The guaranteed leverage. The real figure can only be higher.
`total_borrowed`	Total debt after the loop, in the borrow token.
`projected_health_factor`	The health factor after the loop.
`estimated_swap_cost`	The one-off cost of entering, in collateral units: swap fees and price impact, excluding gas. The position has to earn this back before it’s ahead.
`estimated_max_dust`	The most the swaps can leave over in the Credit Account. This is money kept, not a cost.

3. Build and sign

Send the same request with preview: false. The response has a transaction for the user to sign and send, or eip_712 with gas_sponsorship: true. See Gas Sponsorship.

If the response has quote_expires_at, the swap prices are held only until then, usually a few tens of seconds. Have the user sign and send before it. If they take longer, call the endpoint again for a fresh transaction instead of sending the old one.

4. Track the position

looped = compass.credit.credit_looped_positions(
    chain="ethereum", owner="0xYourWalletAddress"
)

for position in looped.positions:
    if position.status == "OPEN":
        current = position.current
        print(current.leverage, current.health_factor, current.net_apy)

const looped = await compass.credit.creditLoopedPositions({
  chain: "ethereum",
  owner: "0xYourWalletAddress",
});

for (const position of looped.positions ?? []) {
  if (position.status === "OPEN") {
    const current = position.current;
    console.log(current?.leverage, current?.healthFactor, current?.netApy);
  }
}

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

Every leveraged position in the Credit Account comes back, with status (OPEN or CLOSED), the live current state and a full history. The fields to show:

current.leverage: current leverage, from the collateral and debt values.
current.health_factor: distance to liquidation. Above 1 is safe. health_factor_scope is market on Morpho and Euler, where each position stands alone, and account on Aave, where all Aave positions in the account share one health factor.
current.net_apy: what the position earns on the user’s equity at today’s rates: leverage × collateral_apy - (leverage - 1) × borrow_apy. Negative means the borrow cost exceeds the collateral yield.
current.net_usd_value: what the position is worth now, collateral minus debt, in USD.
pnl.total_pnl_usd and pnl.total_pnl_quote: what the position has made or lost since it opened, in USD and in the borrowed token. Both count the entry and exit costs, the carry and the price moves. pnl.total_pnl_percent is the same figure as a return on what the user put in. A closed position keeps its final PnL, and each history entry shows the equity it put in or took out (equity_flow_quote).

5. Unwind

unloop withdraws collateral, swaps it to the borrow token and repays, in one transaction. Leave out target_multiplier to close the position completely, or set it to reduce leverage to that level:

unloop = compass.credit.credit_unloop(
    owner="0xYourWalletAddress",
    chain="ethereum",
    protocol="AAVE",
    collateral_token="WETH",
    borrow_token="USDC",
    allow_partial=True,
)

# unloop.transaction: unsigned tx for the owner to sign and send
# unloop.preview.fully_unwound: False means call unloop again
# once this one confirms

const unloop = await compass.credit.creditUnloop({
  owner: "0xYourWalletAddress",
  chain: "ethereum",
  protocol: "AAVE",
  collateralToken: "WETH",
  borrowToken: "USDC",
  allowPartial: true,
});

// unloop.transaction: unsigned tx for the owner to sign and send
// unloop.preview?.fullyUnwound: false means call unloop again
// once this one confirms

curl -X POST "https://api.compasslabs.ai/v2/credit/unloop" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "chain": "ethereum",
    "protocol": "AAVE",
    "collateral_token": "WETH",
    "borrow_token": "USDC",
    "allow_partial": true
  }'

A position close to its liquidation threshold may not have room to be unwound in one transaction. With allow_partial: true, the API returns the most it can do and sets preview.fully_unwound to false; call unloop again to finish. Without it, an unreachable target returns 400. After a full close, the collateral is back in the Credit Account. Send it to the user’s wallet with transfer. See Withdraw Funds.

Good to know

Maximum leverage at a given LTV is about 0.9 ÷ (1 - loan_to_value ÷ 100), so 70% LTV allows about 3x. If the requested multiplier isn’t reachable, the 400 message names the reachable figure.
Yield-bearing collateral. Vault shares and Pendle principal tokens work as collateral where a market accepts them. Their rate comes back in collateral_apy. On principal-token markets, pt_maturity gives the date the fixed rate runs to, and pt_loopable tells you whether new loops are still allowed.
Slippage protection. Every swap has a minimum output enforced on-chain, so a bad fill reverts the whole transaction instead of leaving a half-built position. Anything a swap delivers above the minimum stays in the Credit Account.
PnL is measured in the borrowed token. On a correlated loop such as wstETH against WETH, total_pnl_quote isolates what the loop earned from the borrowed token’s own price, so a positive figure there can still be a USD loss when that token falls; total_pnl_usd shows it. A loop or unwind entry in history with flow_basis: "oracle" means that transaction’s swap cost could not be separated from the amounts moved, so PnL reads slightly high. pnl is absent when part of the position’s history cannot be priced.
Rebalance several positions at once. POST /v2/credit/rebalance takes a list of positions, each with a target size, target leverage or close: true, and moves them all in one transaction. Money freed by closing one position can fund another. It isn’t available on HyperEVM.

Errors

Status	Message	What to do
`400`	`Credit Account not deployed`	Create the account on this chain first.
`400`	`Multiplier not reachable`, `Loop leverage exceeded`	Offer the reachable multiplier from the message, or a higher LTV.
`400`	`Insufficient market liquidity`	Reduce the size or pick another market.
`400`	`Unwind target not reachable`	Retry with `allow_partial: true`, then call again.
`409`	`Firm quotes expired`	Call the endpoint again for a fresh transaction.
`422`	Protocol not on this chain, or an identifier that doesn’t match `protocol`	The message lists the chains that have it. Send the identifier that matches the protocol.

Endpoints

Endpoint	Use it to
`POST /v2/credit/loop`	Preview or build a leveraged position.
`POST /v2/credit/unloop`	Reduce or close a position.
`GET /v2/credit/looped_positions`	Leverage, health factor, net APY, PnL and history.
`POST /v2/credit/rebalance`	Move several positions to new targets at once.
`GET /v2/credit/positions`	Raw collateral and debt, plus remaining borrow capacity.

Crypto-Backed Loans

Plain borrowing, repayment and market discovery.

Fund an Account

Get the collateral into the Credit Account.

Gas Sponsorship

Pay gas for your users so they never need ETH.

Get Started

Products

Data

Account Lifecycle

Platform Concepts

Developer Tools

Resources

Before you start

1. Pick a market

2. Preview

3. Build and sign

4. Track the position

5. Unwind

Good to know

Errors

Endpoints

Next

Crypto-Backed Loans

Fund an Account

Gas Sponsorship

​Before you start

​1. Pick a market

​2. Preview

​3. Build and sign

​4. Track the position

​5. Unwind

​Good to know

​Errors

​Endpoints

​Next

Crypto-Backed Loans

Fund an Account

Gas Sponsorship

Before you start

1. Pick a market

2. Preview

3. Build and sign

4. Track the position

5. Unwind

Good to know

Errors

Endpoints

Next