Earn SDK Example

A minimal React example for @satsterminal-sdk/earn: connect wallet, setup session, list pools, create a deposit, and check deposit status.

Prerequisites

• Node.js 18+
• Bitcoin wallet: UniSat or Xverse browser extension
• SatsTerminal API key

When this repo lives next to satsterminal-sdk, package.json points at the local SDK packages (file:../satsterminal-sdk/packages/...). Build the SDK once with cd ../satsterminal-sdk && npm run build, then run the example. If you clone only earn-sdk-example, switch those dependencies to @satsterminal-sdk/earn and @satsterminal-sdk/core from npm.

Setup

1. Install dependencies:

   npm install

2. Copy env and add your API key:

   cp .env.example .env

   Set VITE_API_KEY=your-api-key-here in .env.

Run

# Development
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

Flow (v1)

1. Connect – Connect UniSat or Xverse.
2. Setup – Click “Setup earn session” and sign with your wallet. This derives your smart account and authorizes the session.
3. Pools – Click “Refresh” to load earn pools. Select a pool.
4. Deposit – Enter amount and tokens, then “Create deposit”. The created transaction ID is stored for the Status tab.
5. Status – Open the “Status” tab and click the refresh button to fetch deposit status for the last transaction (or paste any transaction ID).

SDK usage (from this app)

The app uses a single provider/hook, useEarnSDK, which wraps the Earn SDK and wallet connection:

import { EarnSDKProvider, useEarnSDK } from '@/hooks/useEarnSDK'

// Wrap app
<EarnSDKProvider>
  <App />
</EarnSDKProvider>

// In components
const {
  isConnected,
  btcAddress,
  connect,
  disconnect,
  setupDone,
  setup,
  pools,
  poolsLoading,
  fetchPools,
  createDeposit,
  lastDepositTxId,
  depositStatus,
  depositStatusLoading,
  fetchDepositStatus,
} = useEarnSDK()

• connect('unisat' | 'xverse') – Connect wallet.
• setup() – Derive smart account and authorize session; required before pools/deposit.
• fetchPools(params?) – Load pools (optional collateralToken, chain).
• createDeposit({ poolId, depositAmount, depositToken, collateralToken }) – Create deposit; returns transaction ID.
• fetchDepositStatus(transactionId) – Load status for a deposit.

Limitations (v1)

• No withdrawal flow.
• Deposit form uses simple text inputs; production apps would validate and format amounts/tokens per pool.

Tech stack

• React 19, TypeScript, Vite
• Tailwind CSS, Radix UI (Label, Slot, Toast)
• sats-connect (Xverse)
• @satsterminal-sdk/earn, @satsterminal-sdk/core