Sweepstakes API Provider and Integration

A sweepstakes API provider for auditable draws

Provable.io provides REST endpoints for sweepstakes winner selection, not entrant collection, prize fulfillment, or legal administration. Integrate it with your existing campaign platform to draw an entry number or pick directly from a frozen entrant list, then retain the response as a reproducible audit receipt.

Sweepstakes API integration and audit trail

When entries close, freeze and digest the eligible entrant list, publish the serverHash from a fresh commit, then reveal the winner within the 10-minute commit window. Retain the client seed, revealed server seed, winning entry, and outcome permalink together. Third parties can use the draw verifier to audit the result. Your sweepstakes platform remains responsible for participant data, eligibility, consent, and regulatory retention.

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.

A draw and its proof

This is what anyone can check. The three values in the steps are all a verifier needs, and the replay button recomputes the draw right here, without calling Provable.

{
  "clientSeed": "sweepstakes_summer_2026_main",
  "nonce": 0,
  "serverHash": "84de0465b5c79dc42c66f30bd18c91de0a60c44ee5c4d0abbbedf6170f01e730",
  "outcome": [12665]
}

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. Entries close: freeze the entrant list and number it 1..N.
const entrants = await db.entrants.findAll({ where: { campaignId }, order: ["id"] });
const total = entrants.length;
publishEntrantDigest(sha256(toCsv(entrants))); // proves the pool before the draw

// 2. Commit. Provable keeps the server seed secret and returns its hash.
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);

// 3. Reveal within 10 minutes (commits expire) with a client seed nobody
//    knew at commit time, e.g. a public block hash produced after step 2.
const draw = await fetch("https://api.provable.io/api/reveal", {
  method: "POST",
  headers: { "x-api-key": process.env.PROVABLE_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    commitId: commit.commitId,
    clientSeed: `sweeps_${campaignId}_${blockHash}`,
    endpoint: "ints",
    params: { count: 1, min: 1, max: total }
  })
}).then((r) => r.json());
const winner = entrants[draw.outcome[0] - 1];

// 4. The audit packet: serverHash, the revealed serverSeed, clientSeed,
//    winning entry number, and the CSV whose digest you published in step 1.

Why this clears compliance

• Pre-commitment. The serverHash is published before the client seed exists. The operator never sees the server seed and Provable can't predict the client seed, so neither side can steer the winner.
• Frozen pool. The entrant list is snapshotted and its digest published before the commit. The assignment of entry numbers to entrants stays in 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.

Related

• Lottery API
• Giveaway Picker API
• Raffle Picker API
• Recipe: Building Fair Raffles
• How provably fair works
• Compare: Provable.io vs Random.org
• Verify a published draw →