even ▸ README.md
updated 2026-02-28

Even - Unicorn.Land MVP

A production-ready MVP for Unicorn.Land’s “Even” product: a low-touch, inequality-driven macro trading decision-support dashboard.

Overview

Even operationalizes an inequality/incentive framework to pick simple, liquid, retail-accessible trades and monitor persistence. It runs a weekly loop: Diagnose → Map → Select instrument → Position sizing helper → Monitor → Reassess only if incentives truly shift.

Tech Stack

Features

Core Pages

Data Model

Market Tiles

Quick Start

Prerequisites

Installation

  1. Clone and install dependencies:
cd even
pnpm install
  1. Set up environment:
cp env.example .env.local
# Edit .env.local with your configuration
  1. Set up database:
pnpm prisma migrate dev
pnpm prisma db seed
  1. Start development server:
pnpm dev
  1. Open in browser:
http://localhost:3000/even

API Endpoints

Core APIs

Cron Jobs (Manual Triggers)

Sample API Calls

Pull Market Metrics

curl -X POST http://localhost:3000/api/cron/pull-metrics

Generate Weekly Summary

curl -X POST http://localhost:3000/api/cron/weekly-summary

Scan News

curl -X POST http://localhost:3000/api/cron/scan-news

Create a Mechanism

curl -X POST http://localhost:3000/api/mechanisms \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fed Policy Uncertainty",
    "whoGains": "Risk-averse investors",
    "whoPays": "Growth stocks and leveraged positions",
    "persistence": "Central bank policy uncertainty creates sustained demand for safe assets",
    "channels": ["duration", "credit"],
    "invalidators": ["Clear Fed guidance", "Economic data normalization"],
    "persistenceScore": 75
  }'

Create a Trade

curl -X POST http://localhost:3000/api/trades \
  -H "Content-Type: application/json" \
  -d '{
    "instrument": "TLT",
    "venue": "ETF",
    "side": "long",
    "entry": 95.50,
    "stop": 92.00,
    "target": 100.00,
    "sizeEUR": 1000,
    "riskEUR": 35.00,
    "notes": "Duration play on Fed uncertainty"
  }'

Data Adapters

The system includes pluggable data providers with graceful fallbacks:

Market Data (lib/adapters/marketData.ts)

Derived Metrics (lib/adapters/derived.ts)

Macro Data (lib/adapters/macro.ts)

Rules Engine

Color Thresholds

Alert Rules

Production Deployment

Environment Variables

DATABASE_URL="file:./prod.db"
NEXT_PUBLIC_APP_URL="https://your-domain.com"
# Optional API keys for real data providers
# ALPHA_VANTAGE_API_KEY=""
# TIINGO_API_KEY=""
# POLYGON_API_KEY=""
# NEWS_API_KEY=""

Database Migration

pnpm prisma migrate deploy
pnpm prisma db seed

Build and Start

pnpm build
pnpm start

Extending the System

Adding Real Data Providers

  1. Implement the MarketDataProvider interface
  2. Add provider to MarketDataService constructor
  3. Update environment variables

Adding New Tiles

  1. Add to DerivedMetricsService.computeMetrics()
  2. Add color rules to RulesEngine
  3. Update TileGrid component
  4. Add to database migration

Adding New Alert Types

  1. Add to AlertRule type in rules.ts
  2. Implement condition logic
  3. Update alert creation in cron jobs

Architecture

even/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── cron/          # Manual cron endpoints
│   │   └── ...            # Core APIs
│   ├── even/              # Main app pages
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   └── ...               # Custom components
├── lib/                  # Core logic
│   ├── adapters/         # Data providers
│   ├── repositories/     # Database layer
│   ├── rules.ts          # Rules engine
│   └── validations.ts    # Zod schemas
├── prisma/               # Database schema & migrations
└── public/               # Static assets

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

Private - Unicorn.Land Internal Use Only