Quickstart

Integrate hardware-extracted, cryptographically conditioned entropy into your application in minutes using our official Python and Node.js SDKs, or direct API endpoints.

Authentication

All requests to the Quey Cloud API require an API key. You can generate an API key from your Dashboard.

Authenticate your requests by providing your API key in a custom header named x-quey-key.

x-quey-key: qu_cloud_your_api_key_here

Installation (Python SDK)

The easiest way to interact with Quey is via our official Python SDK. Install the package via pip:

Initialize the client with your API key and request entropy:

from quey_random import QueyRandom

# Initialize the client with your secure Cloud API key
quey = QueyRandom(api_key="qu_cloud_your_api_key_here")

# Fetch 32 bytes (256 bits) of hardware-extracted entropy
seed = quey.get_bytes(32)
print(f"Entropy Seed: {seed.hex()}")

# Generate a uniform true random float for simulations
val = quey.random()
print(f"Photonic Entropy: {val}")

Installation (Node.js SDK)

You can also interact with Quey using our official Node.js/TypeScript SDK. Install the package via npm:

Initialize the client with your API key and request entropy:

import { QueyRandom } from 'quey-random';

// Initialize the client
const client = new QueyRandom('qu_cloud_your_api_key_here');

async function generateSeed() {
  // Request 32 bytes (256 bits) of hardware-extracted entropy
  const seedBuffer = await client.getBytes(32);
  
  console.log(`Entropy Seed: ${seedBuffer.toString('hex')}`);
  // Output: Entropy Seed: 7f8a9b2...
}

generateSeed();

Example: Monte-Carlo Simulation

Estimate π by sampling random points in the unit square. Pre-fetch a buffer for fast random() calls in tight loops.

from quey_random import QueyRandom

quey = QueyRandom(api_key="qu_cloud_your_api_key_here")

# Pre-fetch a buffer for fast random() calls
quey.prefetch(megabytes=10)

# Run 100k Monte-Carlo iterations to estimate π
inside = 0
for _ in range(100_000):
    x = quey.random()
    y = quey.random()
    if x*x + y*y <= 1:
        inside += 1

pi_estimate = 4 * inside / 100_000
print(f"π ≈ {pi_estimate}")

Example: Verifiable Raffle Draw

Pick winners from a participant list and obtain a signed verification certificate proving the draw used physical entropy.

import { QueyRandom } from 'quey-random';

const quey = new QueyRandom({ apiKey: process.env.QUEY_API_KEY });

// Draw 10 winners from 50,000 participants with a verifiable certificate
const draw = await quey.drawWithCertificate({
  participants: 50_000,
  winners: 10
});

console.log('Winners (indexes):', draw.winners);
console.log('Verification URL:', draw.certificateUrl);

Example: Cryptographic Seed Material

Get physical entropy bytes for use as input to a key derivation function (KDF), nonce material, or seed for cryptographic operations.

from quey_random import QueyRandom

quey = QueyRandom(api_key="qu_cloud_your_api_key_here")

# Get 64 bytes (512 bits) of physical entropy as seed material
seed = quey.get_bytes(64)

# Use as seed for KDF, key derivation, nonces, etc.
print(f"Seed (hex): {seed.hex()}")

Example: Bulk Entropy Download (cURL)

Download a large block of entropy as raw binary directly via REST. Useful for offline simulation seeding or batch jobs.

# Download a 1 MB block of entropy as binary
curl -X GET "https://api.queyquantum.io/v1/entropy/bulk?bytes=1048576" \
  -H "X-Quey-Token: qu_cloud_your_api_key_here" \
  --output entropy_block.bin

# Verify entropy quality locally
sha256sum entropy_block.bin

REST API

For environments where the SDK is not available, you can interact directly with our REST API to fetch raw entropy blocks.

curl -X GET "https://us-central1-quey-deb85.cloudfunctions.net/getQuantumEntropy?size=32" \
  -H "x-quey-key: qu_cloud_your_api_key_here"

{
  "status": "success",
  "bytes_returned": 32,
  "entropy_hex": "7f8a9b2c4e5f6d7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
  "node_id": "quey_edge_01"
}

Verifiable Draw Endpoints

Three endpoints let you produce, fetch, and verify cryptographically signed selection certificates from physical entropy. Every certificate is Ed25519-signed by Quey and independently verifiable in any modern browser via WebCrypto.

POST verifiableDraw

curl -X POST "https://verifiabledraw-33ssvbagba-uc.a.run.app" \
  -H "x-quey-key: qu_cloud_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "list",
    "num_winners": 3,
    "participants": ["alice@example.com", "bob@example.com", "carol@example.com", "dave@example.com", "eve@example.com"]
  }'

curl -X POST "https://verifiabledraw-33ssvbagba-uc.a.run.app" \
  -H "x-quey-key: qu_cloud_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "index",
    "num_winners": 3,
    "total_count": 5,
    "input_hash": "3e85a73e8c1f3c6d9d7b1a2f4e5c8b9d0a1f2e3d4c5b6a7d8e9f0a1b2c3d4e5f"
  }'

{
  "status": "success",
  "certificate": {
    "version": 1,
    "draw_id": "89421ffc-6af3-427e-8123-fa6c799cc166",
    "timestamp": "2026-05-26T14:32:11.482Z",
    "input_hash": "3e85a73e8c1f3c6d9d7b1a2f4e5c8b9d0a1f2e3d4c5b6a7d8e9f0a1b2c3d4e5f",
    "total_participants": 5,
    "num_winners": 3,
    "winning_indices": [0, 2, 4],
    "entropy_consumed_bytes": 2,
    "key_id": "1ec2b73ecd9dab6e",
    "signature": "a3f9c2e5d8b1f4a7...",
    "verify_url": "https://queyquantum.io/verify/89421ffc-6af3-427e-8123-fa6c799cc166"
  }
}

GET getDrawCertificate

curl "https://getdrawcertificate-33ssvbagba-uc.a.run.app?id=89421ffc-6af3-427e-8123-fa6c799cc166"

{
  "version": 1,
  "draw_id": "89421ffc-6af3-427e-8123-fa6c799cc166",
  "timestamp": "2026-05-26T14:32:11.482Z",
  "input_hash": "3e85a73e8c1f3c6d9d7b1a2f4e5c8b9d0a1f2e3d4c5b6a7d8e9f0a1b2c3d4e5f",
  "total_participants": 5,
  "num_winners": 3,
  "winning_indices": [0, 2, 4],
  "entropy_consumed_bytes": 2,
  "key_id": "1ec2b73ecd9dab6e",
  "signature": "a3f9c2e5d8b1f4a7...",
  "verify_url": "https://queyquantum.io/verify/89421ffc-6af3-427e-8123-fa6c799cc166"
}

GET getPublicKey

curl "https://getpublickey-33ssvbagba-uc.a.run.app"

{
  "algorithm": "Ed25519",
  "public_key_hex": "4fad999c2b586aab53155afc97f564a231350087b4c66d6a8f868963f42caf15",
  "key_id": "1ec2b73ecd9dab6e"
}

Verifying a Certificate

You can verify any Quey-issued draw without trusting Quey — the signature check runs entirely in your environment against a published public key.

Easy path — in the browser

Share or open https://queyquantum.io/verify/<draw_id>. The verification page fetches the certificate and the public key, then runs Ed25519 verification locally via crypto.subtle.verify (WebCrypto). No server-side check, no trust required.

Manual path — five steps

1. Fetch the certificate: GET getDrawCertificate?id=<draw_id>
2. Fetch the public key: GET getPublicKey
3. Confirm cert.key_id === keyData.key_id. If not, refuse the certificate — it was signed with a different key.
4. Reconstruct the canonical payload (see format below).
5. Verify the Ed25519 signature against the canonical payload using the public key. Pass = authentic and untampered; fail = reject.

Canonical payload format

The payload signed by Quey is a pipe-delimited UTF-8 string. Field order is fixed; whitespace, BOM, or trailing newlines must not be added.

QUEY-DRAW-CERT-V1|{draw_id}|{timestamp}|{input_hash}|{total_participants}|{num_winners}|{winning_indices_csv}|{entropy_consumed_bytes}|{key_id}

• QUEY-DRAW-CERT-V1 — fixed version tag.
• winning_indices_csv — indices joined by "," with no spaces (e.g. "0,2,4").
• Integers are serialized with String(n) (no leading zeros, no thousands separators).

Reference: JavaScript verification snippet

// Fetch certificate and public key, then verify locally.
const [certRes, keyRes] = await Promise.all([
  fetch(`https://getdrawcertificate-33ssvbagba-uc.a.run.app?id=${drawId}`),
  fetch('https://getpublickey-33ssvbagba-uc.a.run.app')
]);
const cert = await certRes.json();
const keyData = await keyRes.json();

if (cert.key_id !== keyData.key_id) throw new Error('key_id mismatch');

const canonical = [
  'QUEY-DRAW-CERT-V1',
  cert.draw_id, cert.timestamp, cert.input_hash,
  String(cert.total_participants),
  String(cert.num_winners),
  cert.winning_indices.join(','),
  String(cert.entropy_consumed_bytes),
  cert.key_id
].join('|');

const hexToBytes = (h) =>
  Uint8Array.from(h.match(/../g).map(b => parseInt(b, 16)));

const pubKey = await crypto.subtle.importKey(
  'raw', hexToBytes(keyData.public_key_hex),
  { name: 'Ed25519' }, false, ['verify']
);

const ok = await crypto.subtle.verify(
  'Ed25519', pubKey,
  hexToBytes(cert.signature),
  new TextEncoder().encode(canonical)
);
console.log(ok ? 'authentic' : 'tampered');