API Reference

Quantropy exposes a single primary endpoint for verifiable quantum entropy. This page describes the endpoint, authentication, and response shape at a conceptual level. For exact URLs and live specs, use your dashboard or the integration docs at quantropylab.com.

Base URL and protocols

• REST — HTTP/HTTPS; typical base path /v1 (e.g. https://api.quantropylab.com/v1 or your assigned host). See quantropylab.com for current endpoints.

• gRPC — Same API surface over gRPC for lower latency and streaming where supported.

Use REST for simplicity; use gRPC when you need minimal latency or programmatic contracts.

Authentication

All requests require authentication. Typical methods:

• API key — Send in the Authorization header: Authorization: Bearer YOUR_API_KEY.

• Key in header — Some deployments use a custom header (e.g. X-API-Key); check your integration docs.

Without a valid key, requests return 401 Unauthorized.

Primary endpoint: Request entropy

Purpose: Request a block of verifiable quantum entropy and receive the bytes plus provenance (Quantum Job ID, Solana tx).

REST (conceptual)

GET /v1/entropy?size=32
Authorization: Bearer YOUR_API_KEY

Query parameters (typical):

Parameter	Type	Description
size	integer	Requested entropy size in bytes (e.g. 32 for 256 bits). Subject to min/max limits.

Response shape (conceptual)

{
  "job_id": "qj_...",
  "entropy": "<base64 or hex-encoded bytes>",
  "solana_tx": "<transaction signature or ID>",
  "timestamp": "<ISO 8601>"
}

Field	Description
job_id	Quantum Job ID — use it to verify this request on-chain. See Quantum Provenance.
entropy	The requested random bytes (base64 or hex). High-fidelity, from real quantum measurements.
solana_tx	Solana transaction that anchors this job; enables full auditability.
timestamp	Server-side timestamp for the job.

Exact field names and encodings may vary; treat this as the canonical shape.

Rate limits

The API is rate-limited per key (and possibly per IP). Typical behavior:

• Limit — e.g. N requests per second or per minute; see your dashboard or docs.

• Response — 429 Too Many Requests when over limit; retry after the indicated delay (see Error Handling).

Spending $QPY

Each entropy request consumes $QPY (spend-and-burn). Your key is tied to an account or balance; insufficient balance returns an error (e.g. 402 Payment Required or a custom code). See Spend and Burn.

Provenance and verification

Every response includes Quantum Job ID and Solana transaction. Use them to:

• Verify the job on-chain via Quantum Explorer or a Solana RPC.

• Store with your use of the entropy (e.g. game round, lottery, AI run) for auditability.

For SDK usage: SDK Libraries. For errors and retries: Error Handling.