Run a fair draw

run_draw picks count winners (plus optional alternates, in order) from a list of entries, or shuffles the whole list. When the draw is created, the entries are fingerprinted (SHA-256) and stored, and the job is charged; then fresh hardware randomness is drawn and its fingerprint is committed on an Ed25519-signed receipt. At draw_at, or at once without it, the randomness is revealed and the result computed and signed. Each draw has a permanent page, receipt_url, that recomputes the result in the reader's browser; the signed receipt itself is GET /draws/{id} on the API, and GET /draws/key publishes the public key. Draws are numbered per organizer, so a re-run for the same list shows as a new number. The receipt proves the list was fixed before the randomness and lets anyone recompute the result; it cannot prove how the hardware randomness was produced.

Randomness

Hardware-generated, fresh for each draw

Input

entries (one per line), title, winners and alternates or a shuffle; no file

Outputs

A public page, the signed receipt (draw.json) and draw.txt

Proof

Entries locked first; Ed25519-signed receipt; recomputable by anyone

Schedule

Reveal now, or at a time up to 30 days ahead

Send the options as JSON. The response is the new job; poll it until its status is final, then download the files in result.files.

curl https://api.mcpbytes.com/v1/tools/run_draw/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"giveaway-example-001",
  "options":{"title":"October giveaway",
  "count":2,"alternates":1,"publish_entries":true,
  "entries":"ticket-01\nticket-02\nticket-03\nticket-04\nticket-05\nticket-06\nticket-07\nticket-08\nticket-09\nticket-10\nticket-11\nticket-12"}}'

{
  "id": "j_ms3h6bzdpe8d4g5skh96a531cy",
  "tool": "run_draw",
  "status": "succeeded",
  "input_kind": "parameters",
  "draw": {
    "id": "d_twh8fkzwkksxh7y6ykpfexdc4v",
    "status": "drawn",
    "receipt_url": "https://mcpbytes.com/draws/d_twh8fkzwkksxh7y6ykpfexdc4v",
    "draw_at": "2026-09-24T18:24:12.644Z"
  },
  "options": {
    "title": "October giveaway",
    "mode": "pick",
    "count": 2,
    "alternates": 1,
    "publish_entries": true,
    "entries_count": 12,
    "entries_sha256": "08b4ee8c7fa858181f549277d7bff2b65edd0baf252920884b0103272a5c587e",
    "draw_id": "d_twh8fkzwkksxh7y6ykpfexdc4v"
  }
}

curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

{
  "id": "j_ms3h6bzdpe8d4g5skh96a531cy",
  "tool": "run_draw",
  "status": "succeeded",
  "draw": {
    "id": "d_twh8fkzwkksxh7y6ykpfexdc4v",
    "status": "drawn",
    "receipt_url": "https://mcpbytes.com/draws/d_twh8fkzwkksxh7y6ykpfexdc4v",
    "draw_at": "2026-09-24T18:24:12.644Z"
  },
  "result": {
    "draw_id": "d_twh8fkzwkksxh7y6ykpfexdc4v",
    "status": "drawn",
    "title": "October giveaway",
    "receipt_url": "https://mcpbytes.com/draws/d_twh8fkzwkksxh7y6ykpfexdc4v",
    "draw_at": "2026-09-24T18:24:12.644Z",
    "files": [
      {
        "name": "draw.json"
      },
      {
        "name": "draw.txt"
      }
    ]
  }
}

A job can be canceled while it is queued: POST /v1/jobs/{id}/cancel.

More on statuses, downloads and retention in Jobs & files.

No file. Send the options in a JSON body, {"options": {…}}, or as arguments of the MCP tool. Keep private text such as prompts out of URLs.

Put options in the options object of the JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

A new draw returns HTTP 202 while its hardware randomness is drawn, usually within seconds; replaying a completed request returns HTTP 200. Every draw job also carries `draw`: its id, status (pending, committed, drawn or failed), receipt_url and draw_at. A scheduled draw's files are rewritten at the reveal. The page and receipt are permanent; the job's files follow output retention.

Result summary

Next to files, the job's result has a summary you can check without downloading anything:

• Put one entry per line: handles, ticket numbers or names, never emails. Winners appear on a public page.
• Share receipt_url with participants. The page shows the result and checks the receipt in the reader's browser.
• Set publish_entries to let anyone check the list itself. Otherwise the page shows only its size and fingerprint, and a shuffle shows positions instead of names.
• With draw_at, the job succeeds at once with status scheduled: the page is live and its randomness fixed, and the result appears at that time.
• Reuse the idempotency key to retrieve the same draw after a network failure. A new key for the same list is a new, numbered draw.
• If hardware randomness is unavailable, the draw fails with source_unavailable and costs nothing.

Your agent calls run_draw. Connect it to https://api.mcpbytes.com/mcp/random for this tool and the rest of its family (Get random numbers), or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/random

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/random \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/random",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/run_draw.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

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

10 credits per job. The price is charged before paid processing starts. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Get random numbersPlain random integers, when you need numbers rather than a verifiable draw.get_random_numbers