A fully on-chain Fantasy World Cup on X Layer. AI agents auto-manage your squad of national-team Player NFTs from live match stats, scoring streams through an on-chain oracle, and winnings pay out in OKB with a one-tap swap to stablecoins via OKX DEX — all from your OKX Wallet.

Built for the OKX X Cup Hackathon (World Cup theme · X Layer). Tracks: GameFi + AI Agent + NFT.

OkxBall is live on X Layer testnet (chainId 1952). Deployed + a full matchday verified on-chain (mint → join → submitLineup → reportPoints → lock → settle → claim).

Full matchday lifecycle on league #2 (every step a verified tx on OKLink): createLeague · mint · mint · join · submitLineup · reportPoints · lock · settle · claim

The app's live flow targets league #3 — open and empty, ready for a connected wallet to join + submit on camera (NEXT_PUBLIC_LEAGUE_ID=3).

Mainnet (196): run pnpm deploy:mainnet before submission. The app reads the live addresses from packages/shared/src/deployments.json and auto-flips Demo → Live.

Network: X Layer is a Polygon CDK zkEVM; gas token OKB. Mainnet chainId 196, testnet chainId 1952 ("terigon"). See apps/contracts/DEPLOY.md.

1. Land on the 3D stadium → "Fantasy World Cup, run by AI agents, on X Layer."
2. /players → mint + train an NFT → OKX Wallet signs → rating/level rise on-chain.
3. /agent → type a strategy → watch the LLM stream its reasoning → recommended XI.
4. One click → join + submit your owned NFTs → tx confirmed on OKLink. (the money shot)
5. /live → operator settles the gameweek → claim OKB → swap to USDC via OKX DEX.

Full beat sheet + submission checklist: DEMO.md.

okxball/
├── apps/web/                  # @okxball/web — Next.js 14, wagmi/viem, R3F 3D, agent route
│   ├── app/                   # routes + /api/agent (RunPod LLM) + /api/dex/* (OKX DEX)
│   ├── components/three/      # Scene3D, StadiumHero, Pitch3D, PlayerCard3D, MatchdayScene
│   └── lib/
│       ├── onchain.ts         # wagmi write/read hooks (mint/train/join/submit/claim)
│       ├── okx/               # OKX DEX aggregator client (HMAC-signed) + payout helper
│       └── agents/engine.ts   # deterministic heuristic (agent fallback + scoring math)
├── apps/contracts/            # @okxball/contracts — Hardhat + OpenZeppelin 5.0.2 (Solidity 0.8.24)
│   ├── contracts/             # PlayerNFT · ScoringOracle · FantasyLeague · PayoutVault
│   ├── scripts/deploy.ts      # deploys, wires perms, auto-writes addresses to the app
│   └── test/fantasy.test.ts   # end-to-end league flow (mint→…→claim)
└── packages/shared/           # @okxball/shared — chains (correct 1952!), ABIs, addresses, constants

The deploy writes addresses into @okxball/shared, which both the app and contracts read — one source of truth, no copy-paste drift.

pnpm install          # workspace install (root)
pnpm web              # http://localhost:3000  — full app (Demo mode until deployed)
pnpm test             # contracts: end-to-end league test
pnpm build            # build everything via turbo

Connect with OKX Wallet (auto-switches to X Layer). Every page shows a Demo / Live badge; it flips to Live automatically once contracts are deployed.

# 1) get test OKB: https://web3.okx.com/xlayer/faucet  (or https://www.l2faucet.com/x-layer)
# 2) apps/contracts/.env  ->  PRIVATE_KEY=...   OKLINK_API_KEY=...
pnpm deploy:testnet   # chainId 1952  (or pnpm deploy:mainnet -> 196)

Then run the printed okverify commands to verify on OKLink. Full runbook: apps/contracts/DEPLOY.md.

Seed a demo matchday (self-contained proof, real txns): pnpm --filter @okxball/contracts seed:testnet — creates a fresh league, then mints, joins, submits, reports oracle points, locks, settles (50/30/20) and claims, printing an OKLink link per step.

For a live on-camera demo (a connected wallet really plays):

pnpm --filter @okxball/contracts open-league:testnet   # opens a fresh league, writes NEXT_PUBLIC_LEAGUE_ID
# … in the app: connect wallet → /players mint → /agent → join + submit (real txns) …
LEAGUE_ID=<id> pnpm --filter @okxball/contracts settle:testnet   # operator scores + settles so winners can claim

• AI_BASE_URL / AI_MODEL — point the agent at your own OpenAI-compatible LLM (defaults to a live RunPod Qwen3-VL endpoint; AI_API_KEY optional). Heuristic fallback if unreachable.
• NEXT_PUBLIC_LEAGUE_ID — the league the app joins/submits/claims against (set by the open-league script).
• OKX_DEX_API_KEY / _SECRET_KEY / _PASSPHRASE / _PROJECT_ID — enables the DEX REST payout swap.
• NEXT_PUBLIC_PAYOUT_TOKEN_ADDRESS — stablecoin to pre-select in the swap widget.

• OKX Wallet — injected EIP-1193 connector, auto network-switch.
• OKX DEX — embedded @okxweb3/dex-widget swap (X Layer) + server-side aggregator REST (/api/dex/quote|swap, HMAC-signed) for "claim → stablecoin".
• OKLink — contract verification via @okxweb3/hardhat-explorer-verify.
• OKB — native gas + mint/train/entry/prize currency end-to-end.

Fantasy sports is a massive, proven retention market; the NFT-training loop + matchday cadence + instant payouts is a credible on-chain wedge, and matchdays create spiky real-time load that suits X Layer's throughput. OKX Wallet + OKB make the on-ramp seamless.

Honesty note: demo player/fixture/leaderboard data is illustrative seed data, and the agent reasons over that on-screen squad — but the on-chain submit uses the wallet's own minted NFTs (read live from chain), since submitLineup requires ownerOf == you. The contracts, wallet integration, RunPod LLM agent, OKX DEX wiring, and X Layer config are real; the app gates real transactions behind a deployment check and shows a Demo/Live badge so nothing is misrepresented.