Hackathon Category: Data in Finance — Financial markets generate vast amounts of data, yet turning that information into meaningful insight remains a challenge. Build a tool using financial data to inform decision-making or identify opportunities.

Trading Arena is a two-player strategy card game where players manage stock portfolios and deploy derivatives (Puts, Calls) to attack opponents and defend their Net Worth. It uses real historical stock data (10 years via Yahoo Finance), Black-Scholes option pricing, and a C++ AI engine — turning financial market analysis into a competitive, strategic experience.

• Overview
• How It Works
• Project Structure
• Installation & Setup
• Running the Game
• Detailed Documentation
• Tech Stack
• Configuration

Players start with £1,000 and compete over 5 rounds, each representing a 3-month market quarter. Every round has three phases:

1. Buy Phase — Purchase stock cards from a randomly generated market.
2. Action Phase — Assign derivative actions (Place, Call, Defense Put, Attack Put) to your holdings and target opponent assets.
3. Battle Phase — Time jumps 3 months forward, stock prices reveal, combat resolves, and Net Worth updates.

The player with the highest Net Worth at the end wins — or knock your opponent to £0 for an early KO.

Options (Call, Put) charge a Black-Scholes premium upfront, deducted from your NW.

The game renders a full analytics dashboard:

• Total Profit — net gain/loss from starting £1,000
• Options Win Rate — percentage of derivatives that produced positive value
• Max Drawdown — peak-to-trough drop in NW
• NW Over Time Chart — line chart tracking portfolio value per round
• AI Strategy Advisor — LLM-powered post-game analysis (Groq or OpenAI)

FintechHack26/
├── app.py                  # Entry point — Flask + SocketIO server
├── requirements.txt        # Python dependencies
├── README.md               # This file
│
├── server/                 # Backend game engine
│   ├── config.py           # Game constants & ticker pool
│   ├── game_state.py       # Global mutable game state
│   ├── game_logic.py       # Round lifecycle & phase transitions
│   ├── events.py           # Socket.IO event handlers
│   ├── combat.py           # Delta & omega calculations
│   ├── cards.py            # Stock card generation & Black-Scholes
│   ├── finance.py          # Financial math (volatility, B-S pricing)
│   ├── stock_data.py       # Yahoo Finance data loader + GBM fallback
│   ├── ai_engine.py        # Python ↔ C++ bridge (ctypes)
│   └── llm_insights.py     # Post-game LLM analysis (Groq/OpenAI)
│
├── backtester/             # Standalone AI backtesting suite
│   ├── engine.cpp          # C++ AI engine & batch simulator
│   └── backtest.py         # Python harness for 10k-game simulations
│
├── templates/
│   └── index.html          # Main game HTML (Jinja2 template)
│
└── static/
    ├── css/
    │   └── styles.css      # Brutalist Bloomberg Terminal aesthetic
    └── js/
        ├── socket.js       # Socket.IO connection & event wiring
        ├── renderer.js     # DOM rendering engine (state → UI)
        ├── actions.js      # UI action dispatchers → socket emits
        ├── analytics.js    # Battle animations, sounds, analytics display
        ├── charts.js       # Chart.js wrappers (stock history, NW chart)
        └── log.js          # Trade log panel utility

• Python 3.10+
• g++ (64-bit) — only needed for the offline AI bot & backtester

git clone <repo-url>
cd FintechHack26
pip install -r requirements.txt

The offline bot uses a compiled C++ heuristic engine. Without it, the bot falls back to random moves.

Windows (MinGW-w64):

# Install a 64-bit compiler if needed:
winget install BrechtSanders.WinLibs.POSIX.UCRT

# Compile (must match Python architecture — typically 64-bit):
cd backtester
x86_64-w64-mingw32-g++ -shared -O2 -o engine.dll engine.cpp

Linux / macOS:

cd backtester
g++ -shared -fPIC -O2 -o engine.so engine.cpp

For AI-powered post-game strategy analysis, set one of these environment variables:

# Groq (free, recommended — uses llama-3.1-8b-instant)
export GROQ_API_KEY=your_key_here

# OR OpenAI (uses gpt-4o-mini)
export OPENAI_API_KEY=your_key_here

python app.py

Open http://localhost:5000 in your browser.

1. Open http://localhost:5000
2. Click "Play vs AI"
3. You are Player 1; the C++ bot plays as Player 2 automatically

Multiplayer uses Socket.IO — both players connect to the same server.

1. Start the server: python app.py
2. Open two browser tabs to http://localhost:5000
3. In both tabs, click "Multiplayer"
4. The first tab becomes Player 1, the second becomes Player 2
5. The game starts once both players are connected

1. Find the host machine's local IP:

   # Windows
   ipconfig     # look for IPv4 Address (e.g. 192.168.1.42)

   # Linux / macOS
   hostname -I

2. Start the server on the host: python app.py
3. On the second device, open http://<host-ip>:5000 (e.g. http://192.168.1.42:5000)
4. Both players click "Multiplayer"
5. Game starts when both are connected

Note: Both devices must be on the same Wi-Fi / network. The server binds to 0.0.0.0:5000, so it accepts connections from any device on the LAN.

To play with someone on a different network, expose port 5000 using one of these methods:

Share the public URL with the other player. Both click "Multiplayer" to start.

Player 1 opens page → clicks "Multiplayer" → enters lobby (waiting...)
Player 2 opens page → clicks "Multiplayer" → joins lobby
                                             → game starts automatically

Both players go through Buy Phase and Action Phase simultaneously. Each phase advances when both players click their ready/confirm button. If one player disconnects, the other is notified via the trade log.

cd backtester
python backtest.py

Runs 10,000 simulated games (AI vs random) and reports win rate, average profit, and max drawdown.

All game constants are in server/config.py: