API Reference

The API is organized into route groups, each mounted as a separate Fiber app instance to isolate middleware. This means each group has its own authentication and CORS rules.

Route Groups

flowchart TD
    Root["Fiber App"] --> Health["/healthz\n(Health check)"]
    Root --> Login["/login\n(Authentication)"]
    Root --> Game["/\n(Game routes)"]
    Root --> Public["/public\n(Public data)"]
    Root --> Laravel["/laravel\n(Platform integration)"]
    Root --> MiniGame["/minigames\n(External game API)"]
    Root --> Balloons["/balloons\n(WebSocket game)"]
    Root --> Support["/support\n(Admin)"]
    Root --> PPC["/ppc\n(Marketing)"]
    Root --> Metrics["/metrics\n(Prometheus)"]

Game Routes (/)

The main route group serving the Telegram Mini App. Requires JWT authentication and ensures game state is loaded on every request.

Middleware chain: CORS -> JWT validation -> Session tracking -> Game state loading from Redis

Method	Path	Description
POST	/tap	Register taps (max 50 per request)
GET	/game	Get current game state
GET	/boosters	List available boosters with status
POST	/boosters/activate	Activate a booster
GET	/user/wallets	Get player's wallet info
GET	/user/is-notification-read	Check notification read status
POST	/user/mark-notification-as-read	Mark notification as read
GET	/user/friends-ranking	Paginated friends leaderboard
GET	/quests/	List all quests with status
GET	/quests/friends-quest-progression	Friend invite quest progress
GET	/quests/claim-next-friends-quest-level	Claim friend quest reward
POST	/quests/:questID/start	Start a quest
POST	/quests/:questID/claim	Claim quest reward
GET	/tournaments/	List all tournaments
GET	/tournaments/:tournamentID/prize-pool	Tournament prize pool
GET	/tournaments/:tournamentID/leaderboard	Tournament leaderboard
GET	/tournaments/:tournamentID/requirements	Tournament entry requirements
GET	/toy-box/games/	List minigames
GET	/toy-box/games/:gameID	Minigame details
GET	/toy-box/games/:gameID/tournaments	Tournaments for a game
GET	/toy-box/games/:gameID/iframe	Get JWT token for minigame iframe
GET	/inventory/	Full inventory
GET	/inventory/lucky-funatic	In-game items only
GET	/inventory/platform	Platform-transferable items only
GET	/inventory/special-cards	Forged special cards
GET	/cards/	All cards with ownership status
GET	/cards/most-lucrative-cards	Top earning cards
POST	/cards/buy-card	Buy a new card
POST	/cards/upgrade-card	Upgrade an owned card
GET	/cards/stories	Card story/lore content
GET	/cards/special-cards/:cardID/details	Special card forging requirements
GET	/cards/:cardID	Single card details
GET	/store/items	Store catalog
GET	/store/transactions	Purchase history
GET	/store/transactions/transfers	Platform transfer history
GET	/store/limits	Per-player purchase limits
POST	/store/purchase	Buy a store item
GET	/store/eligibility	Purchase eligibility check
GET	/transfer/items	List transferable items
POST	/transfer/	Transfer items to Funtico Platform
GET	/frenzy/	Frenzy mode status
POST	/frenzy/	Trigger frenzy mode
POST	/popups/convert	Convert Lady/Baby Jokers to Funz
GET	/daily-bonus/	Daily bonus status and streak
POST	/daily-bonus/claim	Claim daily wheel spin
GET	/raffles/:raffleName/requirements	Raffle eligibility status
GET	/earn/banners	Promotional banners
GET	/time-trial	Time trial registration status
POST	/time-trial	Register time trial completion

Login Routes (/login)

Public authentication endpoint. No JWT required.

Middleware: CORS (permissive, all headers allowed)

Method	Path	Description
POST	/	Authenticate via Telegram initData, returns JWT

Public Routes (/public)

Unauthenticated endpoints for publicly visible data.

Middleware: Platform CORS (only funtico.com origins)

Method	Path	Description
GET	/raffles/:raffleID/stats	Raffle statistics (eligible count, total players)

Minigame Routes (/minigames)

External API consumed by minigame clients running in iframes. Uses both API key and JWT authentication.

Middleware: CORS -> API key validation (X-Api-Key header) + JWT from token

Method	Path	Description
POST	/score	Submit minigame score
POST	/play	Start a play session (deducts ticket)
GET	/tournaments	Active tournaments for this game
GET	/player	Player info for minigame context
GET	/player/tickets	Player's ticket balance
GET	/tournaments/history	Past tournaments
GET	/tournaments/:tournamentID	Tournament details
GET	/tournaments/:tournamentID/leaderboard	Tournament leaderboard

Laravel Routes (/laravel)

Server-to-server endpoints called by the Funtico Platform backend. Authenticated via a static bearer token.

Middleware: Bearer token validation against LARAVEL_API_TOKEN

Method	Path	Description
POST	/persist-game-state-change	Persist state change from platform
POST	/transfer/item	Transfer items from platform to player

Balloon Routes (/balloons)

WebSocket endpoint for the real-time balloon pop minigame. Only mounted when the EnableBalloons feature flag is true.

Middleware: CORS -> JWT from query param (?token=) -> WebSocket upgrade check

Method	Path	Description
GET	/ws	WebSocket connection for balloon game

Support Routes (/support)

Admin endpoints for debugging and player support. Gated behind the EnableSupportEndpoints config flag and Basic auth.

Middleware: CORS -> Basic auth -> Action logging

Method	Path	Description
POST	/account/reset	Reset a player's account
POST	/account/funds	Adjust player currency
POST	/account/friends	Modify friend count
POST	/account/notifications/remove	Remove notification
POST	/daily-bonus/reset	Reset daily bonus streak

Marketing Routes (/ppc)

Endpoints for marketing campaign tracking. Authenticated via API key query parameter.

Middleware: CORS -> API key validation (api_key query param)

Method	Path	Description
GET	/tasks/:taskName	Check campaign task completion

Metrics Routes (/metrics)

Prometheus metrics endpoint for monitoring. Uses Basic auth.

Method	Path	Description
GET	/	Prometheus metrics

Health Check

Method	Path	Description
GET	/healthz	Returns 200 OK (no auth)