NuroPicks API Reference

Last updated: 2026-04-19

Status: scaffold. Endpoint bodies verified from source 2026-04-19. Requests/responses partially inferred where handlers return NextResponse.json without a typed return. Anything that could not be confirmed from source is marked TBD: verify.

This document covers:

• Next.js web API routes under web/src/app/api/
• Discord bot slash commands under src/bot/commands/
• Webhook endpoints (Whop, NOWPayments) and their signature scheme
• Known rate limits (both web and bot)
• Auth + session model

It does not cover the draft-room Socket.IO protocol (see services/draft-room/) or Python worker HTTP endpoints (internal, cron-only).

Auth and session

The web app currently runs in a hybrid model (Discord bot is still the primary user surface):

• Session cookies: nuropicks_session (opaque id) + nuropicks_discord_id (fallback). Set by the Discord OAuth handshake. web/src/lib/userAuth.ts exposes resolveUserIdentity(), requireUserPage(), requireUserApi(req).
• Header auth: Some routes (notably POST /api/fantasy/deposit) accept x-discord-id + x-nuropicks-auth for bot-to-web calls.
• Admin auth: web/src/lib/adminAuth.ts accepts two signals, in priority:
  1. nuropicks_session cookie whose user has users.is_admin = TRUE (fallback: ADMIN_DISCORD_IDS env allowlist).
  2. x-admin-token header matching ADMIN_REVIEW_TOKEN (legacy, preserved for /admin/fraud and ops curl).
• Webhook auth: HMAC signature per provider. See Webhooks.

Discord bot identifies users by Discord user id only (no separate session). Every command reads interaction.user.id and looks up the profile via src/bot/store.js.

The bot and web share the same Postgres users table. The users.is_admin column referenced in adminAuth.ts is not yet shipped at the schema level. TBD: verify column lands before admin-via-cookie is relied on in prod.

Rate limits

Web (web/src/lib/rateLimit.ts)

In-memory sliding-window bucket keyed by ${key}. checkRateLimit(key, limit, windowMs) returns { ok: true } or { ok: false, retryAfter }. Swap-ready for Redis.

Known per-route limits (sampled from source):

Bot (src/bot/utils/rateLimit.js)

Per-user + per-bucket sliding window. Buckets:

Bot commands currently do not share a centralized rate-limit registry beyond this util; per-command cooldown choice lives in each command file.

External dependency limits

• The Odds API: free tier 500 req/month (documented in .env.example). Bot workers cache aggressively; exact quota enforcement is worker-side and not yet instrumented. TBD: verify quota tracking.
• Discord Gateway: discord.js v14 default rate-limit handling. No custom overrides.
• NOWPayments: no documented per-merchant limit; IPN webhook is idempotent via idempotency_key on ledger_entries.

Web API routes

All routes live under web/src/app/api/ and use Next.js App Router route.ts / route.tsx handlers. Runtime is nodejs with dynamic = "force-dynamic" unless noted.

Public routes

GET /api/health

Liveness + build identity.

Response

{
  "ok": true,
  "service": "nuropicks-web",
  "commit": "abc1234",
  "env": "production",
  "region": "iad1",
  "ts": "2026-04-19T20:00:00.000Z"
}

Headers: Cache-Control: no-store.

POST /api/apply

Capper marketplace application. Public. Rate-limited 3/10min per IP.

Body

{
  "handle": "string",
  "email": "string",
  "specialty": "string",
  "trackRecordUrl": "string",
  "pickCount": "string",
  "startedAt": "string",
  "bankrollStrategy": "string",
  "notes": "string"
}

Required: handle, email, specialty. Email is regex-validated.

Response: { ok: true } or { ok: false, error: string } with 400/429.

Side effect: posts application summary to CAPPER_APPLY_WEBHOOK_URL (Discord relay).

POST /api/fantasy/waitlist

Landing page email capture. Public. Rate-limited 1/60s per IP.

Body

{ "email": "string", "state": "string (optional 2-letter)", "biggest_frustration": "string (optional, <=2000)" }

Duplicate email returns 200 with friendly message (no enumeration).

Response: { ok: true, message: string }. Fire-and-forget Resend confirmation email on new insert.

Other public routes

Shapes partially inferred; see route files for authoritative bodies.

Account (session) routes

Require a valid nuropicks_session cookie. All return 401 if unauthenticated.

GET /api/account/profile

Returns the signed-in user's profile.

Response: { discordId, displayName, username, avatarUrl, email, homeState, timeZone, kycTier, tier, sessionId } (from UserIdentity in lib/userAuth.ts).

PUT /api/account/profile

Update displayName, homeState, timeZone, email. Non-admin users cannot change tier or kycTier.

Body: Partial<{ displayName, email, homeState, timeZone }>.

Response: { ok: true, user: UserIdentity }.

GET /api/account/close + POST /api/account/close

GET returns the pre-close preview (bankroll, open bets, escrow). POST executes the close (soft-delete + self-exclusion).

Response (POST): { ok: true, closedAt: string } (inferred).

GET /api/account/notifications + PUT /api/account/notifications

Notification preferences (email/push/Discord DM). PUT body is a NotificationPrefs struct from lib/notificationPrefs.ts. TBD: verify full shape.

Fantasy (session) routes

All require an identified caller (session cookie or x-discord-id header).

POST /api/fantasy/deposit

Create a league buy-in invoice. Rate-limited 5/10min per user.

Body

{ "leagueId": 123, "amountCents": 2500, "method": "crypto" }

Response

{ "ok": true, "invoiceUrl": "https://...", "escrowId": 456 }

Errors: 401 unauth, 402 RG-blocked (DepositBlockedByRGError), 409 withdrawals halted, 422 validation.

POST /api/fantasy/payout

Request league payout (after season settle / dispute close). TBD: verify exact body - likely { escrowId, walletAddress, currency }.

POST /api/fantasy/ipn

NOTE: This is a webhook endpoint, not user-callable. See Webhooks.

POST /api/fantasy/trade-advisor

Accepts a TradeProposal, returns a Claude-backed TradeAnalysis. Rate-limited 5/min per user-or-ip. Reads + writes to trade_analyses for idempotent replays.

Body: TradeProposal from src/services/ai/types.ts (team rosters + proposed swap).

Response: TradeAnalysis (fairness score + rationale + flags).

Other fantasy advisors (all POST unless noted)

Shapes partially inferred; see route files for authoritative bodies.

Mock-draft + commissioner + draft-token

Commissioner routes require the caller to be the league commissioner; mock-draft and draft-token routes require a session. Body/response shapes inferred; see route files.

KYC, notifications, referrals, creators

Shapes partially inferred; see route files for authoritative bodies.

Admin routes

All admin routes require requireAdminApi(req) to pass. Non-admin returns 403 JSON.

Admin actions generally accept { action, note? }. Response is typically { ok: true, updated: {...} } or { ok: false, error }. See individual route files for exact shape.

Webhooks

All webhook endpoints reject unsigned or invalid-signature requests.

POST /api/webhooks/whop

Whop subscription lifecycle. Signature header: X-Whop-Signature (HMAC-SHA256 of raw body with WHOP_WEBHOOK_SECRET). Events: membership.created, membership.expired, membership.canceled, membership.renewed.

Response: { ok: true } on success, 401 bad sig, 501 not configured.

Idempotency: currently logs + relays to Discord. Tier upsert into DB is TODO(launch).

Also supports GET /api/webhooks/whop for Whop dashboard health-check.

POST /api/webhooks/nowpayments

NOWPayments IPN for crypto subscription payments. Signature header: x-nowpayments-sig (HMAC-SHA512 of canonical-sorted JSON body with NOWPAYMENTS_IPN_SECRET). Statuses: waiting | confirming | confirmed | finished | failed | refunded | expired.

Response: { ok: true } (always 200 after sig verify to prevent retry storms), 401 bad sig, 501 not configured.

Idempotency: downstream credit/upgrade logic is a stub; full idempotency lands with real-money flow at launch.

Also supports GET /api/webhooks/nowpayments for dashboard health-check.

POST /api/fantasy/ipn

NOWPayments IPN for fantasy money flow (league buy-ins). Same signature scheme as above but always returns 200 after signature verification; internal failures surface via reconciliation job. confirmDeposit is idempotent via deterministic idempotency_key on ledger_entries, so duplicate IPNs are no-ops.

The live retail and fantasy IPN endpoints are separate because the domain models diverge (subscription tier vs league escrow); do not merge.

Discord bot slash commands

Commands live in src/bot/commands/. Fantasy subcommands live in src/bot/commands/fantasy/. All commands auto-register via readdirSync walk in src/bot/index.js.

Tiers: free (default), pro, elite, admin. Tier is read from getProfile(userId).tier.

Picks and analysis

Casino + tools

Casino commands (/play game=coinflip/dice/slots/blackjack, /crash, /war, /lottery) each award +5 XP per action; all gated by the casino rate-limit bucket (30/min).

Social

Account

Education + onboarding + draft

Capper follows

Writes through to the capper_follows table (db/schema.sql). Follow set is per Discord user, unique on (discord_id, capper_id). The marketplace + 50/50 rev-share framework lives in docs/CAPPER_AGREEMENT.md.

Example:

/follow-capper capper:glizzysharp
/my-cappers
/unfollow-capper capper:glizzysharp

Fantasy (subcommand group under /fantasy-*)

These are separate top-level commands prefixed fantasy- because Discord limits subcommands per root.

Commissioner-gated commands (fantasy-schedule-draft, dispute-resolve, etc.) check league.commissioner_discord_id === interaction.user.id at command entry.

Example usage

/picks sport:nfl
/bet sport:nba bet:Warriors -4.5 odds:-110 stake:100
/bankroll kelly bankroll:1000 odds:-110 winprob:58
/give user:@mar amount:500
/fantasy-trade league:2026-best-ball proposed-to:@glizzy give:ceedee-lamb get:amon-ra

Unknowns / TBD

• POST /api/fantasy/payout exact body + response not verified from source in this scaffold pass.
• Notification preference struct fields not enumerated here - see lib/notificationPrefs.ts for authoritative shape.
• users.is_admin column does not yet exist in schema; admin-via-cookie path falls back to ADMIN_DISCORD_IDS env allowlist until the column lands.
• Odds API per-worker quota is not instrumented centrally; see workers for per-call caching logic.
• The draft-room Socket.IO protocol is not documented here; see services/draft-room/README.md and src/services/draft/ for the event-sourced actor-per-draft model.
• Command tier enforcement is inconsistent: most commands check interaction.user.id or getProfile(userId).tier inline rather than via middleware. A centralized tier-gate helper is flagged as a P2 cleanup task elsewhere.
• /settle is gated by a staff-role check inside the command, not a global admin middleware. TBD: migrate to shared requireAdmin helper once it exists on the bot side.

See also

• Docs: QUICKSTART.md, ONBOARDING.md, GLOSSARY.md, FAQ.md. Repo root: CONTRIBUTING.md.
• Source of truth for auth + limits: web/src/lib/{adminAuth,userAuth,rateLimit}.ts, src/bot/{utils/rateLimit,store,config}.js.