XFlux

Name: XFlux
Author: yxs1640-png

Affordable & stable X/Twitter API proxy service — MVP built with Next.js 15, TypeScript, Prisma, and PostgreSQL.

Features (MVP)

Landing page — Marketing site with pricing and feature overview
User auth — Email/password registration and login (NextAuth)
API Keys — Generate and manage xflux_* API keys
REST API proxy — User profiles, tweets, search (mock + optional live Twitter API v2)
MCP server — Official Registry + npm (@xflux/xflux-mcp-server) for Claude Desktop & Cursor
Dashboard — Usage stats, API logs, quota tracking
Monitors — KOL tweet monitoring task management
Billing — Stripe Checkout subscriptions (Starter / Growth / Pro / Scale); see docs/STRIPE.md

MCP (Claude / Cursor)

Published on the MCP Registry as io.github.yxs1640-png/xflux and on npm as @xflux/xflux-mcp-server.

export XFLUX_API_KEY=xflux_your_key_here
npx -y @xflux/xflux-mcp-server

Docs: https://www.xfluxapi.com/docs/integrations/mcp

Tech Stack

Next.js 15 (App Router)
TypeScript
Tailwind CSS 4
Prisma + PostgreSQL
NextAuth.js
Recharts

Architecture

Vercel — Next.js app, auth, dashboard, public /api/v1/*
Fly.io — api-server/ (Consumer API proxy) + Dockerfile.worker (Monitor 轮询)
Supabase — PostgreSQL

See docs/DEPLOYMENT.md for Vercel + Fly.io deployment.

Quick Start

Prerequisites

Node.js 20+
PostgreSQL database (local, Neon, Supabase, or Vercel Postgres)

Supabase 数据库配置

Supabase 新版界面里，连接串不在 Project Settings → Database，而在：

项目首页顶部 → 点击 Connect 按钮

只有 DIRECT_URL 时（本地开发够用）

Project Overview 里若已有 DIRECT_URL（端口 5432），在 .env 里 两个变量都填同一个值 即可：

DATABASE_URL="你的DIRECT_URL完整连接串"
DIRECT_URL="你的DIRECT_URL完整连接串"

示例格式：

DATABASE_URL="postgresql://postgres:你的密码@db.abcdefgh.supabase.co:5432/postgres"
DIRECT_URL="postgresql://postgres:你的密码@db.abcdefgh.supabase.co:5432/postgres"

然后执行：

npx prisma db push
npm run dev

需要 DATABASE_URL（6543 池化连接）时

项目首页 → Connect
选择 ORMs → Prisma，或选 Transaction pooler（端口 6543）
复制 Transaction 连接串 → 填入 DATABASE_URL，末尾加 ?pgbouncer=true
DIRECT_URL 仍用 5432 直连（Connect → Direct connection 或 Overview 里的值）

变量	从哪里找	端口
`DIRECT_URL`	Connect → Direct connection，或 Project Overview	5432
`DATABASE_URL`	Connect → Transaction pooler / ORMs → Prisma	6543

本地开发用 5432 直连即可；部署 Vercel 时再把 DATABASE_URL 换成 6543 池化连接。

部署到 Vercel 时，在 Environment Variables 里添加 DATABASE_URL、DIRECT_URL、NEXTAUTH_URL、NEXTAUTH_SECRET。

Setup

cd ~/Projects/xflux
npm install

cp .env.example .env
# Default uses SQLite — no Postgres install needed

npx prisma db push
npm run dev

Local database options:

Option	Command	When to use
SQLite (default)	`DATABASE_URL="file:./dev.db"`	Quick local dev, no install
Docker Postgres	`npm run db:up` then use postgres URL in `.env`	Match production locally
Neon (cloud)	Paste URL from neon.tech	No Docker, free tier

For Docker Postgres, change prisma/schema.prisma provider back to postgresql and set: DATABASE_URL="postgresql://xflux:xflux@localhost:5432/xflux?schema=public"

Open http://localhost:3000

Environment Variables

Variable	Required	Description
`DATABASE_URL`	Yes	`file:./dev.db` (local SQLite) or PostgreSQL URL (production)
`NEXTAUTH_URL`	Yes	App URL (e.g. `http://localhost:3000`)
`NEXTAUTH_SECRET`	Yes	Random 32+ char secret
`TWITTER_BEARER_TOKEN`	No	Twitter API v2 bearer token for live data
`STRIPE_*` / `BILLING_CHECKOUT_ENABLED`	Prod	Live billing on Vercel — see docs/STRIPE.md

Generate a secret:

openssl rand -base64 32

API Usage

After registering, use your API key:

curl -H "Authorization: Bearer xflux_YOUR_KEY" \
  http://localhost:3000/api/v1/users/elonmusk

Endpoints

Method	Path	Description
GET	`/api/v1/users/:username`	User profile
GET	`/api/v1/users/:username/tweets`	User timeline
GET	`/api/v1/tweets/:id`	Tweet by ID
GET	`/api/v1/search?q=keyword`	Search tweets
POST	`/api/v1/tweets`	Post tweet (requires OAuth setup)

Deploy to Vercel

Option A: Vercel CLI

npm i -g vercel
vercel login
vercel

Option B: GitHub Integration

Push to GitHub:

git add .
git commit -m "Initial XFlux MVP"
git remote add origin YOUR_REPO_URL
git push -u origin main

Import project at vercel.com/new
Add environment variables in Vercel dashboard:
- DATABASE_URL — from Vercel Postgres or Neon
- NEXTAUTH_URL — your production URL (e.g. https://xflux.vercel.app)
- NEXTAUTH_SECRET — random secret
- TWITTER_BEARER_TOKEN — optional
After first deploy, run database migration:
```
npx prisma db push
```
Or add a build step with Vercel Postgres integration.

Vercel Postgres Setup

In Vercel project → Storage → Create Database → Postgres
Change prisma/schema.prisma datasource provider from sqlite to postgresql
Connect to project — DATABASE_URL is auto-injected
Redeploy (build runs prisma db push or migrate)

Project Structure

src/
├── app/                  # Next.js App Router pages & API routes
│   ├── api/v1/           # Public REST API (proxy)
│   ├── dashboard/        # Authenticated dashboard
│   ├── docs/             # API documentation
│   └── pricing/          # Pricing page
├── components/           # React components
└── lib/                  # Auth, DB, quota, Twitter proxy
prisma/
└── schema.prisma         # Database schema

Roadmap

Stripe billing (Live on production — docs/STRIPE.md)
Real-time WebSocket monitoring
Telegram/Discord notifications
Account pool management
CLI tool
Batch DM / posting queue (Bull/Redis)

Legal Notice

This project interacts with X/Twitter data. Ensure compliance with X Developer Agreement and applicable laws. Use official APIs when possible.

License

MIT