Python SDK
The official QuantumSafe SDK for Python. Uses real PQC implementations via the pqcrypto library.
Installation
Requires Python 3.9+. The pqcrypto C extension is compiled during installation and requires a C compiler (gcc/clang).
Initialization
from quantumsafe import QuantumSafe
qs = QuantumSafe(
api_key="qs_sec_live_sk_abc123...",
timeout=30, # Request timeout in seconds (default: 30)
)
Configuration Options
| Option | Type | Required | Default | Description |
|---|
api_key | str | Yes | — | Your API key |
timeout | int | No | 30 | Request timeout in seconds |
base_url | str | No | — | Custom API base URL (overrides network) |
Key Generation
Generate PQC key pairs locally. The private key never leaves your device.
keypair = qs.keys.generate(
algorithm="ml-dsa-65",
chain="ethereum",
format="hex",
)
print(keypair.public_key) # "0x7a2b3c..."
print(keypair.private_key) # "0x1a2b3c..." — store securely!
print(keypair.algorithm) # "ml-dsa-65"
print(keypair.key_id) # "key_abc123"
The SDK uses the secrets module (backed by os.urandom()) for all cryptographic randomness. The standard random module is never used for key material. Attempting to patch the RNG will raise a SecurityError.
Parameters
| Option | Type | Required | Description |
|---|
algorithm | str | Yes | ml-dsa-44, ml-dsa-65, ml-dsa-87, slh-dsa-128s |
chain | str | Yes | ethereum, bitcoin, solana, polygon, avalanche |
format | str | No | hex (default), base64, raw |
Hybrid Signing
Create a dual ECDSA + PQC attestation.
attestation = qs.sign.hybrid(
message="0xdeadbeef",
ecdsa_signature="0x3045022100...",
ecdsa_public_key="0x04a1b2c3...",
pqc_private_key=keypair.private_key,
pqc_public_key=keypair.public_key,
algorithm="ml-dsa-65",
chain="ethereum",
metadata={
"tx_hash": "0xabc123...",
"label": "Transfer approval",
},
)
print(attestation.id) # "att_abc123..."
print(attestation.status) # "verified"
Parameters
| Option | Type | Required | Description |
|---|
message | str | Yes | Message to sign (hex-encoded) |
ecdsa_signature | str | Yes | Existing ECDSA signature |
ecdsa_public_key | str | Yes | ECDSA public key |
pqc_private_key | str | Yes | Your PQC private key |
pqc_public_key | str | Yes | Your PQC public key |
algorithm | str | Yes | PQC algorithm |
chain | str | No | Target chain (default: ethereum) |
metadata | dict | No | Arbitrary metadata |
Verification
Verify a hybrid attestation.
# By attestation ID
result = qs.verify(attestation_id="att_abc123...")
# By raw components
result = qs.verify(
message="0xdeadbeef",
ecdsa_signature="0x3045022100...",
ecdsa_public_key="0x04a1b2c3...",
pqc_signature="0x7a8b9c0d...",
pqc_public_key="0x1a2b3c4d...",
algorithm="ml-dsa-65",
)
print(result.valid) # True
print(result.ecdsa_valid) # True
print(result.pqc_valid) # True
Wallet Scanning
Scan an address for quantum vulnerability.
scan = qs.scan.wallet(
address="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
chain="ethereum",
)
print(scan.risk_score) # "W3"
print(scan.risk_label) # "High"
print(scan.chain_grade) # "C"
print(scan.risk_factors) # [{"factor": "public_key_exposure", ...}, ...]
Wallet scanning works with both Publishable and Secret keys, making it suitable for user-facing applications.
Error Handling
from quantumsafe.exceptions import QuantumSafeError
try:
keypair = qs.keys.generate(
algorithm="ml-dsa-65",
chain="ethereum",
)
except QuantumSafeError as err:
print(err.code) # "AUTH_003"
print(err.message) # "Insufficient permissions"
print(err.status) # 403
Async Support
The SDK provides an async client for use with asyncio:
from quantumsafe import AsyncQuantumSafe
qs = AsyncQuantumSafe(
api_key="qs_sec_live_sk_abc123...",
network="mainnet",
)
async def main():
keypair = await qs.keys.generate(
algorithm="ml-dsa-65",
chain="ethereum",
)
print(keypair.public_key)
import asyncio
asyncio.run(main())
PQC Implementation
The Python SDK uses real PQC implementations via the pqcrypto library, which provides:
- ML-DSA (FIPS 204): Lattice-based digital signatures
- SLH-DSA (FIPS 205): Hash-based digital signatures
All cryptographic operations are performed in C for performance and correctness.
