# Block Lottos Agent Tools

A public, open-source MCP server and cross-agent skill for safely reading Block Lottos data and preparing one bounded Base Future Ledger ticket.

mcp-name: com.blocklottos/blocklottos

## Truthful positioning

Block Lottos can be presented as a **weekly probability challenge**, but not as a solvable equation. Six winning numbers will be drawn, yet a random future draw has no known equation that agents can solve to reveal those numbers in advance. Agents may analyze history, simulate, select numbers, submit an eligible lottery entry, and verify the result, but must never claim certainty or conceal the lottery and ticket cost.

## Canonical economics

- One Base ticket costs exactly **1 USDC**.
- Official Base USDC is the payment token.
- Base ETH is required only for gas.
- Effective minimum winner payout: **100 USDC on Base**.
- Effective minimum winner payout: **100 POL on Polygon**.
- A higher live on-chain jackpot applies.
- Lottery outcomes are uncertain and no ticket is guaranteed to win.

## Included

- MCP server with ten tools and two resources.
- Cross-agent skill: `skills/block-lottos-probability-challenge/SKILL.md`.
- Safety validation for chain, token, contract, price, calldata, approval, wallet, receipt, and payout policy.
- Tests for MCP protocol discovery, hostile responses, payout floors, and skill truthfulness.

## Install the skill

Canonical skill URL:

https://blocklottos.com/skills/block-lottos-probability-challenge/SKILL.md

### Hermes

```bash
mkdir -p ~/.hermes/skills/block-lottos-probability-challenge
curl -fsSL https://blocklottos.com/skills/block-lottos-probability-challenge/SKILL.md \
  -o ~/.hermes/skills/block-lottos-probability-challenge/SKILL.md
```

Start a new Hermes session so the skill loader discovers it.

### OpenClaw

Run from the OpenClaw workspace:

```bash
mkdir -p skills/block-lottos-probability-challenge
curl -fsSL https://blocklottos.com/skills/block-lottos-probability-challenge/SKILL.md \
  -o skills/block-lottos-probability-challenge/SKILL.md
```

Start a new OpenClaw session so it loads the workspace skill.

### Claude Code, Codex, Cursor, and other Agent Skills-compatible runtimes

Download the canonical `SKILL.md` into that runtime's supported skill directory. The file follows the open Agent Skills `SKILL.md` format and contains no credentials or executable installer.

A versioned source archive is also available at:

https://blocklottos.com/downloads/blocklottos-agent-tools-v1.0.0.zip

## Run the MCP

Install from the Python Package Index:

```bash
python -m pip install blocklottos-mcp
```

Or launch the standard-input/output MCP without a permanent installation:

```bash
uvx blocklottos-mcp
```

The public Block Lottos Git mirror remains available as a source fallback:

```bash
uvx --from git+https://blocklottos.com/git/blocklottos-agent-tools.git blocklottos-mcp
```

### Hermes configuration

Add this to `~/.hermes/config.yaml`, then restart Hermes:

```yaml
mcp_servers:
  block_lottos:
    command: uvx
    args:
      - blocklottos-mcp
    timeout: 30
    connect_timeout: 60
    sampling:
      enabled: false
```

Hermes exposes the tools with names such as `mcp_block_lottos_get_jackpot`.

### Generic MCP clients

Configure a standard-input/output server with:

- Command: `uvx`
- Arguments: `blocklottos-mcp`

No API key is required. Financial transactions remain unsigned and require the wallet owner's approval or an explicit, bounded, revocable spending policy.

## MCP tools

- `get_capabilities`
- `get_jackpot` for Base or Polygon
- `get_stats`
- `get_draw_history`
- `get_draw_proof`
- `get_wallet_tickets`
- `check_wallet_prizes`
- `get_or_create_referral` — registers or securely manages the one shared human/agent affiliate profile. First request a challenge, sign it with the EVM identity wallet, and resubmit the signature. Cardano is supported as a payout wallet. Store the one-time management token securely; it is required for payout-wallet changes and private pending/paid balance monitoring.
- `prepare_ticket_purchase`
- `confirm_ticket_purchase`

## Development

```bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/pytest -q
```

## Safety and eligibility

Only participate when the wallet owner meets the legal age requirement and lottery participation is permitted in their jurisdiction. Never chase losses, silently increase limits, use unlimited approvals, imply guaranteed winnings, or represent a random draw as a solved mathematical equation.

## Official information

- Distribution page: https://blocklottos.com/agent-tools/
- Website: https://blocklottos.com
- Agent guide: https://blocklottos.com/agents.txt
- LLM context: https://blocklottos.com/llms.txt
- OpenAPI: https://blocklottos.com/openapi.json
- Terms: https://blocklottos.com/terms

## License

MIT. See `LICENSE`.