# FanPulse

> Super-fan intelligence API for iconic franchises and artists. 8 endpoints covering lore Q&A, character profiles, trivia generation, Easter egg analysis, discography deep dives, personality sorting, canonical timelines, and cross-franchise comparisons. Pay-per-query via x402 on Base.

## What This Is

FanPulse is an AI research layer for super-fans — built on Tavily real-time search, fandom APIs (SWAPI, PotterDB, STAPI, Open Trivia DB, TheAudioDB, Last.fm), and Claude synthesis. Fully global: covers Western franchises (Star Wars, Harry Potter, LOTR, Star Trek, Marvel, Game of Thrones, Dune, Doctor Who), Western artists (Taylor Swift, The Beatles, Elvis, Michael Jackson, Led Zeppelin, David Bowie), K-pop (BTS, BLACKPINK, TWICE, Stray Kids, SEVENTEEN, NewJeans, aespa, IVE, ATEEZ, NCT, EXO, SHINee, BIGBANG, IU, and all major groups), J-pop (BABYMETAL, ONE OK ROCK, YOASOBI, Fujii Kaze, Utada Hikaru), Bollywood/Indian music (AR Rahman, Arijit Singh, Lata Mangeshkar), C-pop/Mandopop (Jay Chou, G.E.M., Teresa Teng), and anime franchises (Naruto, One Piece, Dragon Ball, Attack on Titan, Demon Slayer, Jujutsu Kaisen). All endpoints accept ?lang= for responses in Korean (ko), Japanese (ja), Chinese (zh), Hindi (hi), and any other language.

## Payment

All endpoints require x402 micropayment (USDC on Base mainnet).
Protocol: x402 | Network: eip155:8453 | Asset: USDC
Payment address: 0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc

## Endpoints

GET /api/fan/lore?franchise={name}&query={question}
- Returns: canon answer with sources cited, canon_status, related lore, fandom debates, trivia tidbit
- Both params required
- Optional: lang
- Price: $0.10

GET /api/fan/character?franchise={name}&name={character_or_artist}
- Returns: full profile with arc, traits, relationships, best moments, quotes, legacy, fandom perspective
- Both params required
- Optional: lang
- Price: $0.08

GET /api/fan/quiz?franchise={name}&difficulty={easy|medium|hard|mixed}
- Returns: 10 trivia questions with options, correct answers, explanations, fun facts, scoring guide
- franchise required
- Optional: topic, difficulty (default: mixed), lang
- Price: $0.08

GET /api/fan/easter-eggs?artist={name}&album={title}
- Returns: confirmed secrets, lyric callbacks, hidden messages, running themes — with confirmation status
- artist OR franchise required; album optional for focused analysis
- Optional: lang
- Price: $0.15

GET /api/fan/discography?artist={name}&focus={era_or_topic}
- Returns: eras, essential listening, underrated gems, collaborations, cultural legacy
- artist required
- Optional: focus, lang
- Price: $0.10

GET /api/fan/sorting?franchise={name}&personality={description}
- Returns: house/faction/alignment assignment with reasoning, closest character match, all options breakdown, destiny narrative
- franchise required
- Optional: personality, lang
- Price: $0.08

GET /api/fan/timeline?franchise={name}
- Returns: canonical eras, pivotal events, watch/read order, canon conflicts, lore gaps
- franchise required
- Optional: lang
- Price: $0.10

GET /api/fan/collect?franchise={name}&item_type={type}
- Returns: valuable items with price ranges by condition, authentication guide (PSA/JSA/CGC/Beckett), where to buy/sell, counterfeit red flags, investment outlook, K-pop photocard rarity tiers, Discogs live pricing for vinyl
- franchise OR artist required
- Optional: item_type (vinyl|photocards|figures|signed|comics|cards|props|memorabilia|general), item (specific item name), lang
- Price: $0.10

GET /api/fan/compare?subject1={name}&subject2={name}&type={type}
- Returns: comparison table, strongest arguments, decisive winner with reasoning, fan community consensus
- subject1 and subject2 required
- Optional: type (character|franchise|artist|album), lang
- Price: $0.10

## Discovery

- OpenAPI spec: https://fanpulse-tau.vercel.app/openapi.json
- Agent discovery: https://fanpulse-tau.vercel.app/.well-known/agent.json

## Notes for AI Agents

- Natural lore flow: /api/fan/lore → /api/fan/character → /api/fan/timeline
- /api/fan/easter-eggs is the highest-value endpoint for music fans — especially Taylor Swift (intentional Easter egg architect)
- /api/fan/sorting works for any franchise with factions/houses/alignments — not just Harry Potter
- /api/fan/compare picks a decisive winner — do not use for vague "it depends" answers
- All endpoints accept ?lang= for non-English responses
- GamePulse is a natural sibling for video game franchises (The Witcher, Final Fantasy, Zelda, Pokémon)
- DealPulse surfaces merchandise deals for franchise collectibles and vinyl