XFlux

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 池化连接）时

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

本地开发用 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:

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

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

Deploy to Vercel

Option A: Vercel CLI

npm i -g vercel
vercel login
vercel

Option B: GitHub Integration

1. Push to GitHub:

   bash

   Copy

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

2. Import project at vercel.com/new

3. 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

4. After first deploy, run database migration:

   Terminal

   Copy

   npx prisma db push
   

   Or add a build step with Vercel Postgres integration.

Vercel Postgres Setup

1. In Vercel project → Storage → Create Database → Postgres
2. Change prisma/schema.prisma datasource provider from sqlite to postgresql
3. Connect to project — DATABASE_URL is auto-injected
4. 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