Earn SDK Integration Guide

This page is intentionally concise so wallet teams and AI tools can integrate quickly.

Important behavior:

LPs deposit into the shared pool (not directly into a single market contract).
Market routing is controlled with exposure settings (setExposure / setExposures).

1) Install

npm install @surgecredit/earn-sdk@latest viem

2) Initialize SDK

import { createWalletClient, custom } from "viem";
import { baseSepolia } from "viem/chains";
import {
  SurgeEarnClient,
  SURGE_BASE_SEPOLIA_CONFIG,
  createSurgeEarnPublicClient,
} from "@surgecredit/earn-sdk";
 
const publicClient = createSurgeEarnPublicClient("https://sepolia.base.org", baseSepolia);
 
const walletClient = createWalletClient({
  chain: baseSepolia,
  transport: custom(window.ethereum),
});
 
export const earn = new SurgeEarnClient({
  publicClient,
  walletClient,
  config: SURGE_BASE_SEPOLIA_CONFIG,
});

If your wallet uses a local signer/account object (for example createWalletFromMnemonic), pass that account into createWalletClient. SDK writes will use it directly (no custom writeContract wrappers needed):

import { createWalletClient, http } from "viem";
import { mnemonicToAccount } from "viem/accounts";
 
const account = mnemonicToAccount("test test test ...");
 
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http("https://sepolia.base.org"),
});
 
const earn = new SurgeEarnClient({
  publicClient,
  walletClient,
  config: SURGE_BASE_SEPOLIA_CONFIG,
});
 
await earn.deposit({ amountUsdc: "100", waitForReceipt: true });

3) Read markets and user state

const address = "0xYourWalletAddress";
 
const [markets, position, exposures, usdcBalance] = await Promise.all([
  earn.listMarkets(),
  earn.getUserPosition(address),
  earn.getUserExposures(address),
  earn.getWalletUsdcBalance(address),
]);

4) Deposit flow (wallet invest)

const address = "0xYourWalletAddress";
const amountUsdc = "100";
 
const allowance = await earn.getAllowance(address);
if (allowance === 0n) {
  await earn.approveMaxUsdc({ waitForReceipt: true });
}
 
await earn.deposit({ amountUsdc, waitForReceipt: true });

Target a fixed market allocation in one flow:

await earn.depositAsLp({
  amountUsdc: "100",
  exposureUpdates: [{ marketId: 2, exposurePercent: 100 }],
  waitForReceipt: true,
});

5) Withdraw flow

await earn.withdrawByUsdc({
  amountUsdc: "25",
  waitForReceipt: true,
});

6) Activity feed

const activity = await earn.getUserActivity("0xYourWalletAddress", {
  includeTimestamps: true,
  limit: 25,
});

7) React hooks (optional)

import { useEarnActivity, useEarnMarkets, useEarnPortfolio } from "@surgecredit/earn-sdk/react";
 
function EarnView({ client, address }: { client: any; address: `0x${string}` }) {
  const { data: markets } = useEarnMarkets(client, { pollIntervalMs: 15000 });
  const { data: portfolio } = useEarnPortfolio(client, address);
  const { data: activity } = useEarnActivity(client, { user: address, limit: 10, pollIntervalMs: 15000 });
 
  return (
    <div>
      <div>Markets: {markets.length}</div>
      <div>Current Value: {portfolio.position?.currentValue ?? 0}</div>
      <div>Recent Activity: {activity.length}</div>
    </div>
  );
}

Integration checklist

Wallet network is Base Sepolia (chainId: 84532)
Reliable Base Sepolia RPC configured
USDC token decimals treated as 6
Wait for transaction receipts before refreshing UI
Show tx hash and explorer link after write actions