io.github.csacanam/lotero
Provably fair on-chain slot machine for AI agents: x402 spins on Base, Chainlink VRF results.
Open source Open in the app JSON README (API)
About
Provably fair on-chain slot machine for AI agents: x402 spins on Base, Chainlink VRF results.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- csacanam
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Forks
- 1
- Last push
- 2026-07-12T11:40:46Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:38
- Updated
- 2026-08-29 03:02:38
- Origin id
io.github.csacanam/lotero
README
# 🎰 Lotero **A Provably Fair Casino for AI Agents** A provably fair, on-chain slot machine with Chainlink VRF 2.5. Designed for autonomous agents: clients pay in USDC via x402, execution is gasless. ## Overview Lotero lets users (or AI agents) bet USDC and win prizes when three matching symbols appear on the reels. The game uses **Chainlink VRF 2.5** for provably fair randomness. - **RTP ~93%** — [DOCS/RTP_MODEL.md](DOCS/RTP_MODEL.md) - **Max win: 30×** — Bet 1 USDC, win up to 30 USDC (three BTC) - **Symbols** — DOGE 5×, BNB 14×, ETH 20×, BTC 30× - **Referral** — 1% commission on referred players' bets - **Dev fee** — 5% of each bet to the team > ⚠️ **Frontend in development** — The web app in `packages/frontend` is incomplete. The contracts and agent are production-ready. --- ## Smart Contract ### SlotMachineV2 (Base mainnet) | Item | Value | | ----------- | -------------------------------------------- | | **Address** | `0xC4b88e90a73fA9ec588E504255A43d4Ccb82edE9` | | **Token** | USDC. Bet 1 USDC, win up to 30 USDC. | | **VRF** | Chainlink VRF 2.5 | | **Events** | `SpinRequested`, `SpinResolved` | **Core functions** - `playFor(player, referringUserAddress, amountToPlay)` — Pay on behalf of another address; the `player` receives the round, wins, and stats. - `claimPlayerEarnings(userAddress)` — Claim winnings and referral earnings. - `isResolved(requestId)` — Check if a round has been resolved. --- ## Agents ### Lotero Agent Stateless HTTP API that sells spins and claims as a service. Clients pay via x402 (1.1 USDC spin, 0.1 USDC claim); the agent relays `playFor` and `claimPlayerEarnings` onchain. Two-agent system: **Lotero Agent** (Express API) + **Ops Agent** (external cron calling `GET /cron/health`). See [packages/agent/README.md](packages/agent/README.md). - `POST /spinWith1USDC` — Paid (x402). Execute spin for `player`. - `POST /claim` — Paid (x402). Claim player earnings (gasless). - `GET /round?requestId=...`, `GET /player/:address/balances`, `GET /contract/health` — Read-only. - `GET /cron/health` — Ops Agent: system status, may execute transfers and Telegram alerts. ```bash yarn agent # Start agent yarn agent:dev # Dev with watch ``` **Documentation:** [DOCS/AGENT_FLOWS.md](DOCS/AGENT_FLOWS.md) | [DOCS/AGENT_API.md](DOCS/AGENT_API.md) **For AI agents:** - **MCP server** ([`lotero-mcp`](mcp/) on npm, listed on the official [Model Context Protocol registry](https://registry.modelcontextprotocol.io) as `io.github.csacanam/lotero`): exposes 5 MCP tools over stdio — `spin` (paid via x402), `get_round`, `get_balances`, `claim` and `get_contract_health` — built with the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), with an **enforced session spin limit** as a responsible-gambling guardrail. Install: ```bash claude mcp add lotero -- npx -y lotero-mcp ``` See [`mcp/README.md`](mcp/README.md) for configuration and tool reference. - **Agent skill**: `npx skills add csacanam/lotero-core` (or read it at [lotero.xyz/skill.md](https://lotero.xyz/skill.md)) — wallet setup, x402 spin/poll/claim flow, payouts, budget guardrails. - **LLM index**: [lotero.xyz/llms.txt](https://lotero.xyz/llms.txt). --- ## Project Structure ``` packages/ ├── agent/ # Lotero Agent — x402 + onchain relay ├── contracts/ # Smart contracts, tests, deploy scripts │ ├── contracts/ SlotMachine.sol, SlotMachineV2.sol │ ├── deploy/ │ └── test/ └── frontend/ # Web app (in development) ``` --- ## Documentation | Doc | Description | | ------------------------------------------ | ---------------------------------------- | | [DOCS/AGENT_FLOWS.md](DOCS/AGENT_FLOWS.md) | Flow diagrams (cron health, spin, claim) | | [DOCS/AGENT_API.md](DOCS/AGENT_API.md) | API reference, endpoints, env, constants | | [DOCS/DEPLOY_BASE.md](DOCS/DEPLOY_BASE.md) | Deploy contracts to Base | | [DOCS/RTP_MODEL.md](DOCS/RTP_MODEL.md) | RTP math and reel layout | --- ## Requirements - [Node.js](https://nodejs.org/) v18+ - [Yarn](https://yarnpkg.com/) - [Git](https://git.scm.com/) --- ## Quick Start **1. Install dependencies** ```bash git clone https://github.com/csacanam/lotero-core.git cd lotero-core yarn install ``` **2. Run local chain** ```bash yarn chain ``` **3. Deploy contracts** (new terminal) ```bash yarn deploy ``` **4. Run tests** ```bash yarn contracts:test ``` **5. Start the frontend** (optional, in development) ```bash yarn start ``` App runs at `http://localhost:3000`. --- ## Production For Base mainnet: see [DOCS/DEPLOY_BASE.md](DOCS/DEPLOY_BASE.md). Contract address above. Fund the VRF subscription with LINK. --- ## License MIT