# 🎰 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