Earn

Earn lets your users put stablecoins and crypto to work in DeFi yield venues: Aave V3 lending markets, and yield vaults from Morpho and Euler. You pick a venue, the API builds the deposit, your user signs it, and the position is tracked with PnL from then on. Every venue looks the same to your code. A vault or an Aave market is just the venue field on one deposit call, so you can add venues without changing your integration.

Before you start

An API key. See the Quick Start.
An Earn Account for the user on the chain you want, holding the token to deposit. See Create an Account and Fund an Account.

Earn runs on every chain Compass supports. See Supported Chains.

1. Find a venue

Vaults come with their APY over 7, 30 and 90 days, TVL and available liquidity. This lists USDC vaults on Base with at least a million dollars of liquidity, best 30-day APY first:

import os
from compass_api_sdk import CompassAPI

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

vaults = compass.earn.earn_vaults(
    chain="base",
    asset_symbol="USDC",
    order_by="apy_30d",
    min_liquidity_usd=1_000_000,
).vaults

for vault in vaults:
    print(vault.name, vault.vault_address, vault.apy_30d)

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

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

const { vaults } = await compass.earn.earnVaults({
  chain: "base",
  assetSymbol: "USDC",
  orderBy: "apy_30d",
  minLiquidityUsd: 1_000_000,
});

for (const vault of vaults) {
  console.log(vault.name, vault.vaultAddress, vault.apy30d);
}

curl "https://api.compasslabs.ai/v2/earn/vaults?chain=base&asset_symbol=USDC&order_by=apy_30d&min_liquidity_usd=1000000" \
  -H "x-api-key: $COMPASS_API_KEY"

Each vault has a vault_address (what you pass when depositing), name, protocol (MORPHO or EULER), asset_symbol, apy_30d and tvl_usd. Aave markets are listed per chain, each token with its supply and borrow APY:

markets = compass.earn.earn_aave_markets(chain="base").markets

for symbol, market in markets.items():
    rates = market.chains["base"]
    print(symbol, rates.supply_apy, rates.borrow_apy)

const { markets } = await compass.earn.earnAaveMarkets({ chain: "base" });

for (const [symbol, market] of Object.entries(markets)) {
  const rates = market.chains["base"];
  console.log(symbol, rates?.supplyApy, rates?.borrowApy);
}

curl "https://api.compasslabs.ai/v2/earn/aave_markets?chain=base" \
  -H "x-api-key: $COMPASS_API_KEY"

2. Deposit

Deposit 100 USDC from the user’s Earn Account into a vault:

deposit = compass.earn.earn_manage(
    owner="0xYourWalletAddress",
    chain="base",
    venue={"type": "VAULT", "vault_address": "0xVaultAddress"},
    action="DEPOSIT",
    amount="100",
)

# deposit.transaction: unsigned tx for the owner to sign and send

const deposit = await compass.earn.earnManage({
  owner: "0xYourWalletAddress",
  chain: "base",
  venue: { type: "VAULT", vaultAddress: "0xVaultAddress" },
  action: "DEPOSIT",
  amount: "100",
});

// deposit.transaction: unsigned tx for the owner to sign and send

curl -X POST "https://api.compasslabs.ai/v2/earn/manage" \
  -H "x-api-key: $COMPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "0xYourWalletAddress",
    "chain": "base",
    "venue": {"type": "VAULT", "vault_address": "0xVaultAddress"},
    "action": "DEPOSIT",
    "amount": "100"
  }'

Field	Description
`venue`	`{"type": "VAULT", "vault_address": "0x..."}` for a vault, or `{"type": "AAVE", "token": "USDC"}` for an Aave market.
`action`	`DEPOSIT` or `WITHDRAW`.
`amount`	In units of the venue’s token, not wei: `"100"` is 100 USDC.
`fee`	Optional. Your fee on this deposit or withdrawal, paid to your address in the same transaction. See Embedded Fees.
`gas_sponsorship`	Optional. `true` returns `eip_712` for the user to sign instead of a transaction, so your wallet can pay the gas. See Gas Sponsorship.

The user signs transaction and sends it. Once it confirms, the position is live.

3. Track the position

positions = compass.earn.earn_positions(
    chain="base", owner="0xYourWalletAddress"
)

print(positions.total_usd_value)
for vault in positions.vaults:
    print(vault.vault_name, vault.balance, vault.usd_value)

const positions = await compass.earn.earnPositions({
  chain: "base",
  owner: "0xYourWalletAddress",
});

console.log(positions.totalUsdValue);
for (const vault of positions.vaults ?? []) {
  console.log(vault.vaultName, vault.balance, vault.usdValue);
}

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

Positions come back grouped as vaults, aave and pendle_pt, with a total_usd_value. Each has its current balance and usd_value, the venue’s APY, and a pnl block with total_deposited, unrealized_pnl, realized_pnl and total_pnl, plus every deposit and withdrawal with its transaction hash. How Yield Accrues explains the numbers. For one call across Ethereum, Base, Arbitrum and HyperEVM, use GET /v2/earn/positions_all.

4. Withdraw

Call manage again with action: "WITHDRAW" and the same venue. The tokens return to the Earn Account. Then send them to the user’s wallet with transfer. See Withdraw Funds.

Good to know

Deposit whatever the user holds. If the user holds ETH and the vault takes USDC, put a swap and the deposit in one bundle, so the user signs once. swap_quote previews the rate first.
Fixed rates. For a rate locked until a maturity date, see Fixed Earn. It’s the same manage call with a PENDLE_PT venue.
Moving between venues. A withdrawal and a deposit can run in one transaction. See Portfolio Rebalancer.
APYs are percentages (5.25 means 5.25%) that look back over a window. They aren’t a promise of future yield, and they’re null when there isn’t enough history yet.
Show only vaults users can use. Filter with min_liquidity_usd, and min_deposit_cap_usd=0 to drop paused vaults.

Endpoints

Endpoint	Use it to
`GET /v2/earn/vaults`	List vaults with APY, TVL and liquidity.
`GET /v2/earn/aave_markets`	List Aave markets with supply and borrow rates.
`POST /v2/earn/manage`	Deposit into or withdraw from a venue.
`GET /v2/earn/positions`	Read positions and PnL on one chain.
`GET /v2/earn/positions_all`	Read positions across chains.
`GET /v2/earn/balances`	Read idle token balances in the Earn Account.
`POST /v2/earn/swap`	Swap tokens inside the Earn Account.
`POST /v2/earn/bundle`	Run several actions in one transaction.

Embedded Fees

Earn a fee on every deposit or withdrawal.

Gas Sponsorship

Pay gas for your users so they never need ETH.

Fixed Earn

Offer a fixed rate for a set term.

Get Started

Products

Data

Account Lifecycle

Platform Concepts

Developer Tools

Resources