Provably fair random draw API

Pick giveaway winners from a list or a number range with a commit-reveal proof: publish the seed hash first, draw with a public salt, let anyone verify.

Parameters

Example

curl -X POST "https://apibox.io.vn/v1/random-draw/draw" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed":"a3f1c9e07b5d2486a3f1c9e07b5d2486","entries":"Nguyễn An\nTrần Bình\nLê Chi\nPhạm Dũng\nHoàng Em","salt":"1532","winners":2,"reserve":1}'

const res = await fetch('https://apibox.io.vn/v1/random-draw/draw', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "seed": "a3f1c9e07b5d2486a3f1c9e07b5d2486",
    "entries": "Nguyễn An\nTrần Bình\nLê Chi\nPhạm Dũng\nHoàng Em",
    "salt": "1532",
    "winners": 2,
    "reserve": 1
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/random-draw/draw",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"seed": "a3f1c9e07b5d2486a3f1c9e07b5d2486", "entries": "Nguyễn An\nTrần Bình\nLê Chi\nPhạm Dũng\nHoàng Em", "salt": "1532", "winners": 2, "reserve": 1},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/random-draw/draw');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"seed":"a3f1c9e07b5d2486a3f1c9e07b5d2486","entries":"Nguyễn An\\nTrần Bình\\nLê Chi\\nPhạm Dũng\\nHoàng Em","salt":"1532","winners":2,"reserve":1}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "kind": "list",
  "seed": "a3f1c9e07b5d2486a3f1c9e07b5d2486",
  "commitment": "af24c17ea9f89cc17d2b578b1f965de883c5596b31bb34cdac7077bdc8357696",
  "salt": "1532",
  "entries_count": 5,
  "entries_hash": "4c2ecdb5ece276bb6836ad66df15956d19156d10df68e800ed2f62f6bba74b74",
  "weighted": false,
  "unique_entries": true,
  "winners": [
    {
      "rank": 1,
      "entry": "Hoàng Em",
      "index": 5
    },
    {
      "rank": 2,
      "entry": "Nguyễn An",
      "index": 1
    }
  ],
  "reserves": [
    {
      "rank": 3,
      "entry": "Lê Chi",
      "index": 3
    }
  ],
  "algorithm": "random-draw/v1: entries = trimmed non-empty lines in order (with unique_entries, later case-insensitive duplicates are dropped); entries_hash = SHA-256(entries joined by \"\\n\", each as \"label<TAB>weight\" when weights are used); stream = HMAC-SHA256(key = seed, \"random-draw/v1|\" + salt + \"|\" + entries_hash + \"|\" + counter) as 32-bit big-endian words; index = rejection sampling below n; winners = partial Fisher-Yates (weighted: cumulative integer weights, removed once drawn).",
  "drawn_at": "2026-11-11T03:18:50.167Z",
  "verify": "POST /v1/random-draw/verify with the same seed, salt, entries (or min / max), winners and the commitment"
}

Use cases

• Pick comment winners on a Facebook or TikTok livestream
• Run a verifiable lucky draw at a company year-end party
• Draw raffle ticket numbers from a range
• Assign random order or groups in a classroom with proof

FAQ

Related APIs