Entropy API

Endpoint

POST/v1/entropy

Request

{
  "size_bytes": 32,
  "tier": "standard"
}

Headers

Authorization: Bearer qsg_live_… — API key issued at sandbox provisioning
Content-Type: application/json

Response (200)

{
  "entropy": "base64:aBcD...",
  "size_bytes": 32,
  "key_exchange": "X25519+ML-KEM-1024",
  "source_class": "hardware-derived-premium",
  "entropy_score": 0.999,
  "source_id": "qrng-hardware-001",
  "health_check": {
    "rct_passed": true,
    "apt_passed": true
  },
  "fallback": {
    "is_fallback": false,
    "reason": null,
    "original_source": null
  },
  "provenance_id": "prov_2026_06_23_abc123",
  "issued_at": "2026-06-23T14:22:08.117Z"
}

Status codes

200Success. Body contains entropy bytes and provenance metadata. 401Unauthorized. Missing or invalid API key. 402Payment required. Tier cap exceeded or billing suspended. 422Validation error. size_bytes out of range or unsupported tier. 429Rate limit exceeded. Retry after the value in Retry-After. 503Service degraded. Fallback path engaged; body still issued with fallback.is_fallback: true and fallback.reason populated.

Field Reference

size_bytes (int, request) — 1 to 1024 bytes per draw. Standard tier supports up to 256.
tier (enum, request) — "standard" | "verified" | "enterprise". Determines pool access, audit retention, and per-call weight.
entropy (string, response) — base64-encoded bytes. Cryptographically conditioned output, ready for downstream key generation.
key_exchange (string) — hybrid KEM negotiated for this response. Currently "X25519+ML-KEM-1024".
source_class (enum) — hardware-derived-premium | conditioned-archive-derived | hardware-derived | csprng-fallback.
entropy_score (float) — 0 to 1. Admission threshold: ≥ 0.99.
source_id (string) — opaque backend identifier (e.g. qrng-hardware-001).
health_check.rct_passed / health_check.apt_passed (bool) — SP 800-90B gating on the 1024-byte sample window.
fallback (object) — nested object, never flat. is_fallback: false on a normal draw; is_fallback: true with a reason code on fallback. original_source records what would have been served.
provenance_id (string) — record key for GET /v1/audit/:id (Verified and Enterprise tiers only).
issued_at (string) — ISO 8601 timestamp of the response.

Fallback Reasons

When fallback.is_fallback is true, the fallback.reason field carries one of these codes.

pool_unavailableReservoir is below the 1 MB threshold. Draw re-issued from CSPRNG. entropy_score_below_thresholdCandidate batch scored < 0.99 on min-entropy. Re-issued from CSPRNG. health_tests_failed:RCTSP 800-90B Repetition Count Test failed on the 1024-byte sample. Re-issued from CSPRNG. health_tests_failed:APTSP 800-90B Adaptive Proportion Test failed on the 1024-byte sample. Re-issued from CSPRNG. health_tests_failed:RCT,APTBoth tests failed. Re-issued from CSPRNG.

What Hardware Backs This?

IBM Quantum backends — Falcon, FEZ, Kingston, Brussels. Raw measurement output is conditioned by a Toeplitz extractor before admission. Per-batch min-entropy is estimated against the conditioning circuit; only batches scoring ≥ 0.99 are admitted to the reservoir.

NIST SP 800-90B Repetition Count Test (RCT) and Adaptive Proportion Test (APT) are run on a rolling 1024-byte sample. Failed tests force CSPRNG fallback regardless of entropy_score.

Pool byte-age cap: 14 days. Reservoir must hold at least 1 MB before a hardware-derived draw is admitted. Maximum consumption per draw: 90%.

For the full architectural breakdown, see Service Architecture.

Rate Limits

Per-API-key rolling-window limits. Burst capacity up to 2× for 5 seconds. Higher tiers available on request.

Tier	RPS	Daily
Builder	5	10,000
Standard	50	500,000
Standard+	200	5,000,000
Verified	50	500,000
Verified+	200	5,000,000
Enterprise	Custom	Custom

Get a sandbox key

Provisioned within 24–48 hours. Standard tier; full response shape; audit chain attached.

Request Access Developer Guide