Fantasy football meets Solana. Users build squads of real Premier League players, pay USDC to enter matchweek contests, and earn points based on actual match results. Top finishers split the prize pool via on-chain payouts.
This repo is the backend API server. It handles player data, contest management, scoring, AI-assisted squad building, and autonomous agent entries — all backed by a Solana Anchor program for USDC escrow.
Client (Next.js + Privy)
↕ REST API
Express Server
├── PostgreSQL (PgTyped — typed SQL, no ORM)
├── API-Football (teams, players, fixtures, match stats)
├── Claude API (squad assistant + autonomous agent)
└── Solana/Anchor (USDC entry fees, prize distribution, agent vaults)
Key design decision: PgTyped over Prisma. Queries are written as raw SQL in .sql files. PgTyped introspects them against the real database schema and generates TypeScript interfaces. The result is full type safety with zero abstraction — every query is visible, optimizable, and does exactly what it says.
Contest lifecycle — Create a contest tied to a real matchweek. Link fixtures automatically. Lock entries at deadline. After matches complete, pull player stats from API-Football, calculate fantasy points, rank entries, and settle prizes on-chain. The full pipeline: create → lock → score → settle.
AI Squad Assistant — A conversational agent (Claude API with tool use) that helps users build squads. It has four tools: search players, check recent match stats, get contest details, and validate a proposed squad against salary cap and composition rules. Users chat naturally; the assistant queries the database on their behalf.
Autonomous Agent — Users deposit USDC into a Solana escrow vault and configure spending rules (max per contest, max per week, league preferences). A cron job runs hourly: Claude evaluates open contests, decides which to enter, builds an optimal squad, and triggers on-chain USDC transfers from the user's vault to the contest escrow. Every decision is logged with reasoning. On-chain spending caps are enforced by the Anchor program — the AI proposes, the smart contract disposes.
Scoring engine — Pulls per-player match stats from API-Football after each fixture completes. Calculates fantasy points based on goals, assists, clean sheets, cards, minutes played, and penalty saves. Points are weighted by position — a defender's goal scores more than a forward's, incentivising balanced squad selection.
On-chain integration — A single unified Anchor program (EwTXRAQrnm4BasdA5UCabHqpeodjAES3ok8D4LCg6Xt8) handles contest escrow, prize distribution, agent vaults, and refunds. The backend calls it for admin operations (create, lock, settle, cancel). Users sign entry and agent transactions from the frontend.
| Layer | Tools |
|---|---|
| Runtime | Node.js, TypeScript, Express |
| Database | PostgreSQL, PgTyped |
| Auth | Privy (JWT verification) |
| AI | Claude API (tool use, agentic decision-making) |
| Blockchain | Solana, Anchor, SPL Token (USDC) |
| Data source | API-Football (teams, players, fixtures, stats) |
src/
├── config/ # Env validation (Zod), Solana program client
├── routes/ # Express route handlers
├── services/ # Business logic
│ ├── assistant/ # AI squad assistant (Claude + tools)
│ ├── agent/ # Autonomous contest entry agent
│ ├── scoring.ts # Fantasy points calculator
│ ├── sync.service.ts # API-Football data sync
│ └── contest-lifecycle.service.ts # Full contest pipeline
├── queries/ # PgTyped SQL files + generated types
├── solana/ # Anchor program client, PDA helpers
├── middleware/ # Auth (Privy JWT), error handling, async wrapper
├── lib/ # DB pool, API-Football client, Privy client, cron
├── idl/ # Anchor program IDL
├── types/ # Anchor-generated TypeScript types
└── scripts/ # Seed scripts, test scripts
migrations/ # Raw SQL schema migrations
REST API with public, authenticated (Privy JWT), and admin (API key) tiers — covers the full contest lifecycle, player and entry management, AI assistant chat, and agent configuration.
Prerequisites: Node.js 18+, PostgreSQL 14+, funded Solana devnet wallet.
Keys required (see .env.example):
DATABASE_URL=
API_FOOTBALL_KEY=
ANTHROPIC_API_KEY=
HELIUS_API_KEY=
ADMIN_KEYPAIR_JSON=
AGENT_KEYPAIR_JSON=
ADMIN_API_KEY=
PRIVY_APP_ID=
PRIVY_APP_SECRET=Install and run:
npm install
npm run generate # Generate PgTyped query types (requires DATABASE_URL)
npm run devSeed Premier League data:
npm run seed -- --league=39 --season=2024Pulls ~20 teams, ~700 players, and ~380 fixtures from API-Football. Takes 10–15 minutes due to API rate limits.
Program ID: EwTXRAQrnm4BasdA5UCabHqpeodjAES3ok8D4LCg6Xt8 (devnet)
The Anchor program handles all USDC flows: contest escrow, prize distribution to winners, agent vaults with on-chain spending caps, and refunds on cancellation. The program source lives in a separate repo — the IDL and generated types are committed here for the backend client.
- squadxi-escrow — Solana Anchor program
- squadxi-web — Next.js frontend