Portfolio Rebalancer

Users end up with positions spread across venues, and rates move. Rebalancing by hand means several transactions and signatures, so most users never do it. The Portfolio Rebalancer lets you move funds between Aave markets, vaults and Pendle markets in one atomic transaction: every step succeeds, or nothing happens. It’s built on the Earn bundle endpoint, so it works wherever Earn works, from the same Earn Account.

Before you start

An API key. See the Quick Start.
An Earn Account with positions to move. See Account Lifecycle.

How it works

Read the current positions with GET /v2/earn/positions.
Work out the moves. Withdraw from venues that are over target, swap if the target venue takes a different token, deposit into venues that are under target.
Send the moves as one bundle. Actions run in the order you list them, and the user signs once.

Example: move 50 USDC from Aave to a vault

import os
from compass_api_sdk import CompassAPI

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

bundle = compass.earn.earn_bundle(
    owner="0xYourWalletAddress",
    chain="base",
    actions=[
        {
            "body": {
                "action_type": "V2_MANAGE",
                "action": "WITHDRAW",
                "amount": "50",
                "venue": {"type": "AAVE", "token": "USDC"},
            }
        },
        {
            "body": {
                "action_type": "V2_MANAGE",
                "action": "DEPOSIT",
                "amount": "50",
                "venue": {"type": "VAULT", "vault_address": "0xVaultAddress"},
            }
        },
    ],
)

# bundle.transaction: one unsigned tx that runs both actions
# bundle.actions_count: 2

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

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

const bundle = await compass.earn.earnBundle({
  owner: "0xYourWalletAddress",
  chain: "base",
  actions: [
    {
      body: {
        actionType: "V2_MANAGE",
        action: "WITHDRAW",
        amount: "50",
        venue: { type: "AAVE", token: "USDC" },
      },
    },
    {
      body: {
        actionType: "V2_MANAGE",
        action: "DEPOSIT",
        amount: "50",
        venue: { type: "VAULT", vaultAddress: "0xVaultAddress" },
      },
    },
  ],
});

// bundle.transaction: one unsigned tx that runs both actions
// bundle.actionsCount: 2

curl -X POST "https://api.compasslabs.ai/v2/earn/bundle" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "chain": "base",
    "actions": [
      {
        "body": {
          "action_type": "V2_MANAGE",
          "action": "WITHDRAW",
          "amount": "50",
          "venue": {"type": "AAVE", "token": "USDC"}
        }
      },
      {
        "body": {
          "action_type": "V2_MANAGE",
          "action": "DEPOSIT",
          "amount": "50",
          "venue": {"type": "VAULT", "vault_address": "0xVaultAddress"}
        }
      }
    ]
  }'

The user signs transaction and sends it. Set gas_sponsorship: true to get eip_712 instead, so your wallet can pay the gas. See Gas Sponsorship.

Example: change token on the way

To move USDC out of Aave and into a WETH vault, add a swap between the withdrawal and the deposit:

bundle = compass.earn.earn_bundle(
    owner="0xYourWalletAddress",
    chain="base",
    actions=[
        {
            "body": {
                "action_type": "V2_MANAGE",
                "action": "WITHDRAW",
                "amount": "100",
                "venue": {"type": "AAVE", "token": "USDC"},
            }
        },
        {
            "body": {
                "action_type": "V2_SWAP",
                "token_in": "USDC",
                "token_out": "WETH",
                "amount_in": "100",
                "slippage": 0.5,
            }
        },
        {
            "body": {
                "action_type": "V2_MANAGE",
                "action": "DEPOSIT",
                "amount": "0.03",
                "venue": {
                    "type": "VAULT",
                    "vault_address": "0xWethVaultAddress",
                },
            }
        },
    ],
)

const swapBundle = await compass.earn.earnBundle({
  owner: "0xYourWalletAddress",
  chain: "base",
  actions: [
    {
      body: {
        actionType: "V2_MANAGE",
        action: "WITHDRAW",
        amount: "100",
        venue: { type: "AAVE", token: "USDC" },
      },
    },
    {
      body: {
        actionType: "V2_SWAP",
        tokenIn: "USDC",
        tokenOut: "WETH",
        amountIn: "100",
        slippage: 0.5,
      },
    },
    {
      body: {
        actionType: "V2_MANAGE",
        action: "DEPOSIT",
        amount: "0.03",
        venue: { type: "VAULT", vaultAddress: "0xWethVaultAddress" },
      },
    },
  ],
});

curl -X POST "https://api.compasslabs.ai/v2/earn/bundle" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "chain": "base",
    "actions": [
      {
        "body": {
          "action_type": "V2_MANAGE",
          "action": "WITHDRAW",
          "amount": "100",
          "venue": {"type": "AAVE", "token": "USDC"}
        }
      },
      {
        "body": {
          "action_type": "V2_SWAP",
          "token_in": "USDC",
          "token_out": "WETH",
          "amount_in": "100",
          "slippage": 0.5
        }
      },
      {
        "body": {
          "action_type": "V2_MANAGE",
          "action": "DEPOSIT",
          "amount": "0.03",
          "venue": {"type": "VAULT", "vault_address": "0xWethVaultAddress"}
        }
      }
    ]
  }'

A deposit needs a fixed amount, and a swap’s output isn’t known until it runs. Get the expected output from GET /v2/earn/swap_quote, then deposit at most that amount reduced by your slippage, so the deposit can never exceed what the swap delivers. Whatever the swap delivers on top stays in the Earn Account.

Actions you can bundle

`action_type`	What it does
`V2_MANAGE`	Deposit into or withdraw from a vault (`VAULT`), an Aave market (`AAVE`) or a Pendle market (`PENDLE_PT`). Takes the same fields as `manage`, including `fee`.
`V2_SWAP`	Swap one token for another inside the Earn Account. `slippage` is in percent.
`V2_TRANSFER_FROM_EOA`	Pull tokens from the user’s wallet into the Earn Account as the first step, so a wallet top-up and the deposits happen in one transaction. Needs a transfer authorization the user signed: get it from `transfer` with `action: "DEPOSIT"` and `gas_sponsorship: true`, then pass the signature with its nonce and deadline.
`V2_TRANSFER_TO_EOA`	Send tokens from the Earn Account to the user’s wallet, for example to pay out at the end.
`V2_TRANSFER_TO_ADDRESS`	Send tokens from the Earn Account to any address, for example a treasury wallet.

Ready-made UI

The Portfolio Manager widget shows a user’s positions, lets them set target allocations, previews the plan and runs the bundle. Try it in the Widget Studio, and see Widgets to embed it in your app.

Good to know

Order matters. Each action can only use what earlier actions left in the account. Withdraw first, then swap, then deposit.
All or nothing. If any action fails, the whole transaction reverts and nothing moves.
Fees. Add a fee to any V2_MANAGE action to charge on the rebalance. See Embedded Fees.

Endpoints

Endpoint	Use it to
`POST /v2/earn/bundle`	Run the moves in one transaction.
`GET /v2/earn/positions`	Read what the user holds today.
`GET /v2/earn/swap_quote`	Size a deposit that follows a swap.
`GET /v2/earn/vaults`, `GET /v2/earn/aave_markets`, `GET /v2/earn/pendle_markets`	Find target venues and their rates.

Earn

The venues you can rebalance between.

Transaction Bundling

How bundles work.

Gas Sponsorship

Let users rebalance without holding ETH.

Get Started

Products

Data

Account Lifecycle

Platform Concepts

Developer Tools

Resources

Before you start

How it works

Example: move 50 USDC from Aave to a vault

Example: change token on the way

Actions you can bundle

Ready-made UI

Good to know

Endpoints

Next

Earn

Transaction Bundling

Gas Sponsorship

​Before you start

​How it works

​Example: move 50 USDC from Aave to a vault

​Example: change token on the way

​Actions you can bundle

​Ready-made UI

​Good to know

​Endpoints

​Next

Earn

Transaction Bundling

Gas Sponsorship

Before you start

How it works

Example: move 50 USDC from Aave to a vault

Example: change token on the way

Actions you can bundle

Ready-made UI

Good to know

Endpoints

Next