Wheel Spin Pro REST API
Free public API for random picks, Discord bots, and streamer integrations. No API key. No signup. CORS-enabled.
Base URL
https://wheelspinpro.com/api/v1
Try It Live
Test the API directly from your browser — no setup needed.
// Click "Run API Call" to see the JSON response here
API Endpoints
All endpoints return JSON. All are rate-limited to 120 requests per IP per minute.
/api/v1/spin
Pick a random winner
Pick a random winner from a list of items using cryptographically secure randomness. Pass an optional seed for verifiable, reproducible results.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | string | optional | Wheel type. One of: classic-wheel, center-spin, combo-spin, lucky-box, coin-toss, dice-roll. Default: classic-wheel |
items[] | string[] | optional | 2–60 items to spin. If omitted, default items for the type are used. |
seed | string | optional | Deterministic seed. Same seed + same items always returns the same winner. |
Example Request
Example Response
"winner": "Alice",
"seed": "a3f1c8d2e4b09f7e",
"type": "classic-wheel",
"total_items": 3,
"timestamp": "2026-05-15T12:34:56+00:00",
"verification_url": "https://wheelspinpro.com/verify/api/abc123..."
}
/api/v1/wheel
Create a named wheel
Create and store a named wheel configuration. Returns a token you can use to retrieve the wheel later or share with your audience.
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | required | 2–60 items for the wheel. |
name | string | optional | Display name for the wheel. Max 120 chars. |
type | string | optional | Wheel type. Default: classic-wheel |
Example Response
"token": "a3f1c8d2e4b09f7e",
"embed_url": "https://wheelspinpro.com/embed-frame/classic-wheel?items=Alice,Bob,Carol",
"api_url": "https://wheelspinpro.com/api/v1/wheel/a3f1c8d2e4b09f7e"
}
/api/v1/wheel/{token}
Retrieve a stored wheel
Retrieve a previously created wheel configuration by its token. Useful for sharing wheel configs or reloading them in bots.
/api/v1/stats
Public spin statistics
Returns aggregated public statistics — total spins across all wheels, breakdown by wheel type, and spins in the last 24 hours. No PII included.
Code Examples
Pick a random winner from the command line:
Create a named wheel:
-H "Content-Type: application/json" \
-d '{"name":"My Giveaway","items":["Alice","Bob","Carol"]}'
Fetch a random winner in the browser or Node.js:
.then(r => r.json());
console.log(`Winner: ${result.winner}`);
console.log(`Verify: ${result.verification_url}`);
Use in a Python script or bot:
response = requests.get(
'https://wheelspinpro.com/api/v1/spin',
params={'items[]': ['Alice', 'Bob', 'Carol']}
)
data = response.json()
print(f"Winner: {data['winner']}")
discord.js slash command example — /spin Alice Bob Carol:
module.exports = {
data: new SlashCommandBuilder()
.setName('spin')
.setDescription('Pick a random winner')
.addStringOption(o => o.setName('items').setDescription('Comma-separated items').setRequired(true)),
async execute(interaction) {
const items = interaction.options.getString('items').split(',');
const url = new URL('https://wheelspinpro.com/api/v1/spin');
items.forEach(i => url.searchParams.append('items[]', i.trim()));
const { winner, verification_url } = await fetch(url).then(r => r.json());
await interaction.reply(`🎉 Winner: **${winner}**\nVerify: ${verification_url}`);
}
};
Rate Limits
- Free tier: 120 requests/minute per IP
- Exceeding the limit returns HTTP 429
- Limits reset every 60 seconds
Error Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Wheel created |
400 | Bad request (missing/invalid params) |
404 | Wheel token not found |
429 | Rate limit exceeded |
Frequently Asked Questions
verification_url. Opening that URL confirms the winner, seed, and timestamp were not altered. For streamer use, you can also pass your own seed and let your audience verify the outcome independently by re-running the same seed against the same item list./api/v1/spin endpoint uses PHP's random_int() which draws from the operating system's CSPRNG (cryptographically secure pseudo-random number generator) — the same source as crypto.getRandomValues() in browsers.