An automated social reward system that fetches social posts from X/Twitter, scores them using LLM, and pays users via X402 protocol.
bloom-protocol-social-reward-engine.mp4
- x402 Payments: USDC payouts via Coinbase-hosted facilitator service
- Seamless user onboarding: Reliable service from the Crossmint - Embedded Wallet to enable X/Twitter OAuth login with wallet creation
- LLM Scoring: Quality scoring with AI likelihood detection
- Claim UI: User-facing claim page with wallet management
- Admin Dashboard: Real-time monitoring UI with reward configuration
- X/Twitter Fetcher: Built-in mentions crawler using X API v2
┌─────────────────────────────────────────────────────────────────┐
│ SOCIAL REWARD ENGINE │
│ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ Fetcher │→ │ Scorer │→ │ Rules │→ │ Payout │ │
│ │ */3 min │ │ */5 min │ │ Engine │ │ */10 min │ │
│ └───────────┘ └───────────┘ └───────────┘ └──────────────┘ │
│ ↓ ↓ ↓ ↓ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ MongoDB │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┼───────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │LLM Client │ │ X402 Worker │ │ Admin Panel │ │
│ │ (External)│ │ (Cloudflare) │ │ (Next.js) │ │
│ └───────────┘ └───────────────┘ └───────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ CDP / Base │ │
│ │ Network │ │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ CLAIM FLOW │
│ │
│ User clicks claim link → Claim UI → Login with Twitter │
│ → Crossmint creates wallet → Wallet linked to Twitter ID │
│ → Claim reward → Backend signs EIP-3009 payment │
│ → Worker settles via CDP → USDC sent to user wallet │
└─────────────────────────────────────────────────────────────────┘
Runtime
- Node.js 20+
- MongoDB 8+
API Keys
- X Developer Platform - for fetching mentions
- Coinbase Developer Platform - for X402 payments
- Crossmint - for embedded wallets
LLM scoring is included with a public API key (see .env.example).
Limits: 50 req/min, 1000 req/day. Need more? Request here.
# Clone the repository
git clone https://github.com/cBloomProtocol/social-reward-engine.git
cd social-reward-engine
# Install backend dependencies
npm install
# Install claim UI dependencies
cd claim-ui && npm install && cd ..
# Install admin UI dependencies
cd admin-ui && npm install && cd ..
# Install worker dependencies
cd worker && npm install && cd ..
# Copy environment files
cp .env.example .env
cp claim-ui/.env.example claim-ui/.env.local# Terminal 1: Start MongoDB
docker run -d -p 27017:27017 mongo:8
# Terminal 2: Start backend (port 7200)
npm run start:dev
# Terminal 3: Start claim UI (port 3100)
cd claim-ui && npm run dev
# Terminal 4: Start admin UI (port 7201)
cd admin-ui && npm run dev
# Terminal 5: Start X402 worker (port 8787)
cd worker && npm run devSee .env.example files in each directory for configuration options.
| Component | Config File | Required Keys |
|---|---|---|
| Backend | .env |
MONGODB_URI, X_API_BEARER_TOKEN, LLM_API_KEY, X402_EVM_PRIVATE_KEY |
| Worker | worker/.dev.vars |
CDP_API_KEY_ID, CDP_API_KEY_SECRET |
| Claim UI | claim-ui/.env.local |
NEXT_PUBLIC_CROSSMINT_API_KEY |
Reward settings are managed via Admin Dashboard at http://localhost:7201.
- API Reference - Full endpoint documentation
- User Journey - User claim flow and ops manual
- User receives a claim link:
https://your-domain.com/claim/{tweetId} - User opens the claim page and clicks "Sign in with Twitter"
- Crossmint authenticates user and creates a smart wallet
- Wallet address is linked to user's Twitter ID
- User clicks "Claim Reward"
- Backend creates EIP-3009 TransferWithAuthorization signature
- Worker settles payment via Coinbase hosted x402 facilitator
- USDC is transferred to user's wallet on Base network
social-reward-engine/
├── src/
│ ├── modules/
│ │ ├── admin/ # Admin API endpoints
│ │ ├── config/ # Reward configuration
│ │ ├── fetcher/ # X API crawler
│ │ ├── payout/ # X402 payment client
│ │ ├── pipeline/ # Pipeline orchestration
│ │ ├── posts/ # Posts & claims controller
│ │ ├── scorer/ # LLM scoring
│ │ └── x402/ # Wallet linking service
│ ├── storage/ # MongoDB service
│ └── main.ts
├── admin-ui/ # Next.js admin dashboard
├── claim-ui/ # Next.js user claim page
│ ├── app/claim/ # Claim page route
│ ├── app/wallet/ # Wallet management page
│ └── components/ # Crossmint providers
├── worker/ # Cloudflare Worker for X402
│ └── src/index.ts # CDP payment settlement
├── templates/ # LLM prompt templates
└── docker-compose.yml
MIT License - see LICENSE for details.