> For the complete documentation index, see [llms.txt](https://docs.fast.poker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fast.poker/integrations/frontend-integration.md). # Frontend integration Use this guide if you want to build a custom Fast Poker frontend, room, league client, white-label app, or player experience. A frontend is a wallet-facing interface to the protocol. It helps users discover tables, build transactions, sign with their wallet, read live state, and view history. It is not the custody layer. Reference source: `https://github.com/FastPoker/frontend` ## Choose your starting point | Path | Best for | Tradeoff | | ----------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Use the reference app as a behavior guide | Fastest way to understand expected player flows. | You still need to build and maintain your own client. | | Build your own frontend | Custom room UX, custom routing, custom app stack. | You must implement wallet flows, table reads, transaction builders, TEE auth, and optional indexer wiring. | | Static LIGHT app | Minimal hosting and no server process. | Users need a capable browser RPC for some reads; no server route helpers. | | Node server app | Hosted RPC proxy, route helpers, relay APIs, and easier operator control. | You operate a server and keep server-side secrets safe. | | FULL mode | Full read UX with profiles, stats, history, leaderboards, and live push. | Requires a separate indexer, MongoDB, and dedicated RPC. | The released source frontend is a complete wallet-facing example that can be run as-is, forked, rebranded, or used as the base for a custom room. It is still only the frontend layer: player actions are wallet-signed protocol transactions, and FULL indexed screens require an operator-run indexer. ## What a frontend must do | Job | Notes | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Connect a wallet | Wallet pubkey is the player identity. Self-custody wallets and embedded wallets are both possible. | | Read protocol state | Read table accounts, SNG pools, token registry data, balances, rewards, and player state from Solana or an indexer. | | Build player transactions | Player actions that affect custody or settlement must be signed by the player's wallet. | | Request card access | Private card reads use scoped TEE authorization from the player's wallet. | | Show safe status | Distinguish pending, delegated, settled, and claimable states clearly. | | Explain current SNG rules | Disclose classic native HU versus 6/9-max Flat Bounty, points, 50/50 SOL split, maturity, and scheduled duels before buy-in. | | Render sidecars | Read `SngDuelState`, governed jackpot odds, emission snapshot/config, and record-backed settlement state. | | Handle fallbacks | An indexer or frontend API can be unavailable; the protocol state still exists on Solana. | ## Read sources Use the narrowest source that fits the screen: | Data | Preferred source | | --------------------------------- | ------------------------------------------------------------------------ | | Funds, vaults, settlement, claims | Solana accounts and transaction results. | | Active table state | Solana L1 plus ER/TEE state where applicable. | | SNG pool counts | Indexer or direct Solana reads. | | Hand history and reports | Indexer for UX; verify commitments against on-chain reports when needed. | | Profiles, XP, stats, leaderboards | On-chain player state plus an operator-run indexer. | | Token metadata | Token registry, token metadata services, and trusted local fallbacks. | The frontend should never treat an indexer response as final proof of funds. ## Write flows Frontend writes are wallet-signed protocol interactions. Examples include: * Join an SNG pool. * Submit PLAY/NEXT CARDS through `sng_duel_action` with the registered session signer. * Claim Player `claimable_sol` separately from Claim All/refinement of Raw $FP. * Play hand actions through the active gameplay flow. * Claim, leave, or cash out when the protocol state allows it. New cash-table creation, deposits, seats, top-ups, tips, and hands are retired. A current frontend may expose only recovery and close controls for legacy cash state. Server routes can help prepare transactions or relay operator-side helper work, but they must not custody player funds or sign as the player wallet. ## Optional frontend fees A frontend may add its own clearly-disclosed operator fee on top of an entry transaction. In the released template this is controlled with frontend env fields such as: ```bash NEXT_PUBLIC_OPERATOR_FEE_WALLET= NEXT_PUBLIC_SNG_FEE_BPS=100 NEXT_PUBLIC_SNG_FEE_FLAT_SOL= NEXT_PUBLIC_OPERATOR_FEE_CAP_SOL= ``` Leave the wallet blank to disable. This kind of fee is a frontend-added SOL transfer shown in the entry UI. It is separate from protocol buy-ins, prize pools, rake, settlement, and custody. Builders should disclose it clearly and avoid presenting it as part of the on-chain game rules. ## TEE card access Hole cards are private during a hand. A frontend should request scoped access for the connected wallet so the TEE can return only the cards that wallet is allowed to see. This authorization should be narrow and session-oriented. It is not a seed phrase, not a custody permission, and not a reason to ask the user for arbitrary wallet-connect signatures. ## RPC and hosting modes | Mode | RPC model | | ------------ | ------------------------------------------------------------------------------------ | | Static LIGHT | Browser talks directly to a public or user-provided RPC. | | Hosted Node | Browser can use a same-origin `/rpc` proxy backed by the operator's server-side RPC. | | FULL | Frontend uses hosted Node routes plus an indexer for read-heavy screens. | For a public hosted app, do not bake private provider keys into browser-visible environment variables. Put provider keys on the server and expose only safe same-origin routes or browser-safe URLs. A free Helius key can be useful for local frontend smoke testing. It should not be presented as a production FULL setup: the free tier has low RPC limits and standard LaserStream WebSocket methods, but not mainnet LaserStream gRPC for the current public indexer stream adapter. If a hosted frontend uses a seeded or non-streaming indexer, delegated table occupancy should be confirmed from TEE state before showing it as live player count. ## Indexer wiring FULL read surfaces should use an indexer only when the operator explicitly enables it. A typical frontend/indexer wiring looks like: ```bash NEXT_PUBLIC_ENABLE_INDEXER=true INDEXER_BASE_URL=http://localhost:3001 NEXT_PUBLIC_INDEXER_WS_URL=ws://localhost:3001/ws ``` `INDEXER_BASE_URL` is server-side. `NEXT_PUBLIC_INDEXER_WS_URL` must be reachable from the user's browser if you want live push. ## Rebranding and legal copy If you build a custom frontend, replace or avoid protected brand assets, terms, privacy copy, consent copy, and any room-specific support links before publishing. The Fast Poker name and marks remain protected. ## Builder checklist * Do not feature-gate Flat Bounty for 6-max/9-max; it is the canonical live ruleset. * Show fractional points, Bounty Bank value, maturity, active-duel deadline/round/stake, and a paused blind clock from chain state. * Label Royal 1-in-2,500 only as the current Gold 9-max anchor and calculate/display the current cell odds. * Keep per-game settlement deltas separate from cumulative wallet claimable balances. * Decide whether you are following the reference app behavior or building a different player flow from scratch. * Decide whether your app is static, Node-hosted, or FULL with an indexer. * Choose browser RPC and server RPC boundaries. * Keep player transactions wallet-signed. * Use scoped TEE card authorization for private cards. * Treat Solana accounts as the source of truth. * Use an indexer for speed, history, and profiles, not for custody. * Rebrand before public launch.