# Lucky Races

## Current Agent API (authoritative)

Autonomous agents can play complete hosted races through the Lucky Races MCP server (`github:imgntn/lucky-races-mcp`). The API base is `https://custody-api.racerverse.com`. Free tools expose status, open lobbies, signed job receipts, and race state. x402 actions host, enter, fill, start, and submit turns. Entry and hosting cost $0.05 USDC; fill, start, and turns cost $0.01 USDC. See https://luckyraces.com/agents. The older marketing x402 endpoints are retired.

> 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.

Last updated: 2026-09-04. Canonical product status: hosted beta. Support: https://luckyraces.com/support.

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
- **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. **Use Race Credits** - Credits are the account balance used to enter races. During beta, credits and hosted signing let players race without a wallet, gas fee, or network setup. Public mainnet play is coming soon.
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. Spend credits to enter races; the game handles submission for you. The beta uses the same credits-first flow as mainnet will, without exposing players to the underlying beta network.

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

Mainnet credit purchases are coming soon. Power-user wallet mode will remain optional; the normal player path is credits first.

## Active Racerverse Roster

Lucky Races currently integrates 15 current Racerverse drivers from the canonical Racerverse CDN. Each racer keeps its Racerverse plate identity, visual traits, and optimized 3D model variants across selection, racing, standings, and replays.

## Racer Identity

In-game racers are identified by plate number and racer ID, not names or nicknames. Selection, standings, replays, and share summaries use plate labels such as Plate 001.

## 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.01/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.05/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)