# Qrypt quantum entropy quickstart (for AI agents)
> Get an AES-256-GCM key from Qrypt quantum entropy. Plain HTTPS; no SDK exists for this API. Do not invent one.

## FIRST: secrets and layout
- If .env exists, it already has the token. Do NOT read or print it in any form (no cat/head/sed/less, not even masked). Only check: grep -q '^QRYPT_API_KEY=.' .env && echo set
- Write all files in the current directory next to .env. No subfolder, no copying .env.
- If .env gives "Permission denied", you are in the Qrypt agent sandbox ON PURPOSE. Do not try to read it or work around it. Run your program with: qrypt-run quickstart.py (or qrypt-run quickstart.mjs). Only qrypt-run can read .env.
- Humans: to keep agents from reading .env, run the agent in the sandbox: see "Using an AI coding agent?" on the quickstart page (files at /agent-sandbox/).

## API
GET https://api-eus.qrypt.com/api/v1/quantum-entropy?size=1
Headers: Authorization: Bearer $QRYPT_API_KEY ; Accept: application/json
Response: {"random": ["<base64>"], "size": 1}. Each string decodes (standard base64) to 1024 bytes.
size counts KiB (1..512), NOT bytes. For one AES-256 key use size=1 and take the first 32 decoded bytes.

## Rules
- Python: use `requests` or set a custom User-Agent. Cloudflare blocks Python-urllib with 403 Error 1010.
- Read the token from .env (QRYPT_API_KEY). Never print, log or commit the token or key.
- Never show .env or any part of it (no `cat .env`, no `head -c N .env`). To check it is set: `grep -q '^QRYPT_API_KEY=.' .env && echo set`
- Build the project in the directory that already holds .env. Do not copy .env into a new subfolder.
- 400 bad size; 401 missing/malformed Authorization header; 403 wrong token OR quota reached (bad tokens return 403, not 401);
  429 rate limited (docs: 30 req/10 s, but live can return 429 about 1 s after a single prior call; no Retry-After): wait 10 s or more and never loop; 500/503 try again shortly. Exit non-zero on error.

## Python (isolated install: python3 -m venv .venv && .venv/bin/pip install requests cryptography python-dotenv; run with .venv/bin/python)
# Qrypt quickstart (Python): turn 1 KiB of quantum entropy into an AES-256-GCM key.
# Needs: pip install -r requirements.txt  and a .env file with QRYPT_API_KEY=...
import base64, os, sys
import requests
from dotenv import load_dotenv
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

load_dotenv()
token = os.getenv("QRYPT_API_KEY")
if not token:
    sys.exit("QRYPT_API_KEY is missing. Copy .env.example to .env and paste your token from portal.qrypt.com.")
base = os.getenv("QRYPT_BASE_URL", "https://api-eus.qrypt.com")  # override only for the mock server
# size is in KiB, not bytes: size=1 returns 1,024 bytes. A custom User-Agent avoids Cloudflare's urllib block.
try:
    r = requests.get(f"{base}/api/v1/quantum-entropy", params={"size": 1}, timeout=15, headers={
        "Authorization": f"Bearer {token}", "Accept": "application/json",
        "User-Agent": "qrypt-quickstart/1.0", "X-Qrypt-Client": "quickstart-py/1.0"})
    data = r.json() if r.status_code == 200 else None
except (requests.RequestException, ValueError) as e:
    sys.exit(f"Network error or non-JSON reply from Qrypt ({type(e).__name__}). Check your connection, proxy or TLS settings, then try again shortly.")
errors = {
    400: "400 Bad request: size must be an integer from 1 to 512 (it counts KiB, not bytes).",
    401: "401 Missing, malformed or expired token header: it must be 'Bearer <token>'.",
    403: "403 Token invalid OR monthly quota reached. Check the token first (Qrypt returns 403 for a wrong token, not 401).",
    429: "429 Rate limited. Live can return 429 about 1 s after a single prior call; wait 10 s or more and never loop.",
    500: "500 Qrypt internal error. Try again shortly; contact support@qrypt.com if it persists.",
    503: "503 Qrypt entropy supply is temporarily low. Try again shortly."}
if r.status_code != 200:
    sys.exit(errors.get(r.status_code, f"Unexpected HTTP {r.status_code}. See the troubleshooting page."))
key = base64.b64decode(data["random"][0])[:32]  # decode first, then take 32 bytes = AES-256 key
aes, nonce, message = AESGCM(key), os.urandom(12), b"hello, quantum entropy"
assert aes.decrypt(nonce, aes.encrypt(nonce, message, None), None) == message
print("Success: AES-256-GCM round trip with a Qrypt entropy key (key not shown).")

## Node 20.12+ (no deps)
// Qrypt quickstart (Node 20.12+): turn 1 KiB of quantum entropy into an AES-256-GCM key.
// No dependencies. Needs a .env file with QRYPT_API_KEY=...
import { existsSync } from "node:fs";
import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";

if (existsSync(".env")) process.loadEnvFile(".env");
const fail = (msg) => { console.error(msg); process.exit(1); }, token = process.env.QRYPT_API_KEY;
if (!token) fail("QRYPT_API_KEY is missing. Copy .env.example to .env and paste your token from portal.qrypt.com.");
const base = process.env.QRYPT_BASE_URL ?? "https://api-eus.qrypt.com"; // override only for the mock server
// size is in KiB, not bytes: size=1 returns 1,024 bytes.
let res, body;
try {
  res = await fetch(`${base}/api/v1/quantum-entropy?size=1`, { headers: {
  Authorization: `Bearer ${token}`, Accept: "application/json",
  "User-Agent": "qrypt-quickstart/1.0", "X-Qrypt-Client": "quickstart-js/1.0" } });
  body = res.status === 200 ? await res.json() : null;
} catch (e) { fail(`Network error or non-JSON reply from Qrypt (${e.cause?.code ?? e.name}). Check your connection, proxy or TLS settings, then try again shortly.`); }
const errors = {
  400: "400 Bad request: size must be an integer from 1 to 512 (it counts KiB, not bytes).",
  401: "401 Missing, malformed or expired token header: it must be 'Bearer <token>'.",
  403: "403 Token invalid OR monthly quota reached. Check the token first (Qrypt returns 403 for a wrong token, not 401).",
  429: "429 Rate limited. Live can return 429 about 1 s after a single prior call; wait 10 s or more and never loop.",
  500: "500 Qrypt internal error. Try again shortly; contact support@qrypt.com if it persists.",
  503: "503 Qrypt entropy supply is temporarily low. Try again shortly." };
if (res.status !== 200) fail(errors[res.status] ?? `Unexpected HTTP ${res.status}. See the troubleshooting page.`);
const key = Buffer.from(body.random[0], "base64").subarray(0, 32); // decode, then 32 bytes
const iv = randomBytes(12), msg = "hello, quantum entropy";
const c = createCipheriv("aes-256-gcm", key, iv), ct = Buffer.concat([c.update(msg), c.final()]);
const d = createDecipheriv("aes-256-gcm", key, iv); d.setAuthTag(c.getAuthTag());
if (Buffer.concat([d.update(ct), d.final()]).toString() !== msg) fail("Round trip failed.");
console.log("Success: AES-256-GCM round trip with a Qrypt entropy key (key not shown).");

## More
Troubleshooting: /troubleshooting