{
  "markdown": "# 🎰 Lotero\n\n**A Provably Fair Casino for AI Agents**\n\nA provably fair, on-chain slot machine with Chainlink VRF 2.5. Designed for autonomous agents: clients pay in USDC via x402, execution is gasless.\n\n## Overview\n\nLotero 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.\n\n- **RTP ~93%** — [DOCS/RTP_MODEL.md](DOCS/RTP_MODEL.md)\n- **Max win: 30×** — Bet 1 USDC, win up to 30 USDC (three BTC)\n- **Symbols** — DOGE 5×, BNB 14×, ETH 20×, BTC 30×\n- **Referral** — 1% commission on referred players' bets\n- **Dev fee** — 5% of each bet to the team\n\n> ⚠️ **Frontend in development** — The web app in `packages/frontend` is incomplete. The contracts and agent are production-ready.\n\n---\n\n## Smart Contract\n\n### SlotMachineV2 (Base mainnet)\n\n| Item        | Value                                        |\n| ----------- | -------------------------------------------- |\n| **Address** | `0xC4b88e90a73fA9ec588E504255A43d4Ccb82edE9` |\n| **Token**   | USDC. Bet 1 USDC, win up to 30 USDC.         |\n| **VRF**     | Chainlink VRF 2.5                            |\n| **Events**  | `SpinRequested`, `SpinResolved`              |\n\n**Core functions**\n\n- `playFor(player, referringUserAddress, amountToPlay)` — Pay on behalf of another address; the `player` receives the round, wins, and stats.\n- `claimPlayerEarnings(userAddress)` — Claim winnings and referral earnings.\n- `isResolved(requestId)` — Check if a round has been resolved.\n\n---\n\n## Agents\n\n### Lotero Agent\n\nStateless 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).\n\n- `POST /spinWith1USDC` — Paid (x402). Execute spin for `player`.\n- `POST /claim` — Paid (x402). Claim player earnings (gasless).\n- `GET /round?requestId=...`, `GET /player/:address/balances`, `GET /contract/health` — Read-only.\n- `GET /cron/health` — Ops Agent: system status, may execute transfers and Telegram alerts.\n\n```bash\nyarn agent        # Start agent\nyarn agent:dev    # Dev with watch\n```\n\n**Documentation:** [DOCS/AGENT_FLOWS.md](DOCS/AGENT_FLOWS.md) | [DOCS/AGENT_API.md](DOCS/AGENT_API.md)\n\n**For AI agents:**\n\n- **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:\n\n  ```bash\n  claude mcp add lotero -- npx -y lotero-mcp\n  ```\n\n  See [`mcp/README.md`](mcp/README.md) for configuration and tool reference.\n\n- **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.\n- **LLM index**: [lotero.xyz/llms.txt](https://lotero.xyz/llms.txt).\n\n---\n\n## Project Structure\n\n```\npackages/\n├── agent/         # Lotero Agent — x402 + onchain relay\n├── contracts/     # Smart contracts, tests, deploy scripts\n│   ├── contracts/   SlotMachine.sol, SlotMachineV2.sol\n│   ├── deploy/\n│   └── test/\n└── frontend/      # Web app (in development)\n```\n\n---\n\n## Documentation\n\n| Doc                                        | Description                              |\n| ------------------------------------------ | ---------------------------------------- |\n| [DOCS/AGENT_FLOWS.md](DOCS/AGENT_FLOWS.md) | Flow diagrams (cron health, spin, claim) |\n| [DOCS/AGENT_API.md](DOCS/AGENT_API.md)     | API reference, endpoints, env, constants |\n| [DOCS/DEPLOY_BASE.md](DOCS/DEPLOY_BASE.md) | Deploy contracts to Base                 |\n| [DOCS/RTP_MODEL.md](DOCS/RTP_MODEL.md)     | RTP math and reel layout                 |\n\n---\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) v18+\n- [Yarn](https://yarnpkg.com/)\n- [Git](https://git.scm.com/)\n\n---\n\n## Quick Start\n\n**1. Install dependencies**\n\n```bash\ngit clone https://github.com/csacanam/lotero-core.git\ncd lotero-core\nyarn install\n```\n\n**2. Run local chain**\n\n```bash\nyarn chain\n```\n\n**3. Deploy contracts** (new terminal)\n\n```bash\nyarn deploy\n```\n\n**4. Run tests**\n\n```bash\nyarn contracts:test\n```\n\n**5. Start the frontend** (optional, in development)\n\n```bash\nyarn start\n```\n\nApp runs at `http://localhost:3000`.\n\n---\n\n## Production\n\nFor Base mainnet: see [DOCS/DEPLOY_BASE.md](DOCS/DEPLOY_BASE.md). Contract address above. Fund the VRF subscription with LINK.\n\n---\n\n## License\n\nMIT\n",
  "bytes": 4880,
  "sha": "ee7e4820e46777eda3fd59b3cd042f038398b4ab7fd7d5cc099f472ae91e73d7",
  "repo_slug": "csacanam/lotero-core",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_csacanam_lotero_b2329347/readme"
}