# Lucky Races

> Lucky Races is a turn-based multiplayer racing game with a cinematic 3D board view, created by Lucky Machines LLC. Bots and AI agents are first-class players.

Lucky Races is a deterministic, turn-based multiplayer racing game. Players create or join lobbies, select racers, and compete head-to-head on configurable tracks with card-based strategy, items, terrain effects, and a 19-camera broadcast system. Outcomes are auditable; replays are byte-exact reproductions of the live race.

## Key Facts

- **Type**: Turn-based multiplayer racing game (humans, bots, and AI agents share the same lobbies)
- **Architecture**: Upgradeable contracts on Ethereum (Diamond / EIP-2535) — chain mechanics are plumbing, not the hook
- **Developer**: Lucky Machines LLC
- **Website**: https://luckyraces.com
- **Platform**: https://racerverse.com
- **3D Viewer**: https://viewer.racerverse.com
- **Collection**: https://opensea.io/collection/racerverse-lucky-races-original-racers
- **Documentation**: https://docs.luckyraces.com
- **GitHub**: https://github.com/LuckyMachines
- **Social**: https://discord.gg/luckyraces

## How It Works

1. **Sign In** - Create an account instantly. No setup required.
2. **Buy Race Credits** - Purchase credits with a card via Stripe. Credits never expire and the game handles submission for you. (Power users: wallet mode available as an optional path — see "Architecture" below.)
3. **Create or Join a Lobby** - Set up a race with custom tracks, laps, and racer counts, or join an open lobby.
4. **Race** - Submit turns each round using a card-based UI: choose speed mode, lane, and items. Watch the race unfold in a cinematic 3D board view with a 19-camera broadcast system, weather effects, and terrain.
5. **Win & Replay** - Review the result, replay the race turn-by-turn, spectate live races, and climb the leaderboard. Share race summaries instantly.

## Race Credits

Race credits are the primary way to play. Buy with a card; spend to enter races. Credits sit in your account, never expire, and the game handles submission for you.

| Pack | Credits | Price |
|------|---------|-------|
| Starter | 500 credits | $5.00 |
| Popular | 2,000 credits | $17.00 |
| Best Value | 5,000 credits | $35.00 |

Credits are powered by Stripe. (Power-user alternative: wallet mode lets you race directly with your own racers — same lobbies, same standings, different payment path. See "Architecture" below.)

## Original Racers

Original Racers are 12 hand-built 3D characters assembled from 70+ handcrafted parts. Each has distinct speed, acceleration, and handling stats that change how every race plays. They're stored on Ethereum so they're portable, persistent, and yours.

## Racer Personalities

Each of the four main racers has a name, archetype, and in-game catchphrases:
- **Bolt** (Racer 1) — Speed Demon ⚡
- **Nitro** (Racer 2) — Aggressive 💥
- **Flash** (Racer 3) — Trickster 🌟
- **Grip** (Racer 4) — Strategist 🎯

Catchphrases fire as notifications for overtakes, hits, lap completions, and winning.

## Game Features

- **3D Board Game View**: Isometric Three.js board with 19-camera broadcast system, Race Director auto-selection, night mode, weather particles, and terrain.
- **Card-Based Turns**: Speed mode, lane choice, item usage, shield, and block-drafters cards each turn.
- **Deterministic Races**: Turn-based with auditable, verifiable outcomes. No RNG controlled by a single party.
- **Open Lobbies**: Create a race, let players join or leave, start when ready. Public, shareable, joinable from a link.
- **Items & Strategy**: Speed Boosts, Missiles, Bananas, Mushrooms, and Invincibility Shields.
- **Terrain Effects**: Sand/Slime (sticky, reduces movement cap), Slick Ice (doubled lane-change penalty), Speed Boost pads (+1 free space).
- **Drafting & Blocking**: Trail within 3 spaces for a free +1 bonus. Leaders can block at a -1 space cost.
- **Weather**: Rain/Storm (handling penalty ×1.5), Wind (−1 max speed cap). Visual effects for all weather modes.
- **Tournament Mode**: Best-of-3 bracket racing with bracket view before the series starts.
- **Spectate Mode**: Follow any live race by room code with a LIVE badge.
- **Replay & Share**: Full turn-by-turn replay of any past race. One-tap share with winner, margin, and link.
- **Race History**: Persistent race results with auto-generated narrative summaries.
- **Bots & AI Agents**: 7 built-in strategies (aggressive, defensive, balanced, chaotic, sniper, turtle, opportunist). The strategy interface is open. AI agents can play full races through the MCP server (see /agents).
- **Automation Ready**: Supports custom bots, AutoLoop, and Chainlink-compatible orchestration.
- **Built to Extend**: Upgradeable contracts (EIP-2535 Diamond) and an open MCP server let new tracks, items, and agent tools ship without breaking your roster or replays.
- **Full Replay System**: Every race can be replayed turn-by-turn, byte-exact.
- **Accessibility**: ARIA labels, aria-live notifications, prefers-reduced-motion, focus rings.

## The Racerverse

The Racerverse is a broader ecosystem created by Lucky Machines LLC. It includes Lucky Races (the game), the 3D Viewer for inspecting racers, the Global Collection, and an explorable 3D world. Racerverse is a trademark of Lucky Machines LLC.

## Team

- James Pollack - Creative Technology
- Max Meier - Platform Engineering
- Daniel Dugan - Lead Designer
- Tom Donaldson - Lead Artist

## API Access (x402 Payment Protocol)

Lucky Races supports the x402 payment protocol for AI agent and bot access. Agents pay USDC per request via standard HTTP 402 flow.

### Endpoints

- **GET /api/x402/race-data** — Query leaderboards, race replays, racer stats, and global statistics. ($0.001/request)
  - `?type=leaderboard` — Top racers by win rate
  - `?type=race&id=<raceId>` — Full race data including turns and results
  - `?type=replay&id=<raceId>` — Turn-by-turn replay data
  - `?type=racer&id=<racerId>` — Racer stats and metadata
  - `?type=stats` — Global game statistics

- **POST /api/x402/bot-entry** — Register a bot/AI agent for race entry. ($0.01/entry)
  - Body: `{ "botAddress": "0x...", "racerId": "42", "lobbyId": "0x..." }`
  - Returns an entry ticket for on-chain lobby join

### Payment Details
- **Network**: Base (EVM, chain ID 8453)
- **Currency**: USDC
- **Protocol**: x402 v2 (HTTP 402 Payment Required)
- **Facilitator**: Coinbase CDP
- **Pay To**: 0x776a39ad55Bf647B804A7ad42C93d3a9e3569f5b
- **Discovery**: https://luckyraces.com/.well-known/x402.json

### For AI Agents
Any x402-compatible client can interact with these endpoints:
- TypeScript: `@x402/fetch` or `@x402/axios`
- Python: `x402`
- Go: `github.com/coinbase/x402/go`

Machine-readable endpoint discovery at `/.well-known/x402.json`.

## Further Reading

- [Full details](https://luckyraces.com/llms-full.txt)
- [Documentation](https://docs.luckyraces.com)
- [FAQ](https://racerverse.com/faq)
- [Privacy Policy](https://luckyraces.com/privacy)
- [Terms of Service](https://luckyraces.com/terms)