# run_draw

Discover availability and pricing through `GET /v1/tools` or MCP tools/list. Pick winners from a list,
or shuffle it, with hardware randomness and a permanent public page anyone can use to check the result.
No file is needed. Use `/mcp/random` for this tool family, or `/mcp` for the complete catalog.

Use it for giveaways, raffles, prize draws and fair assignments (who goes first, who reviews what).

## Options

- `entries` (required): one entry per line: handles, ticket numbers or names. **Never emails or other
  private data**: winners appear on a public page. Spaces around entries and empty lines are ignored;
  2–10,000 unique entries (duplicates are refused).
- `title` (required, 1–120 characters): shown on the public page.
- `mode`: `pick` (default) or `shuffle` (orders every entry).
- `count` (1–1000, default 1) and `alternates` (0–100, default 0): winners, then backup winners in
  order. `count + alternates` must not exceed the number of entries. Ignored for `shuffle`.
- `draw_at`: an ISO 8601 time up to 30 days ahead to reveal the result then; omit to draw now.
- `publish_entries` (default false): publish the list on the page so anyone can check every name.
  Otherwise the page shows only the list's size and fingerprint, and a shuffle shows positions, not names.
- `idempotency_key` (required): reuse the key and options to recover the same draw after a network
  failure. A new key for the same list is a **new, numbered draw**, visible on the organizer's receipts,
  so never resubmit to get a different result.

## Result

MCP waits up to 30 seconds by default (`wait_seconds` 0–45) and returns `draw.txt` inline: the title,
the page, and the winners (or the scheduled reveal time). REST returns 202 for a new draw and 200 for a
matching replay. The job's `result` has `draw_id`, `status` (`drawn`, or `scheduled` until `draw_at`),
`title`, `receipt_url` and `draw_at`, and the job carries `draw` (id, status, receipt_url, draw_at).
Files: `draw.json` (the signed receipt) and `draw.txt`.

Give the organizer `receipt_url` (`https://mcpbytes.com/draws/<id>`) to share with participants. The
page shows the result and checks the receipt in the reader's own browser. A scheduled draw's page is
live at once: its randomness is already fixed, and the result appears at `draw_at`.

## What a receipt proves

- The list was fingerprinted (SHA-256) and stored before any randomness existed.
- The hardware randomness was committed (its SHA-256 signed) before a scheduled reveal.
- Anyone can recompute the result: `GET https://api.mcpbytes.com/draws/<id>` returns the Ed25519-signed
  receipt, `GET https://api.mcpbytes.com/draws/key` the public key, and the method is published in the
  docs (https://mcpbytes.com/docs/fair-draws).
- It cannot prove how MCPBytes produced the randomness. Say so plainly if asked; do not claim more.

Without MCP, set `MCPBYTES_API_KEY` privately and use the bundled client (entries.txt: one per line):

```bash
python scripts/mcpbytes.py run run_draw \
  -o title="October giveaway" \
  -o entries="$(cat entries.txt)" \
  -o count=2 -o alternates=1 --out draw/
```

Read the catalog price before submitting. `source_unavailable` means hardware randomness was
unavailable: the draw did not run and the charge was refunded; try again in a few minutes.
`invalid_options` names the problem (too few or duplicate entries, too many winners, `draw_at` too far).