# Meme Volatility Index (MVI)

A real-time **meme stock ticker** for X — type any topic and watch hype score, momentum, chart, AI caption, and top posts update live.

Built with **OpenRouter** (`x-ai/grok-4.3` + xSearch), **Next.js**, and the **Vercel AI SDK**.

![Next.js](https://img.shields.io/badge/Next.js-16-black)
![Bun](https://img.shields.io/badge/Bun-1.x-black)
![OpenRouter](https://img.shields.io/badge/OpenRouter-xSearch-7c3aed)

## What it does

- **Hype Score** (1–10) with Pumping / Dumping / Stable momentum
- **Live chart** that appends a point on each analysis
- **AI meme caption** + key insights
- **Top Signals** — high-signal X posts with per-post hype ratings
- **Live Mode** — polls every 5 seconds while enabled

## How OpenRouter fits in

MVI uses a single env var, `OPENROUTER_API_KEY`, and the official [`@openrouter/ai-sdk-provider`](https://github.com/OpenRouterTeam/ai-sdk-provider):

| Piece | Detail |
|-------|--------|
| Model | `x-ai/grok-4.3` |
| xSearch | `web` plugin — live X posts in context |
| Structured output | `generateObject` + Zod schema |
| JSON repair | `response-healing` plugin |

```ts
const model = openrouter("x-ai/grok-4.3", {
  plugins: [{ id: "web" }, { id: "response-healing" }],
});

const { object } = await generateObject({
  model,
  schema: MemeAnalysisSchema,
  prompt: `Analyze hype around: "${topic}"`,
});
```

## Quick start

**Requirements:** [Bun](https://bun.sh) (or Node 20+), an [OpenRouter API key](https://openrouter.ai/keys)

```bash
git clone git@github.com:colesmcintosh/meme-volatility-index.git
cd meme-volatility-index
bun install
cp .env.example .env.local
# Edit .env.local — add OPENROUTER_API_KEY only
bun dev
```

Open [http://localhost:3000](http://localhost:3000).

## Project structure

```
app/
  api/analyze/route.ts   # OpenRouter analysis endpoint
  page.tsx               # Dashboard entry
  layout.tsx
components/
  dashboard/             # Hype score, chart, caption, signals
  providers/             # TanStack Query
  ui/                    # Shared primitives
lib/
  schemas/               # Zod MemeAnalysis schema
  constants.ts           # Presets, poll interval, system prompt
  openrouter.ts          # Provider + model config
```

## API

`POST /api/analyze`

```json
{ "topic": "NBA Finals" }
```

Returns structured JSON: `hype_score`, `direction`, `volatility_level`, `ai_meme_caption`, `key_insights`, `top_posts`, etc.

## Deploy (Vercel)

1. Import the GitHub repo
2. Set `OPENROUTER_API_KEY` in project environment variables
3. Deploy — no other secrets required

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENROUTER_API_KEY` | Yes | From [openrouter.ai/keys](https://openrouter.ai/keys) |

Never commit `.env.local` or real API keys. See [SECURITY.md](./SECURITY.md).

## Cost notes

- One analysis ≈ 10–20s (xSearch + structured output)
- Live Mode ≈ 12 requests/min per active user at 5s polling
- Target ~$0.01–0.02 per analysis on `grok-4.3` (varies by topic)

## Scripts

```bash
bun dev      # local dev server
bun build    # production build
bun start    # run production build
bun lint     # ESLint
```

## License

MIT — see [LICENSE](./LICENSE).