Metadata-Version: 2.4
Name: getquantumrand
Version: 1.0.3
Summary: Python SDK for the QuantumRand API — quantum-seeded randomness, with every value labelled by its source
License: MIT
Project-URL: Homepage, https://quantumrand.dev
Project-URL: Repository, https://github.com/getquantumrand/quantumrand-sdks
Project-URL: Documentation, https://quantumrand.dev/docs
Keywords: quantum,random,qrng,cryptography,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24

# getquantumrand — Python SDK

Quantum-seeded randomness from [QuantumRand](https://quantumrand.dev): a NIST DRBG seeded from real IBM quantum hardware, with every value labelled by the source that produced it.

## Install

```bash
pip install getquantumrand
```

## Quick Start

```python
from getquantumrand import QuantumRandClient

qr = QuantumRandClient("qr_your_api_key")

# Generate 256 quantum random bits
bits = qr.bits(256)

# Random hex string
hex_str = qr.hex(128)

# Random integer in range
number = qr.integer(1, 100)

# Cryptographic key (AES-256)
key = qr.key(256)

# Batch: multiple values in one call
results = qr.batch([
    {"type": "bits", "params": {"n": 64}},
    {"type": "integer", "params": {"min": 1, "max": 6}},
    {"type": "integer", "params": {"min": 1, "max": 6}},
])

# Async webhook delivery
qr.webhook("https://your-app.com/webhook", type="key", params={"bits": 256})

# Usage stats
print(qr.stats())
```

## Configuration

```python
qr = QuantumRandClient(
    api_key="qr_your_key",
    base_url="https://quantumrand.dev",  # default
    backend=None,  # default: the server's quantum-seeded source
    timeout=30.0,
)
```

Leave `backend` unset to get the quantum-seeded default. Set it only to request a
specific engine, e.g. `"aer_simulator"` (a simulator).

## Where your randomness came from

Every response is labelled with its source. The client keeps the label of the
most recent call:

```python
key = qr.key(256)
print(qr.last_source)  # "quantum-seeded", or e.g. "csprng-fallback (...)"
```

If a fresh quantum seed is unavailable (for example, briefly after a restart),
the service falls back to the operating system's secure generator and says so
in this label.

## Get a Free API Key

```bash
curl -X POST https://quantumrand.dev/keys/create \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@example.com"}'
```
