Documentation

Prediction protocol concepts, match markets, settlement, $WCHUB token model, and Solana programs for the WorldCup Hub 2026 tournament app.

Introduction

WorldCup Hub is a fan-owned prediction layer for the 2026 FIFA World Cup, built on Solana. Fans pick match outcomes before kickoff, lock their position on-chain, and earn $WCHUB utility reward eligibility when results settle. Every prediction has a countdown, every settled result is verifiable.

Quick Start

Three ways to interact with the protocol.

Fan / Predictor · connect a Solana wallet and pick matches:

# 1. Open https://worldcuphub.app/dashboard
# 2. Connect Phantom wallet (or Solflare)
# 3. Browse open match markets  ·  each card shows kickoff countdown
# 4. Pick a side, confirm the transaction before the lock window closes
# 5. After the final whistle, settlement runs and $WCHUB eligibility is computed

Country token holder · track token momentum alongside fixtures:

# 1. Visit https://worldcuphub.app/dashboard (Squad Board tab)
# 2. See live price, 24h move, and volume for Brazil, France, Argentina, England and more
# 3. DexScreener pairs refresh live where on-chain liquidity exists
# 4. Country token context sits next to the fixture list  ·  no switching tabs needed

Developer · run the stack locally:

git clone https://github.com/worldcuphub/worldcuphub-app
cd worldcuphub-app
pnpm install
cp .env.example .env.local   # add Supabase URL, anon key, RPC endpoint
npx serve cloner_2.5/pages/axonmed.app   # static frontend on :3000

Architecture

WorldCup Hub is a static-first frontend enhanced with injected vanilla JS and a Supabase back-end.

Frontend (static HTML / CSS / Vanilla JS)
  index.html              Landing page
  dashboard.html          Prediction Hub  ·  sidebar, iframe shell, analytics
  matches/index.html      72-match fixture board (embeddable iframe)
  inject/
    dashboard-predict.js  Tab routing, analytics, remote bet fetch

Backend (Supabase)
  prediction_bets         Table  ·  wallet, match_id, side, stake, odds, payout
  RLS policies            Row-level security: wallet = auth.uid()

On-chain (Solana)
  $WCHUB SPL token         Utility token  ·  reward eligibility after settlement
  Memo program            Settlement anchoring (planned v0.2)

Edge
  Vercel                  Static deploy + Cloudflare geofence worker

How it works

The full prediction lifecycle from fixture listing to reward eligibility:

1. 1. Fixture seeding. The 72 group-stage matches are seeded from the official FIFA 2026 schedule. Each match record includes home_team, away_team, kickoff_at (UTC), and group identifier.
2. 2. Market open. When a fixture is seeded, its prediction market opens. The lock window closes at kickoff · no picks are accepted after the countdown reaches zero.
3. 3. Prediction submission. The fan connects Phantom, picks a side (Home / Draw / Away), and submits. The pick is written to prediction_bets with a Solana wallet signature as the proof of identity. A Supabase RLS policy ensures only the owning wallet can read its own rows.
4. 4. Settlement. After the final whistle, the result oracle writes the outcome to match_results. A settlement job marks winning picks and computes potential_payout based on the odds locked at submission time.
5. 5. $WCHUB eligibility. Wallets with winning settled picks enter the reward eligibility queue. $WCHUB distribution is utility-only and subject to the protocol's geofencing and compliance rules.

Match markets

Each of the 72 group-stage fixtures gets its own prediction market. Knockout markets are planned for v0.2.

{
  "wallet": "7xKX...mW3q",
  "match_id": "WC2026-GRP-A-01",
  "match_title": "France vs Cape Verde",
  "kickoff_at": "2026-06-11T20:00:00Z",
  "side": "home",
  "side_label": "France",
  "stake_usdc": 10.00,
  "odds": 1.65,
  "potential_payout": 16.50,
  "settlement_asset": "usdc",
  "status": "pending",
  "tx_signature": "4mXP...9rFz"
}

Market sides at v0.1: home (home team win), draw, away (away team win). Odds are fixed at lock time and cannot change after submission.

Settlement

Settlement happens after the match result is confirmed by the oracle.

1. 1. Result oracle · posts the verified full-time result to match_results with a source attestation (FIFA data feed).
2. 2. Settlement job · reads all pending picks for the match, marks winners as won and losers as lost, computes payout = stake × odds for winners.
3. 3. Payout queue · winning wallets are queued. USDC payouts release from the protocol escrow account. SOL-denominated picks settle in SOL.
4. 4. On-chain anchor (v0.2) · settlement batch hash will be committed to Solana via the Memo program for public verifiability.

Leaderboard

The leaderboard ranks wallets by prediction accuracy across the group stage.

Score is computed as: wins / total_settled_picks. Wallets with the same win-rate are ranked by total stake volume. The leaderboard is public · any wallet address can be looked up. Scores update in real time as matches settle.

Leaderboard tiers (planned v0.2): Bronze (≥ 40% accuracy, ≥ 5 picks), Silver (≥ 55%, ≥ 10 picks), Gold (≥ 65%, ≥ 20 picks). Tier determines $WCHUB reward multiplier.

$WCHUB Utility

$WCHUB is the Solana SPL utility token for WorldCup Hub. It is not a financial instrument or security.

Protocol uses:

• · Reward eligibility for winning settled predictions
• · Leaderboard tier bonuses (v0.2)
• · Access to early match markets before public release (v0.3)
• · Governance participation in future protocol parameter votes (v1.0)

Reward eligibility

Winning predictions enter the $WCHUB reward eligibility pool after settlement confirms.

- Prediction was submitted before the lock window closed
- Pick was settled as "won" by the result oracle
- Wallet is not in a geofenced jurisdiction
- Wallet has not violated fair-play rules (one pick per market per wallet)
- $WCHUB distribution: computed proportionally to (stake × odds) across the winning pool

What $WCHUB is not

Important limitations and disclaimers.

• · Not a security or investment. $WCHUB has no guaranteed returns and no equity in WorldCup Hub.
• · Not gambling winnings. Predictions are protocol interactions. Payouts are utility distributions, not wagering prizes.
• · Not financial advice. Nothing in this documentation constitutes financial, legal, or tax advice.
• · Not available in restricted regions. The Cloudflare edge worker blocks access from geofenced jurisdictions before any protocol interaction.

Wallet auth

WorldCup Hub uses Phantom (and Solflare) wallet signatures for identity · no email, no password, no account creation.

Auth flow: the user clicks Connect, signs a nonce with their wallet, the server verifies the signature and returns a Supabase JWT scoped to wallet = <public_key>. All RLS policies enforce this scope · no wallet can read or write another wallet's predictions.

Lock window

Every match market has a hard close at kickoff. No prediction is accepted after the countdown reaches zero.

The server validates kickoff_at > NOW() on every prediction insert. Late picks are rejected with HTTP 409. The client-side countdown timer is informational only · the server enforces the cut-off independently.

Geofencing

Certain jurisdictions are blocked at the Cloudflare edge before any protocol interaction is possible.

The geofence worker reads CF-IPCountry at the edge and returns HTTP 451 for restricted regions. The list of restricted regions is reviewed by counsel and updated as regulatory requirements change. Users in restricted regions cannot access the prediction interface regardless of VPN claims · on-chain transaction validation also checks the submission IP.

API · Matches

Public read-only endpoint. No auth required.

GET /rest/v1/matches?select=id,home_team,away_team,kickoff_at,group,status
    &order=kickoff_at.asc
    &status=eq.open

Response 200:
[{ "id": "WC2026-GRP-A-01", "home_team": "France", "away_team": "Cape Verde",
   "kickoff_at": "2026-06-11T20:00:00Z", "group": "A", "status": "open" }]

API · Predictions

Authenticated. Requires wallet JWT in Authorization header.

# Read own predictions
GET /rest/v1/prediction_bets
    ?select=wallet,match_id,match_title,kickoff_at,side,side_label,
            stake_usdc,odds,potential_payout,status,created_at
    &wallet=eq.{wallet}
    &order=created_at.desc
Authorization: Bearer {supabase_jwt}

# Submit a prediction (before kickoff)
POST /rest/v1/prediction_bets
Authorization: Bearer {supabase_jwt}
Content-Type: application/json
{ "match_id": "WC2026-GRP-A-01", "side": "home",
  "stake_usdc": 10, "tx_signature": "4mXP...9rFz" }

API · Leaderboard

Public read-only. Returns top wallets by accuracy across settled picks.

GET /rest/v1/leaderboard?select=wallet,wins,total,accuracy,total_stake
    &order=accuracy.desc,total_stake.desc
    &limit=100

Response 200:
[{ "wallet": "7xKX...mW3q", "wins": 14, "total": 20,
   "accuracy": 0.70, "total_stake": 240.00 }]

Links

• → Dashboard · Prediction Hub, Portfolio, Leaderboard
• → Match board · All 72 group-stage fixtures
• → Privacy Policy
• → Terms of Service

Security disclosure

WorldCup Hub is experimental software. Do not submit more than you are prepared to lose.

To report a vulnerability, email security@useworldcuphub.app with a description and reproduction steps. We aim to respond within 48 hours. Please do not disclose publicly until we have had a chance to patch.