Provably fair on-chain slot machine for AI agents: x402 spins on Base, Chainlink VRF results.
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.
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.
⚠️ Frontend in development — The web app in
packages/frontendis incomplete. The contracts and agent are production-ready.
| 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.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.
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.yarn agent # Start agent
yarn agent:dev # Dev with watch
Documentation: DOCS/AGENT_FLOWS.md | DOCS/AGENT_API.md
For AI agents:
MCP server (lotero-mcp on npm, listed on the official Model Context Protocol registry 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:
claude mcp add lotero -- npx -y lotero-mcp
See mcp/README.md for configuration and tool reference.
Agent skill: npx skills add csacanam/lotero-core (or read it at lotero.xyz/skill.md) — wallet setup, x402 spin/poll/claim flow, payouts, budget guardrails.
LLM index: lotero.xyz/llms.txt.
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)
| Doc | Description |
|---|---|
| DOCS/AGENT_FLOWS.md | Flow diagrams (cron health, spin, claim) |
| DOCS/AGENT_API.md | API reference, endpoints, env, constants |
| DOCS/DEPLOY_BASE.md | Deploy contracts to Base |
| DOCS/RTP_MODEL.md | RTP math and reel layout |
1. Install dependencies
git clone https://github.com/csacanam/lotero-core.git
cd lotero-core
yarn install
2. Run local chain
yarn chain
3. Deploy contracts (new terminal)
yarn deploy
4. Run tests
yarn contracts:test
5. Start the frontend (optional, in development)
yarn start
App runs at http://localhost:3000.
For Base mainnet: see DOCS/DEPLOY_BASE.md. Contract address above. Fund the VRF subscription with LINK.
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y lotero-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-csacanam-lotero": {
"command": "npx",
"args": [
"-y",
"lotero-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencelotero-mcpnpmio.github.csacanam/lotero works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.