Skip to main content

Quick Start Guide

Get started with rng.dev in under 5 minutes.

1. Get an API Key​

Sign in with Google or GitHub at rng.dev/login.

Your dashboard shows:

  • API Key — copy this for authentication
  • ID Verification — optional, unlocks higher rate limits

No passwords. SSO only.

2. Authentication​

Include your API key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://rng.dev/api/v1/current

Without an API key, you're limited to 100 requests/day. Sign in to get higher limits.

3. Using the API​

Get the Current Random Value​

curl -H "X-API-Key: YOUR_API_KEY" https://rng.dev/api/v1/current

Response:

{
  "round": 12345678,
  "output_hash": "a3f2e8c9d1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0",
  "die_value": 4,
  "generated_at": "2026-03-09T15:00:00Z",
  "status": "complete",
  "sources_available": 6,
  "inputs": {
    "algorand": "34567890:QWERTY...XYZ",
    "avalanche": "12345678:0xabc123...",
    "bitcoin": "00000000000000000002a7c4...3f:831245",
    "cardano": "8765432:def456...",
    "ethereum": "0x8a3f2e...b9:19234567",
    "solana": "245678901:5eykt4Uy...Gno"
  }
}

To build explorer links, call /api/v1/meta once and cache it (see API Reference).

Get a Specific Round​

curl -H "X-API-Key: YOUR_API_KEY" https://rng.dev/api/v1/round/12345678

Get Just the Die Value​

curl -H "X-API-Key: YOUR_API_KEY" https://rng.dev/api/v1/simple

Response:

4

Real-Time Updates (WebSocket)​

const ws = new WebSocket('wss://rng.dev/ws/rounds');

ws.onmessage = (event) => {
  const round = JSON.parse(event.data);
  console.log(`New round: ${round.round}, die: ${round.die_value}`);
};

Response Fields​

FieldDescription
roundSequential round number (minutes since epoch)
output_hash256-bit SHA3 hash (64 hex characters)
die_valueFair die roll 1-6, derived from hash
generated_atISO 8601 timestamp
statuscomplete, partial, degraded, or failed
sources_availableNumber of blockchain sources used (out of 8)
inputsRaw blockchain inputs used to generate hash (for verification)

To build explorer links from inputs, use the templates from GET /api/v1/meta (call once and cache).

Rate Limits​

TierLimitHow to Get
Unauthenticated100/dayNo API key
Authenticated10,000/daySign in with SSO

Need higher limits? Contact us (requires sign-in).

Example Use Cases​

import requests

API_KEY = "your_api_key"
HEADERS = {"X-API-Key": API_KEY}

def pick_winner(participants: list[str]) -> str:
    """Pick a random winner using the beacon."""
    response = requests.get("https://rng.dev/api/v1/current", headers=HEADERS)
    data = response.json()

    hash_int = int(data["output_hash"][:16], 16)
    return participants[hash_int % len(participants)]

def coin_flip() -> str:
    """Verifiable coin flip."""
    response = requests.get("https://rng.dev/api/v1/current", headers=HEADERS)
    die_value = response.json()["die_value"]
    return "heads" if die_value <= 3 else "tails"

def get_seed(round_number: int) -> int:
    """Get a deterministic seed from a specific round."""
    response = requests.get(f"https://rng.dev/api/v1/round/{round_number}", headers=HEADERS)
    return int(response.json()["output_hash"], 16)

Client Libraries​

Official SDKs (coming soon):

LanguagePackageUse Case
Pythonpip install rng-beaconData science, ML/AI, backend
Rinstall.packages("rngbeacon")Statistics, research
JavaScriptnpm install @rng-dev/clientWeb frontends, Node.js

Other languages: The API is REST + JSON — any language with HTTP support works. See API Reference.

Next Steps​