Skip to main content

​
Why This Matters

Users accumulate positions across multiple DeFi protocols over time. When rates change, they need to move funds - but doing it manually means multiple transactions, multiple signatures, and wasted gas. Most users never bother. The Portfolio Rebalancer lets you build products that shift allocations across Aave, Morpho vaults, and Pendle markets in one atomic transaction. Users set their target allocation, sign once, and the API handles the rest.

​
What It Does

Given a user’s current positions and a set of target allocations, the rebalancer computes the optimal set of withdrawals, swaps, and deposits to reach the target state. All actions are bundled into one transaction using the Bundle endpoint. You call our API, we return a transaction payload. The user signs once, and their portfolio rebalances atomically. Important: Users must first create an Earn Account before rebalancing.

​
How It Works

  1. Fetch current positions - Call the positions endpoint to see where the user’s funds are deployed
  2. Compute the plan - Determine what needs to move: withdrawals from over-allocated venues, swaps between tokens, deposits into under-allocated venues
  3. Bundle the actions - Send the actions to POST /v2/earn/bundle in order
  4. User signs once - The API returns a single transaction (or EIP-712 data for gas sponsorship)
  5. Execution - All actions execute atomically on-chain

​
Action Order

The bundle executes actions in the order you provide. For a rebalance, the typical order is:
  1. Withdraw from venues that are over-allocated
  2. Swap tokens if the target venue uses a different asset
  3. Deposit into venues that are under-allocated

​
Example: Rebalance from Aave to a Morpho Vault

A user has 100 USDC in Aave earning 4.8% APY. They want to move half to a Morpho vault earning 6.2% APY. This requires three bundled actions: withdraw 50 USDC from Aave, then deposit 50 USDC into the vault. 
import { CompassAPI } from "@compass-labs/api-sdk";

const compass = new CompassAPI({ apiKey: "YOUR_API_KEY" });

const owner = "0xYourWalletAddress";
const chain = "ethereum";

// Step 1: Check current positions
const positions = await compass.v2.earn.getPositions({ owner, chain });
console.log("Current positions:", positions);

// Step 2: Bundle withdraw + deposit to rebalance
const bundle = await compass.v2.earn.bundle({
  owner,
  chain,
  gasSponsorship: true,
  actions: [
    // Withdraw 50 USDC from Aave
    {
      actionType: "V2_MANAGE",
      action: "WITHDRAW",
      amount: 50,
      venue: { type: "AAVE", token: "USDC" },
    },
    // Deposit 50 USDC into Morpho vault
    {
      actionType: "V2_MANAGE",
      action: "DEPOSIT",
      amount: 50,
      venue: {
        type: "VAULT",
        vaultAddress: "0xBEEF01735c132Ada46AA9aA9B6290ac27d14070e",
      },
    },
  ],
});

// Step 3: Sign the EIP-712 typed data with user's wallet
const signature = await wallet.signTypedData(bundle.eip712);

// Step 4: Submit the signed transaction for execution
const result = await compass.v2.gasSponsoredTransaction.prepare({
  owner,
  chain,
  eip712: bundle.eip712,
  signature,
});
console.log("Rebalance tx hash:", result.txHash);

​
Example: Cross-Token Rebalance with Swap

A user has 200 USDC in an Aave market but wants to move 100 into a WETH vault. This requires a withdraw, swap, and deposit - all in one bundle. 
const bundle = await compass.v2.earn.bundle({
  owner,
  chain: "ethereum",
  gasSponsorship: true,
  actions: [
    // 1. Withdraw 100 USDC from Aave
    {
      actionType: "V2_MANAGE",
      action: "WITHDRAW",
      amount: 100,
      venue: { type: "AAVE", token: "USDC" },
    },
    // 2. Swap 100 USDC to WETH
    {
      actionType: "V2_SWAP",
      tokenIn: "USDC",
      tokenOut: "WETH",
      amountIn: 100,
      slippage: 0.5,
    },
    // 3. Deposit WETH into a vault
    {
      actionType: "V2_MANAGE",
      action: "DEPOSIT",
      amount: 0.03, // ~100 USDC worth of WETH
      venue: {
        type: "VAULT",
        vaultAddress: "0xYourWETHVaultAddress",
      },
    },
  ],
});

​
Portfolio Manager Widget

If you want a ready-made UI for rebalancing, use the Portfolio Manager widget. It handles position display, target allocation editing, preview, and execution out of the box.

Try the Portfolio Manager

Try the live widget in the Widget Builder Studio.

Widget Docs

See installation and customization options.
import { RebalancingWidget } from "@compass-labs/widgets";

<RebalancingWidget
  title="Portfolio Manager"
  chain="ethereum"
  showChainSwitcher={true}
  showWalletStatus={true}
  onRebalance={(plan, txHash) => console.log("Rebalanced:", txHash)}
  onError={(err) => console.error("Error:", err)}
/>
PropTypeDefaultDescription
titlestring’Portfolio Manager’Title shown in the header
chainstringundefinedLock to a specific chain. Hides chain selector when set.
showChainSwitcherbooleantrueShow the chain selector dropdown
showWalletStatusbooleantrueShow the wallet connection status
showTopUpbooleantrueShow the Top Up button to transfer from wallet
defaultSlippagenumber0.5Default slippage tolerance for swaps (%)
minRebalanceThresholdUsdnumber0.01Minimum USD value to include in rebalance
venuesobjectundefinedFilter which venues are shown (aave, vaults, pendle)
heightstring’600px’Widget height
onRebalancefunctionundefinedCallback after successful rebalance with plan and tx hash
onErrorfunctionundefinedCallback on error

​
Supported Venues

ProtocolVenue TypeDescription
Aave V3AAVELending markets with variable supply rates
Morpho / ERC-4626VAULTCurated vaults with optimized yield
PendlePENDLE_PTFixed-rate yield via principal tokens

​
Use Cases

Yield Optimization: Monitor rates across protocols and automatically rebalance to maximize returns. When Morpho offers 6.2% but Aave drops to 4.8%, move funds in one transaction. Example: $50,000 in Aave earning 4.8% ($2,400/year). Rebalance to Morpho at 6.2% ($3,100/year). Net gain: $700/year in additional yield. Risk Diversification: Spread user funds across multiple protocols to reduce smart contract risk. Set target allocations like 40% Aave, 40% Morpho, 20% Pendle and rebalance when drift exceeds a threshold. Treasury Management: Let businesses rebalance idle capital across venues based on changing rate environments. Build dashboards that show current vs. target allocation and offer one-click rebalancing.

​
Next Steps

Transaction Bundling

Learn how bundling works under the hood.

Variable Earn

Explore the vaults and Aave markets available for rebalancing.

Gas Sponsorship

Sponsor gas so users rebalance without needing ETH.