Lotero

io.github.csacanamPublished by GitHub account csacanamv0.1.0Updated Oct 24, 2026

Provably fair on-chain slot machine for AI agents: x402 spins on Base, Chainlink VRF results.

VerifiedSTDIODesktop onlyFinanceAI & ML

Overview

AI-generated overview

A local MCP server that lets an AI assistant play a provably fair on-chain slot machine on Base, paying for spins and claims in USDC via x402.

What you can do
Spin the slot machine with USDC, paid through x402 and settled on-chain with Chainlink VRF randomness, under an enforced per-session spin limit (spin). Check a round's resolution status by request ID (get_round). Read a player's balances and earnings (get_balances). Claim winnings and referral earnings gaslessly (claim). Check the contract's health (get_contract_health).
When to use it
For experimenting with an autonomous agent that pays for and plays an on-chain gambling game on Base, or for reading round, balance and contract-health data from the Lotero slot machine.
Requirements
Runs locally via npx as an npm package (Node.js). Needs a dedicated wallet private key in LOTERO_WALLET_PRIVATE_KEY holding USDC on Base for spins and claims, and a player wallet address in LOTERO_PLAYER_ADDRESS. Optional LOTERO_MAX_SPINS_PER_SESSION sets the spin cap (default 10). Network access to Base and the Lotero agent API.
Before you install
This is real-money gambling: spins cost USDC (1.1 USDC per spin, 0.1 USDC per claim) and the stated RTP is about 93%, so losses are expected over time. The server requires a wallet private key in LOTERO_WALLET_PRIVATE_KEY; use a dedicated, low-balance wallet. Spin and claim send transactions and spend funds. The README notes a 5% dev fee per bet and a 1% referral commission.

Installation

In SourceWeft

  1. Open Lotero in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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
  • 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)

ItemValue
Address0xC4b88e90a73fA9ec588E504255A43d4Ccb82edE9
TokenUSDC. Bet 1 USDC, win up to 30 USDC.
VRFChainlink VRF 2.5
EventsSpinRequested, 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.

  • 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 agentyarn 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:

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

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

DocDescription
DOCS/AGENT_FLOWS.mdFlow diagrams (cron health, spin, claim)
DOCS/AGENT_API.mdAPI reference, endpoints, env, constants
DOCS/DEPLOY_BASE.mdDeploy contracts to Base
DOCS/RTP_MODEL.mdRTP math and reel layout

Requirements

Quick Start

1. Install dependencies

bash
git clone https://github.com/csacanam/lotero-core.gitcd lotero-coreyarn 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. Contract address above. Fund the VRF subscription with LINK.

License

MIT

Source: README.md at commit 4a55d7a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts