Overview Architecture Entropy API Crypto Web3 Vault & Audit Enterprise Developers Portal Security Pricing
Request Access

Developer Guide

Wire the QSG entropy endpoint into your stack in minutes. Drop-in replacement for crypto.randomBytes() with signed provenance.

Quickstart

Three calls. No SDK install. Bring your own HTTP client.

1. Get a sandbox key

Request access at /access. You'll receive an API key (qsg_live_…) automatically.

2. Call the entropy endpoint

curl 
curl -X POST https://api.quantumsecuregateway.com/v1/entropy \
  -H "Authorization: Bearer qsg_live_…" \
  -H "Content-Type: application/json" \
  -d '{"format": "hex", "length": 32}'
JavaScript (fetch) 
const r = await fetch("https://api.quantumsecuregateway.com/v1/entropy", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.QSG_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ format: "hex", length: 32 })
});
const body = await r.json();
const { data, provenance, fallback } = body;
if (fallback.is_fallback) {
  console.warn(`CSPRNG fallback engaged: ${fallback.reason}`);
}
// data.entropy contains hex, base64, or raw bytes depending on format
Python (requests) 
import os, requests

r = requests.post(
    "https://api.quantumsecuregateway.com/v1/entropy",
    headers={"Authorization": f"Bearer {os.environ['QSG_API_KEY']}"},
    json={"format": "hex", "length": 32},
    timeout=5,
)
r.raise_for_status()
body = r.json()
if body["fallback"]["is_fallback"]:
    print(f"CSPRNG fallback engaged: {body['fallback']['reason']}")

3. Use the entropy bytes

The data.entropy field contains the requested bytes in the specified format. For "hex", decode from hex; for "base64", decode from base64. Feed into your key-derivation function or cryptographic library:

import base64

if body["data"]["format"] == "hex":
    raw = bytes.fromhex(body["data"]["entropy"])
else:
    raw = base64.b64decode(body["data"]["entropy"])
# now `raw` is 32 bytes suitable for HKDF / direct use

Encrypted Draw

POST /v1/entropy/encrypted performs a hybrid KEM (X25519 + ML-KEM-1024) and returns entropy encrypted to your public key. Private beta — enrollment is invite-only and requires a Verified, Verified+, or Enterprise tier key. Contact us to join.

curl 
curl -X POST https://api.quantumsecuregateway.com/v1/entropy/encrypted \
  -H "Authorization: Bearer qsg_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "base64",
    "length": 32,
    "suite": "QSG-HYBRID-1",
    "client_public_keys": {
      "x25519": "<base64url 32 bytes>",
      "ml_kem_1024": "<base64url 1568 bytes>"
    },
    "client_nonce": "<base64url >= 16 bytes>",
    "key_id": "my-key-001"
  }'

The response contains kem (with x25519_ephemeral_pk and mlkem1024_ciphertext), ciphertext, nonce, tag, and aad_hash. Derive the key via HKDF-SHA-256 (salt = SHA256(x25519_ephemeral_pk || mlkem1024_ciphertext), info = QSG-HYBRID-1|X25519+ML-KEM-1024|AES-256-GCM), then verify aad_hash and decrypt ciphertext + tag with AES-256-GCM.

Tier Requirements for Hardware Entropy

Hardware-derived entropy with signed provenance is a paid feature. There is no free access to real hardware entropy.

See Pricing for full tier breakdown.

Edge Workers Integration

If your workload runs on edge workers, route entropy calls through a service binding to keep latency sub-50 ms.

config.toml 
[[services]]
binding = "QSG"
service = "qsg-api-gateway"
environment = "production"
worker.js 
export default {
  async fetch(req, env) {
    const r = await env.QSG.fetch(
      new Request("https://internal/v1/entropy", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${env.QSG_API_KEY}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ format: "hex", length: 32 })
      })
    );
    return new Response(r.body, r);
  }
};

SDKs

First-party SDKs are planned. Until they ship, the endpoint is plain HTTP and works with any language.

Want early access? Email [email protected] with your language and use case.

Rate Limits

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

TierRequests / MinuteMax LengthBilling Multiplier
Public104,096 bytesFree
Builder1004,096 bytes1.0×
Standard1004,096 bytes1.0×
Standard+2004,096 bytes1.25×
Verified25016,384 bytes1.5×
Verified+50016,384 bytes1.75×
Enterprise1,00016,384 bytes2.0×

When you exceed a limit, the response is 429 with a Retry-After header indicating seconds until retry.

Error Handling

The API returns structured errors. Always check fallback.is_fallback in 200 responses.

JavaScript 
if (!response.ok) {
  const err = await response.json();
  switch (response.status) {
    case 401:
      throw new Error(`Auth failed: ${err.error}`);
    case 402:
      throw new Error(`Quota exceeded: ${err.error}. Upgrade at ${err.retryAfter}s.`);
    case 429:
      const retryAfter = err.retryAfter || 60;
      await sleep(retryAfter * 1000);
      break;
    case 503:
      console.warn(`Service degraded: ${err.error}`);
      break;
  }
}

// Even on 200, check fallback
const body = await response.json();
if (body.fallback?.is_fallback) {
  console.warn(`CSPRNG fallback: ${body.fallback.reason}`);
}

// For hardware guarantee, verify
if (body.provenance?.source_class !== 'hardware-derived') {
  // This is expected on Public tier; paid tiers should rarely see this
  console.warn('Draw not hardware-derived');
}

Web3 Integration

Use QSG entropy for wallet key generation, randomness beacons, and secure dApp operations.

Read the Web3 Gateway page for architecture and competitive comparison.

Next: API Reference

Full endpoint reference, error codes, provenance schema, and billing model.

API Reference