5. Pilot packet

Version: 1.0 · Production API: https://api.quantzk.com
Binding: bn128-poseidon8-v1 (Phase-2 in-circuit) · Full packet: ../QUANTZK_VERIFIABLE_BILLING_PILOT_PACKET.pdf

---

Problem

Usage-based API billing breaks at the trust boundary between meter, tariff, and invoice.

Pain	What teams experience
Dispute archaeology	Finance reconstructs charges from logs, Stripe, spreadsheets — days per ticket
No portable proof	Nothing cryptographically links this usage event to this line-item charge
Enterprise friction	Procurement wants verifiable audit trails, not dashboards
Replay and drift	Duplicate event IDs and tariff changes create silent mismatches

---

QuantZK workflow

Two HTTP calls. Same surface before and after Phase-2.

POST /api/vdi/billing/attest   →  signed bundle (meter + tariff + charge + receipt)
POST /api/vdi/billing/verify   →  pass/fail + incircuit_binding_verification

Bundle fields

Field	Role
meter_event	Idempotent event_id, usage units, tenant, window
tariff_snapshot	Pinned price, min/max, rounding at issuance
billing.expected_charge_micros	Deterministic charge
billing.billing_verify_fingerprint	Reconciliation fingerprint
attestation + receipt	VDI signed decision + verification receipt
attestation.billing_proof	Phase-2 Groth16 binding (additive)

Trust infrastructure (production)

Endpoint	Status
GET /.well-known/vdi-billing-revocation.json	200
GET /api/vdi/billing/transparency/head	200
GET /api/vdi/status	operational
GET /health	environment: production

---

Integration (10 minutes)

Step 1 — Attest after metering

curl -sS -X POST "https://api.quantzk.com/api/vdi/billing/attest" \
  -H "Content-Type: application/json" \
  -H "X-VDI-Attest-Secret: $VDI_ATTEST_SECRET" \
  -d '{
    "billing_version": "v2",
    "profileId": "VDI_VERIFY_STANDARD_V1",
    "meter_event": {
      "event_id": "evt_pilot_001",
      "event_timestamp": "2026-05-29T12:00:00.000Z",
      "tenant_id": "tenant_acme",
      "api_key_id": "api_live_001",
      "endpoint": "/v1/completions",
      "usage_units": 1842,
      "contract_version": "contract-v1",
      "billing_window_id": "2026-05"
    },
    "tariff_snapshot": {
      "tariff_id": "tariff_default",
      "tariff_version": "1.0.0",
      "tariff_class": "usage_linear",
      "unit_price_micros": 120,
      "min_charge_micros": 50000,
      "max_charge_micros": 5000000000,
      "rounding_mode": "floor",
      "currency": "USD"
    }
  }' | jq .

Store the full JSON response.

Step 2 — Verify on dispute

curl -sS -X POST "https://api.quantzk.com/api/vdi/billing/verify" \
  -H "Content-Type: application/json" \
  -d @verify-body.json | jq .

verify-body.json includes attestation, receipt, billed_billing_v2, and expected_billing_v2 from step 1.

Step 3 — Wire into stack

1. Call /attest once per billable event (unique event_id).
2. Persist bundle next to invoice line or ledger entry.
3. On dispute or month-end close, call /verify.

---

Dispute resolution (worked example)

Scenario: Customer disputes $221.04 for 1,842 completion units.

Verify (valid bundle):

{
  "verification": { "valid": true },
  "billing_check": { "valid": true },
  "incircuit_binding_verification": {
    "valid": true,
    "binding_version": "bn128-poseidon8-v1",
    "commitment_digest": "17482494435685096671389889045805694801134018277950430849590868584772755507057"
  }
}

Tamper (modified tariff): incircuit_binding_verification.valid → false. Fail closed.

Resolution time: minutes, not days. Evidence: JSON bundle + verify response.

---

Pilot scope

Parameter	Value
Duration	2–4 weeks
Endpoints	One high-volume billable API route
Tariff	One tariff line
Profile	VDI_VERIFY_STANDARD_V1
Success metrics	Dispute MTTR, reconciliation match rate, security sign-off

---

ROI (conservative)

Variable	Example
Disputes / month	20
Hours per dispute	4
Blended hourly cost	$150
Monthly dispute cost (today)	$12,000
With verify receipts	~$1,500 (~0.5 hr each)
Monthly savings	~$10,500

Pilot integration: ~1–2 engineering days. Break-even often in first billing cycle at material dispute volume.

---

References

Document	Path
Full pilot packet (markdown)	../QUANTZK_VERIFIABLE_BILLING_PILOT_PACKET.md
Pilot runbook	../../../protocol/docs/api-billing-pilot.md
Production deploy	../../../protocol/docs/api-billing-production.md
Smoke script	scripts/smoke-billing-phase2.sh

Contact: Omar@quantzk.com · Trust index: quantzk.com/trust