REST API Reference

Base URL: https://rng.dev/api/v1

Endpoints

GET /current

Returns the most recent generated round, including all inputs for verification.

Response:

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

Response Fields

Field	Description
`output_hash`	SHA3-256 hash of combined blockchain inputs
`die_value`	Die value (1-6) derived from hash using rejection sampling
`inputs`	Combined block hash and transaction ID inputs for each chain

The inputs field contains the exact strings used to generate output_hash. Each chain's input includes block data and transaction ID in the format specified in How It Works. See Verification Guide to verify any round independently.

GET /round/{round_number}

Returns a specific historical round, including all inputs for verification.

Parameters:

Name	Type	Description
`round_number`	integer	The round number to fetch

Example:

curl https://rng.dev/api/v1/round/12345678

Response:

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

GET /simple

Returns just the current die value as plain text.

Response:

Useful for simple integrations or shell scripts:

DIE=$(curl -s https://rng.dev/api/v1/simple)
echo "The die shows: $DIE"

GET /health

Returns service health status.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "last_round": 12345678,
  "last_round_at": "2026-03-09T15:00:00Z",
  "sources": {
    "aptos": "ok",
    "bitcoin": "ok",
    "cardano": "ok",
    "ethereum": "ok",
    "solana": "ok",
    "sui": "ok"
  }
}

GET /health/gaps

Returns information about any missing rounds in the sequence.

Response:

{
  "has_gaps": false,
  "total_rounds": 12345678,
  "missing_rounds": [],
  "last_checked": "2026-03-09T15:00:00Z"
}

Response with gaps:

{
  "has_gaps": true,
  "total_rounds": 12345678,
  "missing_rounds": [12345600, 12345601],
  "gap_reason": "source_unavailability",
  "last_checked": "2026-03-09T15:00:00Z"
}

GET /meta

Returns static metadata about the beacon service. Call once and cache — this data rarely changes.

Response:

{
  "version": "2.0.0",
  "sources": ["aptos", "bitcoin", "cardano", "ethereum", "solana", "sui"],
  "explorers": {
    "aptos": "https://explorer.aptoslabs.com/block/{block}",
    "bitcoin": "https://mempool.space/block/{hash}",
    "cardano": "https://cardanoscan.io/block/{block}",
    "ethereum": "https://etherscan.io/block/{block}",
    "solana": "https://solscan.io/block/{slot}",
    "sui": "https://suiscan.xyz/mainnet/checkpoint/{checkpoint}"
  },
  "tx_explorers": {
    "aptos": "https://explorer.aptoslabs.com/txn/{txid}",
    "bitcoin": "https://mempool.space/tx/{txid}",
    "cardano": "https://cardanoscan.io/transaction/{txid}",
    "ethereum": "https://etherscan.io/tx/{txid}",
    "solana": "https://solscan.io/tx/{txid}",
    "sui": "https://suiscan.xyz/mainnet/tx/{txid}"
  },
  "input_format": {
    "aptos": "{block_height}:{block_hash}:{txid}",
    "bitcoin": "{block_height}:{block_hash}:{txid}",
    "cardano": "{slot}:{block_hash}:{txid}",
    "ethereum": "{block_number}:{block_hash}:{txid}",
    "solana": "{slot}:{blockhash}:{txid}",
    "sui": "{checkpoint}:{digest}:{txid}"
  },
  "tx_selection": {
    "aptos": { "index": 0, "description": "First transaction" },
    "bitcoin": { "index": 1, "description": "Second transaction (skip coinbase)" },
    "cardano": { "index": 0, "description": "First transaction" },
    "ethereum": { "index": 0, "description": "First transaction" },
    "solana": { "index": 0, "description": "First transaction" },
    "sui": { "index": 0, "description": "First transaction" }
  },
  "combination_order": ["aptos", "bitcoin", "cardano", "ethereum", "solana", "sui"],
  "combination_separator": "|",
  "hash_algorithm": "SHA3-256"
}

Use explorers templates to build verification links from inputs values.

Statistics Endpoints

GET /stats/distribution

Returns die value distribution statistics.

Parameters:

Name	Type	Default	Description
`rounds`	integer	1000	Number of recent rounds to analyze

Response:

{
  "rounds_analyzed": 1000,
  "distribution": {
    "1": 168,
    "2": 165,
    "3": 167,
    "4": 166,
    "5": 167,
    "6": 167
  },
  "expected": 166.67,
  "chi_squared": {
    "statistic": 0.072,
    "p_value": 0.9995,
    "degrees_of_freedom": 5
  },
  "status": "PASS"
}

GET /stats/streaks

Returns streak distribution analysis.

Parameters:

Name	Type	Default	Description
`rounds`	integer	1000	Number of recent rounds to analyze

Response:

{
  "rounds_analyzed": 1000,
  "streaks": {
    "1": 833,
    "2": 139,
    "3": 23,
    "4": 4,
    "5": 1
  },
  "expected_geometric": {
    "1": 833.3,
    "2": 138.9,
    "3": 23.1,
    "4": 3.9,
    "5": 0.6
  },
  "status": "PASS"
}

GET /stats/transitions

Returns transition matrix between consecutive die values.

Parameters:

Name	Type	Default	Description
`rounds`	integer	1000	Number of recent rounds to analyze

Response:

{
  "rounds_analyzed": 1000,
  "matrix": [
    [28, 27, 28, 28, 28, 28],
    [27, 28, 27, 28, 28, 27],
    [28, 28, 27, 28, 27, 28],
    [27, 28, 28, 27, 28, 28],
    [28, 27, 28, 28, 27, 28],
    [28, 28, 28, 27, 28, 27]
  ],
  "expected": 27.78,
  "chi_squared": {
    "statistic": 0.36,
    "p_value": 1.0,
    "degrees_of_freedom": 25
  },
  "status": "PASS"
}

GET /stats/autocorrelation

Returns autocorrelation analysis for sequence independence.

Parameters:

Name	Type	Default	Description
`lags`	integer	20	Number of lag values to compute

Response:

{
  "rounds_analyzed": 10000,
  "autocorrelations": {
    "1": 0.003,
    "2": -0.002,
    "3": 0.001,
    "...": "...",
    "20": -0.001
  },
  "confidence_bound": 0.02,
  "significant_lags": [],
  "status": "PASS"
}

GET /stats/randomness

Comprehensive randomness statistics for monitoring and AI agents.

Response:

{
  "_meta": {
    "schema_version": "1.0",
    "generated_at": "2026-03-09T15:00:00Z",
    "beacon_round": 12345678
  },
  "summary": {
    "overall_status": "PASS",
    "plain_english": "The beacon is behaving like a fair random source with no detectable bias."
  },
  "rolling_windows": {
    "last_100": { "...": "..." },
    "last_1000": { "...": "..." },
    "last_100000": { "...": "..." }
  },
  "comparisons": {
    "beacon_vs_drand": {
      "ks_statistic": 0.012,
      "p_value": 0.87,
      "status": "PASS"
    },
    "beacon_vs_nist": {
      "ks_statistic": 0.011,
      "p_value": 0.84,
      "status": "PASS"
    }
  }
}

Response Codes

Code	Meaning
200	Success
400	Bad request (invalid parameters)
404	Round not found
429	Rate limit exceeded
500	Server error
503	Service unavailable (generation paused)

Rate Limiting

Tier	Limit
Unauthenticated	100/day
Authenticated	10,000/day

Include your API key in the X-API-Key header to authenticate. Need higher limits? Contact us.

Rate limit headers are included in responses:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9423
X-RateLimit-Reset: 1709996400

Status Values

Status	Description
`complete`	All 8 sources contributed
`partial`	4-5 sources contributed
`degraded`	2-3 sources contributed (use with caution)
`failed`	Round could not be generated
`missed`	Round was skipped (historical gap)

Error Responses

{
  "error": {
    "code": "ROUND_NOT_FOUND",
    "message": "Round 99999999 does not exist",
    "details": {
      "requested_round": 99999999,
      "latest_round": 12345678
    }
  }
}

CORS

The API supports CORS for browser-based applications:

Allowed origins: * (all origins)
Allowed methods: GET, OPTIONS
Allowed headers: Content-Type, Authorization

OpenAPI Specification

Full OpenAPI 3.0 specification available at:

Swagger UI: https://api.rng.dev/docs
ReDoc: https://api.rng.dev/redoc
JSON: https://api.rng.dev/openapi.json

Endpoints​

GET /current​

Response Fields​

GET /round/{round_number}​

GET /simple​

GET /health​

GET /health/gaps​

GET /meta​

Statistics Endpoints​

GET /stats/distribution​

GET /stats/streaks​

GET /stats/transitions​

GET /stats/autocorrelation​

GET /stats/randomness​

Response Codes​

Rate Limiting​

Status Values​

Error Responses​

CORS​

OpenAPI Specification​

Endpoints

GET /current

Response Fields

GET /round/{round_number}

GET /simple

GET /health

GET /health/gaps

GET /meta

Statistics Endpoints

GET /stats/distribution

GET /stats/streaks

GET /stats/transitions

GET /stats/autocorrelation

GET /stats/randomness

Response Codes

Rate Limiting

Status Values

Error Responses

CORS

OpenAPI Specification