React Widgets

Fastest path: AI assistants

Paste this into any AI coding agent — Claude Code, Cursor, Windsurf, ChatGPT, or anything that can fetch a URL:

Fetch https://compasslabs.ai/llms-widgets.md and integrate Compass widgets into this project.

The agent will pull the full integration guide, install dependencies, generate the provider/server/widget files, and wire up your env. Claude Code users can install the slash command for repeat use:

mkdir -p .claude/commands
curl -o .claude/commands/integrate-compass-widgets.md \
  https://compasslabs.ai/integrate-compass-widgets.md

Then run /integrate-compass-widgets.

How it works

User connects their wallet
Widget shows yield opportunities (Aave, Morpho vaults, Pendle, credit, rebalancing)
User picks a market, enters an amount, signs an EIP-712 transaction
Your server relays the signed transaction to Compass; gas can be sponsored
Each user gets a non-custodial product account — they sign every transaction themselves

Installation

npm install @compass-labs/widgets @tanstack/react-query react react-dom

You also need a wallet library. Anything that gives you an EIP-712 signer works — Privy, RainbowKit + wagmi, etc.

Quick start

Three steps: wrap with providers, add a server route, drop in a widget.

1. Providers

// components/providers.tsx
"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { PrivyProvider, usePrivy, useWallets } from "@privy-io/react-auth";
import { CompassProvider } from "@compass-labs/widgets";

const queryClient = new QueryClient();

function CompassWithPrivy({ children }: { children: React.ReactNode }) {
  const { login, logout } = usePrivy();
  const { wallets } = useWallets();
  const wallet = wallets[0];

  return (
    <CompassProvider
      defaultChain="base"
      wallet={{
        address: wallet?.address ?? null,
        signTypedData: async (data) => {
          const provider = await wallet?.getEthereumProvider();
          return provider.request({
            method: "eth_signTypedData_v4",
            params: [wallet.address, JSON.stringify(data)],
          });
        },
        login,
        logout,
      }}
    >
      {children}
    </CompassProvider>
  );
}

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <PrivyProvider appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!} config={{ /* ... */ }}>
      <QueryClientProvider client={queryClient}>
        <CompassWithPrivy>{children}</CompassWithPrivy>
      </QueryClientProvider>
    </PrivyProvider>
  );
}

Using RainbowKit, wagmi, or another library? See llms-widgets.md for full provider examples.

2. Server route

// app/api/compass/[...path]/route.ts
import { createCompassHandler } from "@compass-labs/widgets/server";

const handler = createCompassHandler({
  apiKey: process.env.COMPASS_API_KEY!,
  gasSponsorPrivateKey: process.env.GAS_SPONSOR_PK, // optional
  rpcUrls: {
    ethereum: process.env.ETHEREUM_MAINNET_RPC_URL,
    base: process.env.BASE_MAINNET_RPC_URL,
    arbitrum: process.env.ARBITRUM_MAINNET_RPC_URL,
  },
});

export const GET = handler;
export const POST = handler;

Using NestJS?

import { CompassModule } from "@compass-labs/widgets/server/nestjs";

@Module({
  imports: [
    CompassModule.register({
      apiKey: process.env.COMPASS_API_KEY!,
      rpcUrls: { /* ... */ },
    }),
  ],
})
export class AppModule {}

CompassModule.registerAsync() is also available if you need to inject config from another module (e.g. ConfigService). Routes are served at /api/compass/* — no global prefix needed.

// app/layout.tsx
import "@compass-labs/widgets/styles.css";

// app/page.tsx
"use client";
import { EarnAccount } from "@compass-labs/widgets";

export default function Home() {
  return <EarnAccount />;
}

Tailwind users — register the package as content:

// Tailwind v3
content: [..., "./node_modules/@compass-labs/widgets/**/*.{js,mjs,ts,tsx}"]

// Tailwind v4 (in CSS)
@source "../node_modules/@compass-labs/widgets/dist/**/*.{js,mjs}";

Available widgets

Widget	What it does
`EarnAccount`	Banking-style savings account — variable (Aave, Morpho) + fixed (Pendle) markets, deposit/withdraw, P&L
`CompassEarnWidget`	Unified earn interface combining variable and fixed markets
`CreditAccount`	Credit borrowing UI on top of an earn position
`RebalancingWidget`	Automated portfolio rebalancing across positions
`TraditionalInvestingWidget`	Tokenized stocks interface

Each widget accepts theming and sizing props. For full prop references, see llms-widgets.md or hover the types in your IDE.

<EarnAccount
  title="Savings Account"
  defaultMarketTab="variable"
  chain="base"
  onDeposit={(market, amount, txHash) => {}}
  onWithdraw={(market, amount, txHash) => {}}
/>

Building custom UIs

Prefer to compose your own layout? The SDK exports building blocks:

Shared components — ChainSwitcher, WalletStatus, EarnAccountGuard, CreditAccountGuard, EarnAccountBalance, AccountBalancesModal, DepositWithdrawForm, SwapForm, PnLSummary, TransactionHistory, CopyableAddress, ActionModal
Data hooks — useSwapQuote, useRebalancingData, useRefreshBalances
Context hooks — useCompassWallet, useCompassChain, useCompassApi, useEarnAccount, useCreditAccount

Theming

Six built-in presets: compass-dark, compass-light, minimal-dark, minimal-light, high-contrast-dark, high-contrast-light.

<CompassProvider theme="compass-dark" defaultChain="base">
  {/* widgets */}
</CompassProvider>

Override specific values:

<CompassProvider
  theme={{
    preset: 'compass-dark',
    overrides: { colors: { brand: { primary: '#8b5cf6' } } },
  }}
>

The full schema (colors, typography, spacing, shape, effects) is exported as the Theme type — your IDE will autocomplete every override.

Wallet adapter

CompassProvider needs a wallet prop bridging your wallet library to the widgets:

interface WalletAdapter {
  address: Address | null;
  chainId?: number;
  signTypedData: (data: TypedDataToSign) => Promise<string>;
  switchChain?: (chainId: number) => Promise<void>;
  login?: () => void;
  logout?: () => Promise<void>;
  ready?: boolean;
  fundWallet?: (params: FundWalletParams) => Promise<void>;
  sendTransaction?: (params: SendTransactionParams) => Promise<string>;
  hasExternalWallet?: boolean;
}

signTypedData is the critical one — every transaction is EIP-712 signed by the user, then your server relays it (and optionally sponsors gas).

Supported chains

ethereum, base, arbitrum.

Gas sponsorship

Set gasSponsorPrivateKey and rpcUrls on the server handler. Widgets automatically use sponsored transactions when configured. See Gas Sponsorship.

Next steps

LLM Integration Guide

Full reference for AI-assisted integration.

Earn

The underlying Yield API.

Fixed Earn

Add fixed-yield Pendle markets to your product.

Gas Sponsorship

Sponsor gas so users never need ETH.

Get Started

Quick Guides

Agents

Products

Features

Support

Fastest path: AI assistants

How it works

Installation

Quick start

1. Providers

2. Server route

3. Add a widget

Available widgets

Building custom UIs

Theming

Wallet adapter

Supported chains

Gas sponsorship

Next steps

LLM Integration Guide

Earn

Fixed Earn

Gas Sponsorship

​Fastest path: AI assistants

​How it works

​Installation

​Quick start

​1. Providers

​2. Server route

​3. Add a widget

​Available widgets

​Building custom UIs

​Theming

​Wallet adapter

​Supported chains

​Gas sponsorship

​Next steps

LLM Integration Guide

Earn

Fixed Earn

Gas Sponsorship

Fastest path: AI assistants

How it works

Installation

Quick start

1. Providers

2. Server route

3. Add a widget

Available widgets

Building custom UIs

Theming

Wallet adapter

Supported chains

Gas sponsorship

Next steps