@h33/commerce

Private commerce infrastructure. Proof-of-payment without identity disclosure.

Three API calls. Ten minutes.

Install

npm install @h33/commerce

Quickstart

import { H33Commerce } from '@h33/commerce';

const h33 = new H33Commerce('your-api-key');

// 1. Create invoice
const invoice = await h33.createInvoice({
  amount: 50.13,
  currency: 'USD',
});

// 2. Display QR code (customer scans and pays)
displayQR(invoice.qrPayload);

// 3. Check settlement
const status = await h33.getSettlement(invoice.commitment);
console.log(status.approved); // true

That's it. The customer proves payment without revealing their identity, wallet, or balance.

What the merchant sees

approved: true
settlement_status: "completed"
compliance_valid: true

What the merchant never sees

• Customer identity
• Wallet address
• Account balance
• Transaction history
• Spending patterns
• Other purchases

API

createInvoice(params)

Create a PQ-signed invoice. Returns a QR payload for display.

const invoice = await h33.createInvoice({
  amount: 50.13,         // Dollars
  currency: 'USD',
  tax: 4.14,             // Optional
  expiresIn: 3600,       // Seconds (default: 1 hour)
  idempotencyKey: 'order-12345',  // Prevents duplicates
  items: [               // Optional: for selective disclosure
    { description: 'Dinner', quantity: 1, unitPrice: 45.99, category: 'food' },
  ],
});

Returns:

{
  invoiceId: "INV-1716400000-a1b2c3d4",
  commitment: "6a9dd070...",          // 32 bytes (hex)
  total: 50.13,
  totalCents: 5013,
  currency: "USD",
  expiresAt: Date,
  qrPayload: { ... }                 // Display as QR code
}

The QR payload contains an H33-74 substrate signed by three post-quantum signature families (ML-DSA + FALCON + SLH-DSA). The customer's wallet verifies this signature before paying. A forged QR code is cryptographically impossible.

getSettlement(commitment)

Check if a payment has been verified and settled.

const status = await h33.getSettlement(invoice.commitment);

if (status.approved) {
  // Payment verified. Serve the customer.
  console.log(status.complianceValid);        // true
  console.log(status.attestationCommitment);  // Proof reference
  console.log(status.proofKey);               // For dispute resolution
}

verify(commitment)

Verify a payment attestation. No API key required. Anyone can verify.

const result = await h33.verify(invoice.commitment);
console.log(result.valid);  // true

health()

Check service status.

const h = await h33.health();
console.log(h.status);    // "healthy"
console.log(h.circuits);  // 35

Webhooks

Receive real-time payment notifications instead of polling.

// Express example
app.post('/h33-webhook', (req, res) => {
  const valid = h33.verifyWebhook(req.body, req.headers['x-h33-signature']);
  if (!valid) return res.status(401).send('Invalid');

  switch (req.body.event) {
    case 'payment.verified':
      handlePayment(req.body.invoice_id);
      break;
    case 'payment.settled':
      markSettled(req.body.invoice_id);
      break;
  }

  res.status(200).send('ok');
});

QR Code Display

The qrPayload object can be rendered as a QR code using any library:

import QRCode from 'qrcode';

const invoice = await h33.createInvoice({ amount: 50.13, currency: 'USD' });
const qrDataUrl = await QRCode.toDataURL(JSON.stringify(invoice.qrPayload));

// In HTML: <img src="${qrDataUrl}" />

The QR code contains:

• Invoice commitment (32 bytes)
• Merchant ID
• Amount (for wallet display)
• H33-74 PQ signature (unforgeable)
• Expiry

Error Handling

import { H33Error } from '@h33/commerce';

try {
  const invoice = await h33.createInvoice({ amount: 0, currency: 'USD' });
} catch (e) {
  if (e instanceof H33Error) {
    console.log(e.code);    // "invalid_amount"
    console.log(e.message); // "amount_cents must be > 0"
    console.log(e.status);  // 400
  }
}

Error codes:

Code	HTTP	Meaning
invalid_amount	400	Amount must be > 0
invalid_currency	400	Currency is required
invoice_not_found	404	Invoice commitment not found
invoice_expired	410	Invoice has expired
double_payment	409	Nullifier already spent
amount_mismatch	400	Payment amount doesn't match invoice
rate_limited	429	Too many requests
missing_auth	401	API key required

Framework Examples

Next.js API Route

// app/api/invoice/route.ts
import { H33Commerce } from '@h33/commerce';

const h33 = new H33Commerce(process.env.H33_API_KEY!);

export async function POST(req: Request) {
  const { amount, currency } = await req.json();

  const invoice = await h33.createInvoice({ amount, currency });

  return Response.json({
    invoiceId: invoice.invoiceId,
    qrPayload: invoice.qrPayload,
  });
}

Express

import express from 'express';
import { H33Commerce } from '@h33/commerce';

const app = express();
const h33 = new H33Commerce(process.env.H33_API_KEY!);

app.post('/invoice', async (req, res) => {
  const invoice = await h33.createInvoice({
    amount: req.body.amount,
    currency: 'USD',
  });
  res.json(invoice);
});

app.get('/status/:commitment', async (req, res) => {
  const status = await h33.getSettlement(req.params.commitment);
  res.json(status);
});

How It Works

1. Merchant calls createInvoice() — H33 generates a STARK proof commitment and signs it with three post-quantum signature families
2. Customer scans QR — their wallet verifies the H33-74 signature (unforgeable), then generates a zero-knowledge proof that they can pay
3. Proof is verified — H33 confirms the payment is valid, authorized, and compliant without ever seeing the customer's identity
4. Merchant receives approved: true — settlement happens on the chosen rail (ACH, card, RTP, FedNow, stablecoin)

No customer identity is collected, stored, or transmitted. The proof replaces the identity.

Security

• Invoices are signed by ML-DSA-65, FALCON-512, and SLH-DSA-128f (three independent post-quantum signature families)
• Payment nullifiers prevent double-payment
• Idempotency keys prevent duplicate invoices
• All proofs are independently verifiable via the public HATS verifier
• Rate limiting: 100 invoices/sec, 500 verifications/sec

Links

• Live Systems (50 demos)
• Use Case Matrix (44 ZK use cases)
• HATS Standard
• HATS Verifier (open source)
• API Reference
• Schedule Demo

License

MIT

Copyright 2026 H33.ai, Inc.