Sweepstakes API — Auditable Sweepstakes Winner Selection

What it is

A sweepstakes-grade winner picker built on /api/ints (for entry-number draws) and /api/pick (for direct entrant lists). One call returns the winning entry plus a serverHash that any third party — your legal team, an administrator, a state regulator, an annoyed Reddit thread — can paste into /verify to confirm the draw wasn't re-rolled.

The pain point

Sweepstakes are heavily regulated in the US and EU and the operator usually has to provide proof — to a bonding company, to a regulator, sometimes to a court — that the winner was selected at random and not, say, the brand manager's cousin. Screenshots of Math.random() won't cut it. A verifiable RNG with a pre-published commitment is exactly the kind of evidence affidavits ask for.

Try it live — draw entry #X out of N

Most sweepstakes assign entrants sequential entry numbers. Draw a winning entry number directly:

curl "https://api.provable.io/api/ints?clientSeed=sweepstakes_summer_2026_main&count=1&min=1&max=15842"

Or draw a runner-up + 5 alternates from the same seed (the API auto-advances the cursor so each call returns a distinct draw):

curl "https://api.provable.io/api/ints?clientSeed=sweepstakes_summer_2026_alts&count=5&min=1&max=15842"

Integration snippet

// 1. When entries open: pre-commit the draw.
const commit = await fetch("https://api.provable.io/api/commit", {
  method: "POST",
  headers: { "x-api-key": process.env.PROVABLE_KEY }
}).then((r) => r.json());
publishToRulesPage(commit.serverHash); // pinned at the top of the official rules

// 2. When entries close: freeze the entrant list and assign sequential IDs.
const entrants = await db.entrants.findAll({ where: { campaignId }, order: ["id"] });
const total = entrants.length;

// 3. Reveal the draw with an unguessable clientSeed
//    (a published block hash from a public chain is ideal).
const winner = await fetch(
  `https://api.provable.io/api/ints?clientSeed=sweeps_${campaignId}_${blockHash}` +
  `&count=1&min=1&max=${total}`,
  { headers: { "x-api-key": process.env.PROVABLE_KEY } }
).then((r) => r.json());

// 4. The audit packet: clientSeed, serverHash, winning entry number,
//    permalink to /o/{shortId}, and a CSV of the frozen entrant list.

Why this clears compliance

Pre-commitment. The serverHash is published before entries close, so the operator can't shop seeds against the entrant list.
Frozen pool. The entrant list is snapshotted before the draw; the assignment of entry numbers to entrants is the operator's existing system of record.
Open math. The mapping from HMAC bytes to an integer in [1, N] is documented in the open-source library — re-derivable years later from the published seed.
Permalink in the affidavit. Every outcome lands at /o/<shortId> — drop the URL into the post-draw filing.

Where it fits

Consumer brand sweepstakes with state-level disclosure requirements.
SaaS launch giveaways where users want a receipt, not "we promise."
Affiliate / partner contests where multiple parties need the same source of truth.
Loyalty program prize draws tied to point thresholds or tier eligibility.