xStocks - Yield Comparison Platform for Tokenized Stocks

A yield comparison platform that helps users find the best DeFi yield strategies for tokenized stocks (xStocks) across multiple Solana protocols.

What It Does

xStocks aggregates and compares yield opportunities for tokenized stocks across DeFi protocols, letting users:

• Compare yields across Kamino, Falcon Finance, Raydium, and TermMax at a glance
• Assess risk with per-strategy risk breakdowns (smart contract, liquidity, protocol, market)
• Sort and filter by APY, risk level, TVL, asset, or protocol
• Sync live data from on-chain sources via protocol adapters
• Drill into strategies with detailed pages showing how each strategy works

Supported Assets

AAPL, TSLA, GOOGL, MSFT, NVDA (5 assets x 4 protocols = 20 strategies)

Supported Protocols

• Kamino - Variable-rate lending/yield strategies
• Falcon Finance - Structured yield products
• Raydium - AMM-based liquidity provision
• TermMax - Fixed-rate term lending

Tech Stack

Layer	Technology
Frontend	Next.js 14 (App Router), Tailwind CSS, shadcn/ui, TanStack Query
Backend	Node.js, Express, Prisma ORM, Zod validation
Database	PostgreSQL
On-chain	Solana Web3.js, Kamino KLEND SDK, Raydium SDK
Deployment	Vercel (UI), Docker (API)

Project Structure

packages/
├── ui/          # Next.js frontend
├── api/         # Express REST API + protocol adapters
└── db/          # Shared database utilities

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL
• npm 9+

Installation

# Install all dependencies (npm workspaces)
npm install

# Setup the database
cd packages/api
cp .env.development .env
npx prisma migrate dev
npm run db:seed

Running Locally

# Terminal 1 - API (port 3001)
cd packages/api
npm run dev

# Terminal 2 - UI (port 3000)
cd packages/ui
npm run dev

API

Endpoints

Method	Endpoint	Description
GET	/api/v1/yields/comparison	Compare yields across all strategies. Filterable by ?assets=AAPL,TSLA&protocols=kamino
GET	/api/v1/strategies/:id	Get full strategy details with risk breakdown
POST	/api/v1/yields/sync	Trigger yield data sync from protocol adapters

See API-INTEGRATION.md for full request/response examples.

Architecture

Yield Sync System

Protocol adapters fetch yield data from on-chain sources using a factory pattern:

POST /yields/sync
  → YieldSyncService
    → ProtocolFactory (returns correct adapter)
      → Kamino / Falcon / Raydium / TermMax adapters
        → External APIs / On-chain data
          → New YieldSnapshot records in DB

Each adapter extends a BaseProtocolAdapter and implements getYieldData() for its specific protocol.

Risk Scoring

Every strategy has a multi-dimensional risk score covering:

• Smart contract risk
• Liquidity risk
• Protocol risk
• Market risk
• Overall composite score with a label (Low / Medium / High)

Environment Variables

API (packages/api/.env):

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/xstocks_dev"
PORT=3001
NODE_ENV=development
CORS_ORIGIN=http://localhost:3000

UI (packages/ui/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1

License

MIT