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:
| Category | Stripped headers |
|---|---|
| Credentials & sessions | authorization, cookie, set-cookie, x-api-key, x-session-id |
| Network & IP origin | x-forwarded-for, x-real-ip, x-client-ip, cf-connecting-ip, true-client-ip |
| Client & organization identity | user-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
| Header | Example value | Description |
|---|---|---|
Content-Type | application/json | JSON challenge body |
X-Kalo-Protocol | kalo-402/v1 | Wire protocol version |
X-Kalo-Request-Hash | 0x4b1e...90a2 | SHA-256 of the raw request payload |
X-Kalo-Price-Commitment | 0x9f4a...c21e | Shielded 32-byte price commitment |
X-Kalo-Enclave-Pubkey | A222yQ4i...YZm5 | Base58 Ed25519 key of the provider's TEE |
X-Kalo-Provider | Prov7k...3xMn | Base58 EnclaveRegistry PDA |
X-Kalo-Mint | EPjFWdd5...Dt1v | Settlement SPL mint address |
X-Kalo-Amount | 40000 | Price in mint base units |
Challenge JSON body
{
"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 header | Required | Description |
|---|---|---|
Content-Type | Yes | application/json |
X-Kalo-Escrow | Yes | Base58 address of the locked SealedEscrow PDA |
X-Kalo-Viewing-Key | No | Viewing key used by the enclave to encrypt the response with AES-256-GCM |
X-Kalo-Mode | Demo only | Set 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
| Header | Description | ||||
|---|---|---|---|---|---|
Content-Type | application/json | ||||
X-Kalo-Protocol | kalo-402/v1 | ||||
X-Kalo-Receipt-Sig | 0x-prefixed 64-byte Ed25519 signature over `SHA256(escrow_pda \ | \ | request_hash \ | \ | output_hash)` |
Response JSON body
{
"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.