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.

From your dashboard, create an API Key and copy it for authentication.

2. Make a Request​

With your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" https://rng.dev/api/v1/current

Or without (limited to 10 requests/hour):

curl https://rng.dev/api/v1/current

3. Response​

Example response:

{
  "round": 12345678,
  "output_hash": "a3f2e8c9d1b4a5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0",
  "die_value": 4,
  "generated_at": "2026-03-09T15:00:00Z",
  "status": "finalized",
  "sources_available": 8,
  "inputs": {
    "aptos": "12345678:0xabc123...:0xdef456...",
    "arbitrum": "442950038:0x9a877ac9...:0xa4b31d82...",
    "base": "43507585:0x6f0e768a...:0x63b60a42...",
    "bitcoin": "831245:00000000000000000002a7c4...3f:def4567890abc...",
    "cardano": "123456789:abc...:ghi7891234def...",
    "ethereum": "19234567:0x8a3f2e...b9:0x1a2b3c4d5e6f...",
    "solana": "245678901:5eykt4Uy...Gno:5VERv8NMvzbJMEkV...",
    "sui": "12345678:abc123...:def789..."
  }
}

To build blockchain explorer links from the inputs, see API Reference.

4. Other Endpoints​

Get a Specific Round​

curl -H "Authorization: Bearer YOUR_API_KEY" https://rng.dev/api/v1/round/12345678

Get Just the Die Value​

curl -H "Authorization: Bearer YOUR_API_KEY" https://rng.dev/api/v1/simple

Response:

4

Real-Time Updates (WebSocket)​

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

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

Response Fields​

FieldDescription
roundRound number (increments every second)
output_hashThe random hash (64 hex characters)
die_valueFair die roll 1-6
generated_atTimestamp (e.g., 2026-03-09T15:00:00Z)
statuscomplete, partial, degraded, or failed
sources_availableNumber of sources used (out of 8)
inputsBlockchain data used to generate the hash

Rate Limits​

TierLimitHow to Get
Unauthenticated10/hourNo API key needed
Authenticated100,000/daySign in and get an API key

Need higher limits? Contact us.

Example Use Cases​

import requests

API_KEY = "your_api_key"
HEADERS = {"Authorization": f"Bearer {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: Any language that can make HTTP requests works. See API Reference.

Next Steps​