​
TypeScript SDK

The official QuantumSafe SDK for TypeScript and JavaScript environments.

​
Installation

npm install @quantumsafe/sdk
Requires Node.js 18+ or a browser with Web Crypto API support.

​
Initialization

import { QuantumSafe } from "@quantumsafe/sdk";

const qs = new QuantumSafe({
  apiKey: "qs_sec_live_sk_abc123...",
  network: "mainnet",       // "mainnet" | "testnet"
  timeout: 30000,           // Request timeout in ms (default: 30000)
});

​
Configuration Options

OptionTypeRequiredDefaultDescription
apiKeystringYes—Your API key
networkstringNomainnetmainnet or testnet
timeoutnumberNo30000Request timeout in milliseconds
baseUrlstringNo—Custom API base URL (overrides network)

​
Key Generation

Generate PQC key pairs locally. The private key never leaves your device. 
const keypair = await qs.keys.generate({
  algorithm: "ml-dsa-65",
  chain: "ethereum",
  format: "hex",
});

console.log(keypair.publicKey);   // "0x7a2b3c..."
console.log(keypair.privateKey);  // "0x1a2b3c..." — store securely!
console.log(keypair.algorithm);   // "ml-dsa-65"
console.log(keypair.keyId);       // "key_abc123"
The SDK uses crypto.getRandomValues() (Web Crypto CSPRNG) for all key generation. Math.random() is explicitly banned — the SDK will throw an error if the Web Crypto API is unavailable.

​
Parameters

OptionTypeRequiredDescription
algorithmstringYesml-dsa-44, ml-dsa-65, ml-dsa-87, slh-dsa-128s
chainstringYesethereum, bitcoin, solana, polygon, avalanche
formatstringNohex (default), base64, raw

​
Hybrid Signing

Create a dual ECDSA + PQC attestation. 
const attestation = await qs.sign.hybrid({
  message: "0xdeadbeef",
  ecdsaSignature: "0x3045022100...",
  ecdsaPublicKey: "0x04a1b2c3...",
  pqcPrivateKey: keypair.privateKey,
  pqcPublicKey: keypair.publicKey,
  algorithm: "ml-dsa-65",
  chain: "ethereum",
  metadata: {
    txHash: "0xabc123...",
    label: "Transfer approval",
  },
});

console.log(attestation.id);      // "att_abc123..."
console.log(attestation.status);  // "verified"

​
Parameters

OptionTypeRequiredDescription
messagestringYesMessage to sign (hex-encoded)
ecdsaSignaturestringYesExisting ECDSA signature
ecdsaPublicKeystringYesECDSA public key
pqcPrivateKeystringYesYour PQC private key
pqcPublicKeystringYesYour PQC public key
algorithmstringYesPQC algorithm
chainstringNoTarget chain (default: ethereum)
metadataobjectNoArbitrary metadata

​
Verification

Verify a hybrid attestation. 
// By attestation ID
const result = await qs.verify({
  attestationId: "att_abc123...",
});

// By raw components
const result = await qs.verify({
  message: "0xdeadbeef",
  ecdsaSignature: "0x3045022100...",
  ecdsaPublicKey: "0x04a1b2c3...",
  pqcSignature: "0x7a8b9c0d...",
  pqcPublicKey: "0x1a2b3c4d...",
  algorithm: "ml-dsa-65",
});

console.log(result.valid);       // true
console.log(result.ecdsaValid);  // true
console.log(result.pqcValid);    // true

​
Wallet Scanning

Scan an address for quantum vulnerability. 
const scan = await qs.scan.wallet({
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  chain: "ethereum",
});

console.log(scan.riskScore);     // "W3"
console.log(scan.riskLabel);     // "High"
console.log(scan.chainGrade);    // "C"
console.log(scan.riskFactors);   // [ { factor: "public_key_exposure", ... }, ... ]
Wallet scanning works with both Publishable and Secret keys, making it safe for frontend use.

​
Error Handling

import { QuantumSafe, QuantumSafeError } from "@quantumsafe/sdk";

try {
  const keypair = await qs.keys.generate({
    algorithm: "ml-dsa-65",
    chain: "ethereum",
  });
} catch (err) {
  if (err instanceof QuantumSafeError) {
    console.error(err.code);     // "AUTH_003"
    console.error(err.message);  // "Insufficient permissions"
    console.error(err.status);   // 403
  }
}

​
TypeScript Types

The SDK exports full TypeScript types: 
import type {
  KeyPair,
  Algorithm,
  Chain,
  HybridAttestation,
  VerifyResult,
  WalletScan,
  RiskScore,
  ChainGrade,
} from "@quantumsafe/sdk";

​
Browser Support

The SDK works in any environment with the Web Crypto API:
  • Node.js 18+
  • Chrome 60+
  • Firefox 57+
  • Safari 11+
  • Edge 79+
The SDK will throw Error: CSPRNG not available if crypto.getRandomValues is not present. This prevents accidental use of insecure random sources.