Reference

HTTP 402 Wire Format

Exact kalo-402/v1 request and response headers, 402 challenge payload, escrow retry format, receipt response, and PII stripping rules.

Protocol identifier

All Kalo HTTP 402 exchanges carry the protocol version string kalo-402/v1 in both the X-Kalo-Protocol header and the JSON response body.

Pre-execution PII header filtering

Before an agent sends its initial probe or its paid retry, filterPiiHeaders() removes identifying metadata headers in under 6ms p99. The 16 default blocked headers (matched case-insensitively) are:

CategoryStripped headers
Credentials & sessionsauthorization, cookie, set-cookie, x-api-key, x-session-id
Network & IP originx-forwarded-for, x-real-ip, x-client-ip, cf-connecting-ip, true-client-ip
Client & organization identityuser-agent, referer, origin, accept-language, x-org-trace-id, x-user-email

Callers can extend this set per call with filterPiiHeaders(headers, ['x-custom-trace']).

Stage 1: HTTP 402 Payment Required challenge

When a request arrives without an X-Kalo-Escrow header (or with X-Kalo-Mode: challenge on /v1/demo/infer), the provider responds with HTTP 402.

Response headers

HeaderExample valueDescription
Content-Typeapplication/jsonJSON challenge body
X-Kalo-Protocolkalo-402/v1Wire protocol version
X-Kalo-Request-Hash0x4b1e...90a2SHA-256 of the raw request payload
X-Kalo-Price-Commitment0x9f4a...c21eShielded 32-byte price commitment
X-Kalo-Enclave-PubkeyA222yQ4i...YZm5Base58 Ed25519 key of the provider's TEE
X-Kalo-ProviderProv7k...3xMnBase58 EnclaveRegistry PDA
X-Kalo-MintEPjFWdd5...Dt1vSettlement SPL mint address
X-Kalo-Amount40000Price in mint base units

Challenge JSON body

json
{
  "protocol": "kalo-402/v1",
  "status": 402,
  "requestHash": "0x4b1e8c...",
  "priceCommitment": "0x9f4a21...",
  "amountBaseUnits": "40000",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "symbol": "USDC",
  "providerAddress": "Prov7k...",
  "enclavePubkey": "A222yQ4iVKXrq2xRYxgZ5ruqMfmv2jBsxnwzyuT6YZm5"
}

On the live demo endpoint (POST /v1/demo/infer), the challenge body additionally returns hardwareType, measurementHash, piiStrippedHeaders, piiFilterLatencyMs, and expiresAt.

Stage 2: Paid retry request

After locking SealedEscrow on-chain via lock_sealed_402, the agent retries the exact same request body with the escrow PDA and optional viewing key headers:

Request headerRequiredDescription
Content-TypeYesapplication/json
X-Kalo-EscrowYesBase58 address of the locked SealedEscrow PDA
X-Kalo-Viewing-KeyNoViewing key used by the enclave to encrypt the response with AES-256-GCM
X-Kalo-ModeDemo onlySet to challenge or execute on /v1/demo/infer

Stage 3: Attested HTTP 200 OK response

Once verifyEscrow(escrowAddress, requestHash) passes and the handler executes inside the enclave, kaloGate() returns HTTP 200:

Response headers

HeaderDescription
Content-Typeapplication/json
X-Kalo-Protocolkalo-402/v1
X-Kalo-Receipt-Sig0x-prefixed 64-byte Ed25519 signature over `SHA256(escrow_pda \\request_hash \\output_hash)`

Response JSON body

json
{
  "protocol": "kalo-402/v1",
  "escrowAddress": "Escr5p...",
  "requestHash": "0x4b1e8c...",
  "outputHash": "0x7c90d4...",
  "enclavePubkey": "A222yQ4iVKXrq2xRYxgZ5ruqMfmv2jBsxnwzyuT6YZm5",
  "teeSignature": "0xa1f0...",
  "encryptedResponse": "0x84c2..."
}

When X-Kalo-Viewing-Key is provided, encryptedResponse contains the AES-256-GCM ciphertext (iv || authTag || ciphertext) and plaintext result is omitted. When no viewing key is provided, encryptedResponse is omitted and result contains the handler output directly.

Escrow verification failure

If verifyEscrow returns false, kaloGate() returns HTTP 402 with { "error": "Escrow verification failed." } and does not execute the handler.

Confidential commerce infrastructure for autonomous software.

Shielded treasuries, scoped mandates, and receipt-bound HTTP 402 settlement on Solana L1.

Open consoleRead the docs