Surge Earn SDK

TypeScript SDK for integrating Surge Earn in web wallets and frontend apps.

Important behavior:

• Users become LPs by depositing USDC into the shared liquidity pool.
• There is no direct per-market deposit function on the pool.
• Variable/fixed market targeting is controlled by setExposure/setExposures before or after deposit.

Install

npm install @surgecredit/earn-sdk@latest viem

Quick start

import { createWalletClient, custom } from "viem";
import { baseSepolia } from "viem/chains";
import {
  SURGE_BASE_SEPOLIA_CONFIG,
  SurgeEarnClient,
  createSurgeEarnPublicClient,
} from "@surgecredit/earn-sdk";

const publicClient = createSurgeEarnPublicClient("https://sepolia.base.org", baseSepolia);
const walletClient = createWalletClient({
  chain: baseSepolia,
  transport: custom(window.ethereum),
});

const earn = new SurgeEarnClient({
  publicClient,
  walletClient,
  config: SURGE_BASE_SEPOLIA_CONFIG,
});

const markets = await earn.listMarkets();

Most-used methods

• Reads: listMarkets, getUserPosition, getUserExposures, getWalletUsdcBalance, getAllowance
• Writes: approveMaxUsdc, deposit, depositAsLp, withdrawByUsdc, withdrawByLpTokens, setExposure, setExposures
• Activity: listActivity, getUserActivity, listDepositEvents, listWithdrawEvents

Write compatibility notes:

• SDK write methods accept either a wallet address or a full account object.
• If your walletClient is created with account (for example mnemonicToAccount), write methods use that signer directly.
• If your walletClient is injected (for example window.ethereum), the SDK resolves the connected address automatically.

Deposit example

const address = "0xYourWalletAddress";
const amountUsdc = "100";

const allowance = await earn.getAllowance(address);
if (allowance === 0n) {
  await earn.approveMaxUsdc({ account: address, waitForReceipt: true });
}

await earn.deposit({ amountUsdc, account: address, waitForReceipt: true });

Fixed/variable targeting

Set exposures, then deposit as LP:

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

• Example above routes new LP allocation toward fixed market 2 by setting exposure first.
• For variable-first behavior, keep fixed exposures at 0 and call deposit.

React hooks

import { useEarnActivity, useEarnMarkets, useEarnPortfolio } from "@surgecredit/earn-sdk/react";

• useEarnMarkets(client, { includeInactive?, pollIntervalMs? })
• useEarnPortfolio(client, address)
• useEarnActivity(client, { user?, fromBlock?, toBlock?, includeTimestamps?, limit?, pollIntervalMs? })

Examples

• MetaMask helper snippet: examples/snippets/metamask-write.ts
• End-to-end wallet demo: examples/test-wallet

Run wallet demo:

cd examples/test-wallet
npm install
npm run dev