Integrate an Earn Product

Build a one-deposit earn experience on Base with the Base Earn API: a vault catalog, live positions, and redeemable value.

Give users a simple earn product: they pick a vault, deposit once, and watch the value of their position. The Base Earn API supplies the vault catalog, position values, and unsigned transactions, so your app focuses on the experience while the user’s existing wallet signs every action.

The Base Earn API is in developer preview. Upshift Earn (cbXRP) is available in early access. Morpho Earn (USDC) is coming soon.

​

Demo

The demo above is mock only. If you want to see onchain demos on Vibenet, head to Base chain demos.

​

Design the Experience

1. Show a curated catalog

   Build your list from GET /lend/vaults, filtered to the vaults your app has approved. Show each vault’s name, asset, and provider. For Upshift, also show depositsPaused, withdrawalsPaused, and the waiting period from redemptionLagSeconds.

2. Take one deposit

   The user enters an amount and approves one batch from POST /lend/deposit. The batch may include a token approval; execute every call in order.

3. Show redeemable value

   Read GET /lend/positions after each confirmed action. Display assets, the current value of the user’s shares, rather than a fixed return. For Upshift, assetsAfterFee is the value net of the current withdrawal fee.

4. Set exit expectations

   Read withdrawalMode before the user commits. Morpho (synchronous) withdraws in one step. Upshift (queued) needs a request, a waiting period, and a claim, so show the expected claim date and the queued amount until it is claimed.

​

Build the Portfolio View

This example joins the catalog with the user’s positions for a portfolio screen. It uses earn() from Call the API in TypeScript, Python, or Go (earn.Call, which returns raw JSON); deposits and withdrawals follow Integrate Lending and End-to-End Lend Examples.

TypeScript

const { vaults } = await earn("GET", "/lend/vaults?network=base");
const { positions } = await earn("GET", `/lend/positions?address=${encodeURIComponent(address)}`);

const portfolio = vaults
  .filter(v => approvedVaultIds.includes(v.vaultId))
  .map(vault => {
    const position = positions.find(p => p.vaultId === vault.vaultId);
    return {
      name: vault.name,
      asset: vault.asset, // symbol and decimals for display
      provider: vault.provider,
      exit: vault.withdrawalMode, // "synchronous" or "queued"
      shares: position?.shares ?? "0",
      value: position?.assetsAfterFee ?? position?.assets ?? "0", // atomic units
    };
  });

Amounts are atomic-unit strings; format them with each token’s decimals from discovery. Upshift shares already in the redemption queue are not included in positions, so track queued withdrawals with GET /lend/redemptions.

Yield is variable and not guaranteed, and funds are exposed to protocol risk. A position’s current value is not guaranteed withdrawal proceeds: withdrawals depend on liquidity and protocol conditions, and fees depend on the vault. An absent fee field does not mean there are no fees. Review each vault before listing it and never present a fixed return.

​

See Also

Base Earn API

Supported protocols, endpoints, and quick start.

Concepts

Vaults, shares, withdrawal modes, and queued withdrawals.

Base Earn API FAQ

Custody, accounts, fees, and withdrawal questions.

Integrate Lending

Deposit and withdraw through the same API.