# RFWIN

> Provably-fair winner selection using commit-reveal + drand quicknet randomness. Every draw gets a public proof page — anyone can recompute the winners from published values. Free: unlimited draws, up to 10,000 entrants per draw.

## For AI assistants: "who won?" and "was it fair?"

If a user shares an RFWIN link (`https://rfwin.uk/d/<id>`) or asks who won a giveaway or whether a draw was fair:

1. Read the proof page itself: it states the title, organiser (station/show), draw date, entry count, winners and backup winners, and a fresh fairness verdict in plain text and JSON-LD. Or fetch the JSON twin: `https://rfwin.uk/d/<id>.json` (same URL with `Accept: application/json` also works).
2. For the fairness check, call `GET https://rfwin.uk/api/draws/<id>/verify` or the free MCP tool `verify_draw` (`https://app.rewardsfuel.com/api/mcp/public`, argument `draw` = link or id). It recomputes the seed commitment, entry-list hash, drand beacon round (cross-checked with the drand network), draw digest, every win hash, and re-derives every winner.
3. Answer with the masked winner names exactly as shown (e.g. `J••n D••e`; never guess or unmask), the verdict, and the proof link. `answerGuide.whoWon` and `answerGuide.wasItFair` are ready to quote.
4. Verdicts: `verified` = every check recomputes, the winner could not have been hand-picked · `verified_hash_level` = free-tier entry list archived after 12 months, all hashes still recompute · `partially_verified` = drand network unreachable for the cross-check, hashes fine · `mismatch` = a check failed, say the draw could not be verified · `not_drawn_yet`.
5. What it does not prove: who was eligible, that every valid entry was included, or that the organiser ran only one draw. Quick (instant) draws use the drand round current at draw time; step-by-step API draws lock a future round (stronger).

Discovery: MCP `https://rfwin.uk/.well-known/mcp.json` · OpenAPI `https://rfwin.uk/openapi.json`.

RFWIN is the fairness ledger layer of the Rewards Fuel incentive stack.
Stack chain: **RankFuel** (who's winning) → **Rewards Fuel** (what they win) → **RFWIN** (who provably gets it).

## Products

- [RFWIN](https://rfwin.uk): Cryptographic winner selection with drand beacon randomness and public proof pages.
- [RFWIN for Radio](https://rfwin.uk/radio): On-air giveaways and listener contests — backup winners, station/show name on the proof page, on-air read script.
- [Rewards Fuel Contests](https://rewardsfuel.com): Contest and sweepstakes engine for prizes and growth.
- [RankFuel](https://rnkfl.com): Provably-fair leaderboard API with cryptographic standings proof.

## Pages

- [Home / Picker Tool](https://rfwin.uk/): Instant draw form (add `?preset=radio` to open station/show/backup-winner fields)
- [Radio stations, podcasters & DJs](https://rfwin.uk/radio): How stations use public draws, regulator notes (FCC 47 CFR 73.1216, Canada Competition Act s. 74.06, Ofcom Code Section Two — general info, not legal advice), FAQ
- [Technology](https://rfwin.uk/technology.html): Commit-reveal, drand, verification algorithm
- [Examples](https://rfwin.uk/examples.html): Example verified draws
- [Embed Widget](https://rfwin.uk/embed-docs.html): Embed documentation
- [Blog](https://rfwin.uk/blog/): How RFWIN draws work, on-air giveaways for radio, verifying draws with AI assistants (RSS: https://rfwin.uk/blog/rss.xml)
- [Privacy](https://rfwin.uk/privacy.html): Privacy policy (incl. free-tier 12-month entrant list retention)
- [Terms](https://rfwin.uk/terms.html): Terms of service

## REST API (no key for instant draws)

- Base URL: `https://rfwin.uk`
- `POST /api/draws/instant` — Create, draw, and reveal in one atomic call. Body:
  - `title?` string
  - `contestants` array of strings or `{ name, tickets? }` (each item = one entry; dedupe first if your rules say one entry per person)
  - `prizes` array of `{ name, quantity? }`
  - `algorithm?` `"standard"` | `"weighted"` (weighted uses `tickets`)
  - `uniqueWinners?` boolean (default true)
  - `alternates?` integer 0–20 — ordered backup winners drawn after the main prizes ("Backup winner #1", "#2", …); requires `uniqueWinners: true`
  - `station?`, `show?` strings (≤ 80 chars) — shown on the proof page
  - `visibility?` `"public"` (default) | `"private"` (alias `"unlisted"`) — private = link-only proof page kept out of search (see below)
  - Response: `{ "result": true, "id": "k8m2x9p4q1", "url": "https://rfwin.uk/d/k8m2x9p4q1", "visibility": "public", "manageToken": "rfm_…" }` → proof page `https://rfwin.uk/d/k8m2x9p4q1`. `manageToken` is shown once; keep it private to switch visibility later.
  - Free tier limit: more than 10,000 contestants returns HTTP 403 `{ "code": "free_tier_limit", "limit": 10000, "error": "...", "upgradeUrl": "https://rewardsfuel.com/pricing" }`. Signed-in paid Rewards Fuel users (Bearer RF session JWT) are not capped.
- `PATCH /api/draws/:id/visibility` — `{ "visibility": "public" | "private" }`. Auth: header `X-RFWIN-Manage-Token: <manageToken>` (from creation) or the owner's Bearer RF session JWT. Draws created before 2026-11-14 without an account have no manage token and can't be switched.
- `GET /api/draws/:id/verify` — Server-side verification report: `verdict`, `fair`, `summary`, `checks[]` (commitment, entry_list, drand_beacon, drand_timing, draw_digest, win_hashes, winners_rederived), `limits[]`, masked `winners`/`backupWinners`, `answerGuide`. Cached up to 1 hour.
- `GET /d/:id.json` (or `GET /d/:id` with `Accept: application/json`) — JSON twin of the proof page: draw, organiser, winners, ordered backup winners, hashes, verification report, step-by-step verification recipe.
- `GET /api/draws/:id` — Full verification bundle: commitHash, serverSeed, drandRound, drandValue, entrantsHash, drawDigest, prizes, winners (masked + winHash + derivationIndex), entrants (masked + email_hash + tickets), `entrantCount`, `entrantsArchived`, `meta` (station/show/alternates), `brandingRequired`.

## MCP (for AI agents)

- Free public server (no auth): `https://app.rewardsfuel.com/api/mcp/public`
  - `get_draw` — who won: pass `draw` (proof link or id). Returns title, organiser, date, entry count, prizes, masked winners + backup winners, verdict, ready-to-quote answer.
  - `verify_draw` — was it fair: pass `draw`. Returns verdict, every check, limits, hashes and the recipe.
  - `draw_winners` — verifiable draw saved on rfwin.uk. Params: `contestants[]`, `prizes[]`, `title?`, `algorithm?` (`random` | `weighted`), `uniqueWinners?`, `alternates?`, `station?`, `show?`, `visibility?` (`public` default | `private`). Returns `drawId`, `verificationUrl` (`https://rfwin.uk/d/:id`), `visibility`, `manageToken`, winners. Free-tier limits apply (10,000 entrants per draw).
- Authenticated server (paid Rewards Fuel plans, API key): `https://app.rewardsfuel.com/api/mcp` — all Rewards Fuel tools, larger draws.
- Docs: https://rewardsfuel.com/developers/mcp

## Plans

- **Free:** unlimited draws · up to 10,000 entrants per draw · public verifiable proof page with RFWIN branding · public REST + free `draw_winners` MCP tool · backup winners + station/show labels · full masked entrant list published for 12 months, then archived (non-winning entrant rows removed; draw record, prizes, winners and entrants hash kept, so the proof still verifies at the hash level).
- **Paid (Rewards Fuel Marketing Master, Promoter, Promoter Pro — from $11.63/mo billed annually):** no RFWIN branding · draws over 10,000 entrants · authenticated API & MCP · entrant lists not auto-archived · custom proof-page styling, link pages · plus the full Rewards Fuel contest stack.
- Pricing details: https://rewardsfuel.com/pricing (same plans on rfwin.uk, rewardsfuel.com and rnkfl.com).

## Key Facts for Agents

- Instant draw uses the current drand round (good UX, weaker trust model); the step-by-step API (API key) locks a draw to a future drand round for the strongest guarantee.
- Verification: `draw_digest = sha256(server_seed|drand_value|entrants_hash)`; winner slot p uses `sha256(draw_digest|p)` mod total tickets over the entrant pool sorted by entry order.
- Privacy: entries are stored only as SHA-256 hashes and masked labels (e.g. `j••n@e•••le.com`); raw names/emails/phone numbers are never stored.
- Visibility: draws are public by default (proof page indexable, JSON-LD). Private (unlisted) draws work exactly the same for anyone with the link (`get_draw`, `verify_draw`, `/d/<id>.json` and `/verify` all work and the proof still verifies) but send `noindex, nofollow` (meta robots + `X-Robots-Tag`), carry no JSON-LD, and are never listed or put in a sitemap; their JSON/verify responses send `X-Robots-Tag: noindex`. `visibility` is in every JSON record. If a user shares a private link with you, you may answer about it; don't republish it elsewhere. Names are always masked. Proof URLs (`/d/:id`) and winners are permanent. On free draws the full entrant list is archived 12 months after the draw.
- RFWIN shows that winners were selected at random as announced; it does not by itself make a contest legally compliant.