HomeCollectionRoadmapTokenomicsAboutCommunity
Join Community
Public REST API

Lottery Draw API

No authentication required. Provably fair, deterministic, and fully auditable. Send entries, get winners, verify everything independently.

None
Auth
Fully public
REST / JSON
Protocol
HTTP POST & GET
100 req/min
Rate Limit
Per IP address
Yes
Deterministic
Same seed = same result
Base URL
https://api.winfinity.club/api/v1
Endpoints

API Reference

Two endpoints. One runs the draw. The other gives you the algorithm source code.

POST/lottery/drawPublic

Run a weighted lottery draw

Submit a list of entries with weights and receive deterministic winners. The draw uses SHA-256 entry hashing, cumulative weight distribution, and a VRF-seeded random number generator. Results are fully reproducible.

Request Body Fields

entriesarray[object]RequiredList of entries. Each needs 'id' (string) and 'weight' (number >= 0).
winner_countintegerRequiredHow many winners to draw. Min 1, max 100. Must be <= len(entries).
seedstring | nullOptionalVRF seed hex string. If omitted, a random 64-char seed is auto-generated.
max_weight_capfloatOptionalMaximum allowed weight per entry. Default 3.0. Min 1.0.

Request Example

json
{
"entries": [
{ "id": "alice", "weight": 2.5 },
{ "id": "bob", "weight": 1.0 },
{ "id": "carol", "weight": 3.0 },
{ "id": "dave", "weight": 1.5 }
],
"winner_count": 3,
"seed": "0xabc123def4567890abcd1234ef567890ab12cd34ef567890ab12cd34ef5678",
"max_weight_cap": 3.0
}

Response Example

json
{
"success": true,
"seed": "0xabc123def4567890abcd1234ef567890ab12cd34ef567890ab12cd34ef5678",
"seed_source": "provided",
"total_entries": 4,
"total_weight": 8.0,
"winner_count": 3,
"max_weight_cap": 3.0,
"winners": [
{ "rank": 1, "entry_id": "alice", "weight": 2.5, "selection_value": 1.234567, "cumulative_index": 0 },
{ "rank": 2, "entry_id": "carol", "weight": 3.0, "selection_value": 4.567890, "cumulative_index": 2 },
{ "rank": 3, "entry_id": "dave", "weight": 1.5, "selection_value": 6.123456, "cumulative_index": 3 }
],
"cumulative_weights": [2.5, 3.5, 6.5, 8.0],
"entry_hashes": [
"a3f5c8...", "b7e2d1...", "c9a4b2...", "d1e8f3..."
],
"draw_log": [
{ "step": 1, "pick_value": 1.234567, "selected_id": "alice" },
{ "step": 2, "pick_value": 4.567890, "selected_id": "carol" },
{ "step": 3, "pick_value": 6.123456, "selected_id": "dave" }
]
}
GET/lottery/draw/algorithmPublic

Get algorithm documentation & source code

Returns the full algorithm description, Python source code, JavaScript source code, and a verification checklist. Useful for client-side implementations or audits.

Response Example

json
{
"algorithm": {
"name": "Provably Fair Weighted Lottery Draw",
"version": "1.0.0",
"steps": [
"Cap all entry weights to max_weight_cap",
"Compute SHA-256 hash of each entry (id + weight + seed)",
"Build cumulative weight distribution array",
"Seed deterministic PRNG with VRF seed",
"For each winner: generate random pick in [0, available_total)",
"Binary search on cumulative array to find winning entry",
"Remove winner from pool (no replacement)",
"Return winners, seed, hashes, and cumulative weights for verification"
]
},
"code": {
"python": "def weighted_lottery_draw(...)",
"javascript": "function weightedLotteryDraw(...)"
},
"verification": {
"description": "Anyone can verify a draw by re-running the algorithm...",
"checklist": [ "Use the exact same entry IDs and weights", ... ]
}
}
Examples

Try It Yourself

Copy-paste these examples into your terminal or IDE. No API key needed.

example.sh
javascript
1
curl -X POST https://api.winfinity.club/api/v1/lottery/draw \
2
-H "Content-Type: application/json" \
3
-d '{
4
"entries": [
5
{"id": "alice", "weight": 2.5},
6
{"id": "bob", "weight": 1.0}
7
],
8
"winner_count": 1,
9
"seed": "0xabc123..."
10
}'

How to Verify Any Result

The API returns everything you need to independently confirm that a draw is fair. Follow these steps to reproduce the exact same winners locally.

1

1. Save the returned seed, entry list, and max_weight_cap

2

2. Run the algorithm locally using the Python or JS code above

3

3. Compare your output cumulative_weights with the API response

4

4. Confirm entry_hashes match (SHA-256 of id:weight:seed)

5

5. Confirm winner order, ranks, and selection values match

6

6. If everything matches, the draw is provably fair and untampered

Ready to Integrate?

Use the public API to power your own lottery, giveaway, or random selection system.