H33/ Docs/ API/ Reference

Privacy & Commerce API Reference

13 privacy endpoints + 4 commerce endpoints. Post-quantum attested proofs for identity, KYC, DeFi, and commerce settlement. Every proof is a 32-byte on-chain commitment backed by STARK + PQ signatures.

Base URL https://privacy.h33.ai

Alias https://api.h33.ai

Spec /docs/api/openapi-privacy.yaml

Auth: X-API-Key header required for commerce invoice/settlement only. All privacy and verify endpoints are public.

All Endpoints (17)

POST /privacy/age POST /privacy/identity POST /privacy/kyc-status POST /privacy/jurisdiction POST /privacy/accredited POST /privacy/compliance POST /defi/balance-range POST /defi/collateral POST /defi/portfolio-threshold GET /privacy/proof/:id POST /privacy/verify GET /commerce/health POST /commerce/invoice GET /commerce/settlement/:commitment POST /commerce/verify GET /health GET /chain/status

Universal ResponseShieldProofResponse

All privacy endpoints return this envelope. The commitment is the on-chain anchor; claim_satisfied is the boolean result.

Field	Type	Description
commitment	string	32-byte hex commitment (on-chain anchor)
claim_satisfied	bool	Whether the claim passed the threshold
attestation_type	string	Proof type (e.g. "age_threshold", "kyc_status")
expires_at	string	ISO 8601 expiration timestamp
cachee_key	string	Cachee lookup key for fast re-verification
proof_size_bytes	int	Total proof size (typically 74 bytes on-chain)
solana_program_id	string	Solana program ID for on-chain verification
chain	string	Target chain (e.g. "solana", "ethereum")

Identity

Prove identity attributes without revealing underlying data. Age and attribute proofs.

POST /api/v1/privacy/age Public

Generate a zero-knowledge age threshold proof. Proves the subject is above a minimum age without revealing their date of birth.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/age \
  -H "Content-Type: application/json" \
  -d '{
    "date_of_birth": "1990-01-15",
    "minimum_age": 21,
    "chain": "solana"
  }'

Response 200

{
  "commitment": "a1b2c3d4e5f6...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "age_threshold",
  "expires_at": "2026-05-24T00:00:00Z",
  "cachee_key": "age:solana:a1b2c3d4",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/identity Public

Prove an identity attribute (e.g. nationality, residency) without revealing the full identity document.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/identity \
  -H "Content-Type: application/json" \
  -d '{
    "attribute": "nationality",
    "value": "US",
    "chain": "ethereum"
  }'

Response 200

{
  "commitment": "f8e7d6c5b4a3...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "identity_attribute",
  "expires_at": "2026-05-24T00:00:00Z",
  "cachee_key": "identity:ethereum:f8e7d6c5",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "ethereum"
}

KYC & Compliance

Regulatory compliance proofs: KYC tier, jurisdiction membership, accredited investor status, and multi-regulation checks.

POST /api/v1/privacy/kyc-status Public

Prove KYC tier (e.g. tier_1, tier_2, tier_3) without revealing personal documents or provider details.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/kyc-status \
  -H "Content-Type: application/json" \
  -d '{
    "kyc_tier": "tier_2",
    "provider_hash": "sha3_of_provider_attestation",
    "chain": "solana"
  }'

Response 200

{
  "commitment": "c4d5e6f7a8b9...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "kyc_status",
  "expires_at": "2026-06-22T00:00:00Z",
  "cachee_key": "kyc:solana:c4d5e6f7",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/jurisdiction Public

Prove membership in an allowed jurisdiction set without revealing the exact country of residence.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/jurisdiction \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "US",
    "allowed_set": ["US", "CA", "GB", "DE", "JP"],
    "chain": "solana"
  }'

Response 200

{
  "commitment": "b3a2c1d0e9f8...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "jurisdiction_membership",
  "expires_at": "2026-05-24T00:00:00Z",
  "cachee_key": "jurisdiction:solana:b3a2c1d0",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/accredited Public

Prove accredited investor status per SEC Rule 501 without revealing income, net worth, or financial documents.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/accredited \
  -H "Content-Type: application/json" \
  -d '{
    "qualification": "income",
    "provider_hash": "sha3_of_financial_attestation",
    "chain": "ethereum"
  }'

Response 200

{
  "commitment": "d2e3f4a5b6c7...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "accredited_investor",
  "expires_at": "2026-08-21T00:00:00Z",
  "cachee_key": "accredited:ethereum:d2e3f4a5",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "ethereum"
}

POST /api/v1/privacy/compliance Public

Multi-regulation compliance proof covering OFAC screening, AML checks, KYC verification, and travel rule compliance in a single attestation.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/compliance \
  -H "Content-Type: application/json" \
  -d '{
    "checks": ["ofac", "aml", "kyc", "travel_rule"],
    "entity_hash": "sha3_of_entity_data",
    "chain": "solana"
  }'

Response 200

{
  "commitment": "e1f2a3b4c5d6...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "regulatory_compliance",
  "expires_at": "2026-05-24T00:00:00Z",
  "cachee_key": "compliance:solana:e1f2a3b4",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

DeFi

Privacy-preserving financial proofs for DeFi protocols. Prove balance ranges, collateral ratios, and portfolio thresholds without exposing wallet balances.

POST /api/v1/privacy/defi/balance-range Public

Prove a wallet balance falls within a specified range without revealing the exact amount.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/defi/balance-range \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "token_mint": "So11111111111111111111111111111111111111112",
    "min_balance": 100,
    "max_balance": 10000,
    "chain": "solana"
  }'

Response 200

{
  "commitment": "1a2b3c4d5e6f...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "balance_range",
  "expires_at": "2026-05-23T01:00:00Z",
  "cachee_key": "balance:solana:1a2b3c4d",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/defi/collateral Public

Prove a collateral ratio meets a minimum threshold without revealing position size or borrowed amounts.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/defi/collateral \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "protocol": "marginfi",
    "min_ratio": 150,
    "chain": "solana"
  }'

Response 200

{
  "commitment": "7f8e9d0c1b2a...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "collateral_ratio",
  "expires_at": "2026-05-23T01:00:00Z",
  "cachee_key": "collateral:solana:7f8e9d0c",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/defi/portfolio-threshold Public

Prove total portfolio value exceeds a threshold without revealing holdings, allocations, or individual positions.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/defi/portfolio-threshold \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "min_value_usd": 50000,
    "chain": "solana"
  }'

Response 200

{
  "commitment": "4e5f6a7b8c9d...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "portfolio_threshold",
  "expires_at": "2026-05-23T01:00:00Z",
  "cachee_key": "portfolio:solana:4e5f6a7b",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

Verification

Retrieve cached proofs and verify commitments. These are how relying parties confirm a proof is valid.

GET /api/v1/privacy/proof/:id Public

Retrieve a cached proof by its commitment ID. Returns the full ShieldProofResponse if the proof has not expired.

curl

curl https://privacy.h33.ai/api/v1/privacy/proof/a1b2c3d4e5f6...64hexchars

Response 200

{
  "commitment": "a1b2c3d4e5f6...64 hex chars",
  "claim_satisfied": true,
  "attestation_type": "age_threshold",
  "expires_at": "2026-05-24T00:00:00Z",
  "cachee_key": "age:solana:a1b2c3d4",
  "proof_size_bytes": 74,
  "solana_program_id": "5eAwAv59YqpnSBMj59KeXhDdLqmn99HBYSjrb6jcLbC5",
  "chain": "solana"
}

POST /api/v1/privacy/verify Public

Verify a commitment against the on-chain anchor. Returns whether the proof is valid and has not expired.

curl

curl -X POST https://privacy.h33.ai/api/v1/privacy/verify \
  -H "Content-Type: application/json" \
  -d '{
    "commitment": "a1b2c3d4e5f6...64hexchars",
    "chain": "solana"
  }'

Response 200

{
  "valid": true,
  "commitment": "a1b2c3d4e5f6...64 hex chars",
  "attestation_type": "age_threshold",
  "expires_at": "2026-05-24T00:00:00Z",
  "chain": "solana",
  "verified_at": "2026-05-23T12:00:00Z"
}

Commerce

Privacy-preserving payment infrastructure. Create invoices, verify payments, and check settlement status with PQ-attested proofs.

GET /api/v1/commerce/health Public

Check commerce service health and availability.

curl

curl https://privacy.h33.ai/api/v1/commerce/health

Response 200

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400
}

POST /api/v1/commerce/invoice Auth Required

Create a privacy-preserving invoice. The amount and recipient are committed on-chain without revealing either to third parties.

curl

curl -X POST https://privacy.h33.ai/api/v1/commerce/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "amount_cents": 5000,
    "currency": "USD",
    "description": "SaaS subscription - May 2026",
    "recipient_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "chain": "solana"
  }'

Response 201

{
  "invoice_id": "inv_a1b2c3d4e5f6",
  "commitment": "9a8b7c6d5e4f...64 hex chars",
  "payment_url": "https://privacy.h33.ai/pay/inv_a1b2c3d4e5f6",
  "expires_at": "2026-05-24T00:00:00Z",
  "chain": "solana",
  "proof_size_bytes": 74
}

GET /api/v1/commerce/settlement/:commitment Auth Required

Check settlement status for a commerce commitment. Returns whether the payment has been confirmed on-chain.

curl

curl https://privacy.h33.ai/api/v1/commerce/settlement/9a8b7c6d5e4f...64hexchars \
  -H "X-API-Key: your_api_key_here"

Response 200

{
  "commitment": "9a8b7c6d5e4f...64 hex chars",
  "status": "settled",
  "settled_at": "2026-05-23T14:30:00Z",
  "tx_signature": "5VERv8NMvz...solana_tx_sig",
  "chain": "solana"
}

POST /api/v1/commerce/verify Public

Publicly verify a commerce payment commitment. No API key required -- anyone can confirm a payment was made.

curl

curl -X POST https://privacy.h33.ai/api/v1/commerce/verify \
  -H "Content-Type: application/json" \
  -d '{
    "commitment": "9a8b7c6d5e4f...64hexchars",
    "chain": "solana"
  }'

Response 200

{
  "valid": true,
  "commitment": "9a8b7c6d5e4f...64 hex chars",
  "status": "settled",
  "chain": "solana",
  "verified_at": "2026-05-23T15:00:00Z"
}

Infrastructure

Health checks and chain connectivity status.

GET /health Public

Root health check. Returns service status, version, and uptime.

curl

curl https://privacy.h33.ai/health

Response 200

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 259200,
  "pq_families": 3,
  "chains_connected": 10
}

GET /api/v1/chain/status Public

Returns connectivity status for all 10 supported chains. Use this to check which chains are available before submitting proofs.

curl

curl https://privacy.h33.ai/api/v1/chain/status

Response 200

{
  "chains": {
    "solana":    { "connected": true,  "latency_ms": 12 },
    "ethereum":  { "connected": true,  "latency_ms": 45 },
    "bitcoin":   { "connected": true,  "latency_ms": 180 },
    "polygon":   { "connected": true,  "latency_ms": 18 },
    "arbitrum":  { "connected": true,  "latency_ms": 22 },
    "optimism":  { "connected": true,  "latency_ms": 20 },
    "base":      { "connected": true,  "latency_ms": 19 },
    "avalanche": { "connected": true,  "latency_ms": 35 },
    "zcash":     { "connected": true,  "latency_ms": 95 },
    "hyperliquid": { "connected": true, "latency_ms": 15 }
  },
  "total": 10,
  "all_healthy": true
}