Provably fair RNG API · open source

Generate provably fair random numbers.

A free, open-source API for random numbers, dice rolls, winner picks and shuffles. Every result comes with a server hash and a proof anyone can check.

Get started View on GitHub

Live API console

GET https://api.provable.io/api/ints?clientSeed=demo-user&count=5&min=1&max=100

No key needed
Your random numbers will appear here
cURL
Live Response
{
  "outcome": [],
  "message": "Click 'Generate' to try the API"
}

Try a draw, then check it with the outcome verifier or read the API reference.

Open by default

Every piece is public.

The generator, the spec and the audit trail are all open, so nothing about a draw depends on taking our word for it. Check any of it.

The problem

Random you can't check is just a claim.

A fair draw needs a commitment before the result and a way to check it after. Most random sources give you neither.

How to generate provably fair random numbers

Math.random() leaves no receipt.

Fine for particles, useless in a dispute. Nothing records what the numbers were or how they were made.

A hosted RNG asks for trust.

You get a number and a promise. With no commitment made before the draw, there is nothing to check after it.

On-chain proof has a toll.

Every draw is a transaction: a fee per request and a wait for block confirmations. Worth it for contracts, heavy for everything else.

Audit trail

Every draw leaves a receipt.

Each outcome is stored with its client seed, nonce and server hash. Once the seed rotates, the server seed is revealed and anyone can re-run the draw. Pick a record and replay it.

How verification works
outcomesExample records · replay runs in your browser
Example outcome records
shortIdclientSeedrangeoutcomeserverHashtime (UTC)
raffle-2026-091–2400284eb39f6e8…14:02:11
loot-box-77811–10087e16699a3…14:02:48
tournament-seat-121–64369299991b…14:03:05
dice-room-31–62, 6cbc4bc81…14:03:19
giveaway-oct1–50002033, 741, 137931edfa0…14:04:02
mint-reveal-04191–100008310190dffe9…14:04:37

Unbiased mapping

Uniform means uniform.

The usual shortcut maps random bytes onto a range with %, which quietly favours some numbers. provable-core throws away the few values that would tilt the odds, so every outcome is exactly as likely.

2,400

MethodSkew, log scaleMost likely outcome vs fair

provable-core ints()exact
Math.random() * n+1.6e-11%
uint32 % n+0.000016%
byte % nmisses 2,144 outcomes

Math.random() assumes a 52-bit float, as in V8. Skew is the worst-case extra chance of the most favoured outcome.

SDK

Typed client. Zero dependencies.

@provableio/sdk covers every endpoint with types generated from the OpenAPI spec. It runs on Node 18+, Deno, Bun, browsers and Workers, and returns errors as values instead of throwing.

TypeScript SDK guide
draw.tspackage.json
import { ProvableClient } from "@provableio/sdk";

const client = new ProvableClient({ apiKey: process.env.PROVABLE_KEY });

const { data, error } = await client.getInts({
  clientSeed: "raffle-2026-09",
  count: 1, min: 1, max: 2400,
});
if (error) throw new Error(error.error);

// publish the hash with the winner so anyone can check it later
const { data: ok } = await client.verifyServerHash({
  clientSeed: data.clientSeed,
  serverHash: data.serverHash,
});

Commit-reveal

Hash first. Seed second.

For draws that must be sealed in advance, POST /api/commit returns a server hash before you choose your client seed. POST /api/reveal then returns the outcome and the seed, so the server could not have steered the result.

Commit-reveal reference
raffle-2026-09timeline
  1. POST /api/commitserverHash eb39f6e84e957e12… published
  2. you chooseclientSeed "raffle-2026-09"
  3. POST /api/revealoutcome returned, serverSeed aed996bd82c48a54… revealed
  4. sha256(serverSeed)equals the hash published at 14:02:07

Public proof

A proof page for every draw.

Every outcome gets a short ID and a permalink anyone can open. Post it next to a raffle result and let people check it themselves.

Verify an outcome
zsh
$ curl -s "https://api.provable.io/api/pick?clientSeed=standup-rota-oct&items=ana,ben,cy,dee"
{
  "outcome": "cy",
  "index": 2,
  "clientSeed": "standup-rota-oct",
  "serverHash": "de9f309861c8d6e6…",
  "shortId": "6bqsyaI07a",
  "permalink": "https://api.provable.io/o/6bqsyaI07a"
}
$ curl -s "https://api.provable.io/api/verifyShortId?shortId=6bqsyaI07a" | jq .verified
true

Use cases

Built for draws people care about.

Dice Roller API

Standard NdM notation, verifiable per-roll outcomes.

Raffle Picker API

Draw a winner from a list, publish proof anyone can verify.

Card Shuffler API

A verifiable Fisher-Yates shuffle in one HTTP call.

Lottery API

Pre-committed lottery draws anyone can replay.

Sweepstakes API

Compliance-ready winner selection with a paper trail.

NFT Mint Randomizer API

Gas-free, off-chain trait and reveal-order randomness.

See all use cases

Compare

How it stacks up.

RANDOM .ORG

vs Random.org

Hardware entropy vs publicly verifiable randomness.

vs Chainlink VRF

The off-chain alternative: no gas, no LINK, same proof.

JS

vs Math.random()

When a local generator stops being enough.

 drand

vs drand

A public beacon vs a per-call commit-reveal API.

See all comparisons

FAQ

Frequently asked questions.

What is a provably fair random number?

A provably fair random number is an outcome that anyone can independently verify was not chosen on purpose. The server publishes a cryptographic hash of its secret seed before you ask for a number; once your client seed is mixed in and the server seed is revealed, anyone can recompute the result and prove it matches the original hash.

Is the API free to use?

Yes. Anonymous calls are free and rate-limited by IP. Signing up gives you an API key for usage attribution and a daily quota of 10,000 requests at no cost.

How do I verify a past outcome?

Go to the /verify page or call GET /api/verifyServerHash with the original clientSeed and serverHash. The endpoint returns true if the values match our records, confirming the outcome was generated as claimed.

Can I use this for online gaming or a casino?

Provable.io is a general-purpose verifiable RNG suitable for game mechanics, raffles, NFT trait reveals, and similar use cases. It is not itself a gaming licence — operators in regulated jurisdictions are responsible for their own compliance, but the cryptographic transparency the API provides is exactly the kind of evidence regulators and players ask for.

How does the commit-reveal flow work?

Call POST /api/commit to receive a commitment id and a hash of an outcome that has been generated but not yet shown to you. Later, call POST /api/reveal with the commitment id to receive the outcome itself. Because the hash was issued before reveal, neither party could have changed the result after the fact.

Commit first. Prove every draw.

Free API key, no credit card. 10,000 requests a day.

Get started View on GitHub