Gating an API with HTTP 402
Register a Confidential Compute TEE enclave and wrap paid API or AI routes with kaloGate() for atomic receipt-bound settlement.
How a provider joins Kalo
A provider runs an API, data feed, or private model inside a Confidential Compute enclave (IntelTDX or AmdSevSnp), registers the enclave's ephemeral Ed25519 signing key on Solana via register_enclave, and wraps its HTTP route with kaloGate() from @kalo/sdk.
Step 1: Register your TEE enclave on-chain
register_enclave creates two paired PDAs:
EnclaveRegistryat["enclave_registry", enclave_pubkey]ReputationAccumulatorat["reputation", enclave_pubkey]
In the web console
- Open Attested Providers and connect your provider authority wallet.
- Click Register enclave.
- Provide the service name, description, endpoint URL, enclave Ed25519 public key, hardware type (
IntelTDX=0orAmdSevSnp=1), 32-bytemeasurementHash,serviceCategorybit (1,2,4,8, or16), per-call price in base units, and settlement mint. - Sign and submit
register_enclave.
Via the REST API
const res = await fetch('http://127.0.0.1:41202/v1/providers/register/build', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
authority: providerAuthorityPubkey,
name: 'Helios Private Alpha',
description: 'Intel TDX volatility and basis signal endpoint',
endpointUrl: 'https://infer.kalo.local/v1/demo/infer',
enclavePubkey: enclaveEd25519Pubkey,
hardwareType: 'IntelTDX',
measurementHash: '0x8a2f19c4d8e7b10293847561029384756102938475610293847561029384e91b',
serviceCategory: 1, // AI Inference
priceBaseUnits: '40000', // 0.04 USDC
mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
symbol: 'USDC',
}),
})
const built = await res.json()
// built.derivedAddresses.providerAddress -> EnclaveRegistry PDAexpires_slot must be strictly greater than the current Solana slot. Once clock.slot >= enclave.expires_slot, both lock_sealed_402 and settle_with_receipt reject calls with EnclaveInactive (6009).Step 2: Wrap your route with kaloGate()
kaloGate(config, handler) returns a standard (req: Request) => Promise<Response> handler compatible with Hono, Next.js Route Handlers, Cloudflare Workers, and Node Fetch servers.
import { kaloGate } from '@kalo/sdk'
const handler = kaloGate(
{
providerAddress: process.env.KALO_PROVIDER_PDA!,
enclavePubkey: process.env.KALO_ENCLAVE_PUBKEY!,
enclaveSecret32: Buffer.from(process.env.KALO_ENCLAVE_SECRET_HEX!, 'hex'),
mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
symbol: 'USDC',
priceBaseUnits: '40000',
verifyEscrow: async (escrowAddress, requestHash) => {
const r = await fetch(`http://127.0.0.1:41202/v1/settlements/${escrowAddress}`)
if (!r.ok) return false
const escrow = await r.json()
return escrow.state === 'locked' && escrow.requestHash === requestHash
},
},
async (bodyText) => {
const input = JSON.parse(bodyText)
// Run private inference or query inside the TEE
return { signal: 'long_vol', promptLength: String(input.prompt ?? '').length }
},
)What kaloGate() does on each request
- Reads the raw request body and computes
requestHash = sha256Hex(bodyText || req.url). - Checks for the
X-Kalo-Escrowheader. If absent, creates a fresh price commitment and returns HTTP402with both JSON body andX-Kalo-*response headers. - If
X-Kalo-Escrowis present, callsconfig.verifyEscrow(escrowAddress, requestHash). Returningfalserejects the call with HTTP402. - Runs
handler(bodyText, req), serializes the result, computesoutputHash = sha256Hex(serialized), builds the 32-byte receipt digestSHA256(escrow_pda_bytes || request_hash_bytes || output_hash_bytes), and signs it withenclaveSecret32. - If
X-Kalo-Viewing-Keyis present, encrypts the response body with AES-256-GCM (encryptedResponse) and omits plaintextresult. - Returns HTTP
200withX-Kalo-Protocol: kalo-402/v1andX-Kalo-Receipt-Sig: <signatureHex>.
Step 3: Settle the escrow on-chain
After returning the signed response, submit settle_with_receipt before escrow.timeout_slot passes. The transaction must prepend a Solana Ed25519SigVerify precompile instruction verifying enclave_pubkey over the 32-byte digest SHA256(escrow_pda || request_hash || output_hash).
You can build the settlement transaction via POST /v1/settlements/:address/settle/build:
const settleRes = await fetch(`http://127.0.0.1:41202/v1/settlements/${escrowAddress}/settle/build`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
providerAuthority: providerAuthorityPubkey,
outputHash,
teeSignatureHex: teeSignature,
}),
})On confirmation, ring_vault transfers amount - fee_amount to provider_token_account, transfers fee_amount to launch_wallet_token_account, sets escrow.state = 1 (Settled), and increments reputation_accumulator.settled_count.
Next step
Learn how agents verify your Ed25519 receipts and how timed-out escrows refund in Verifying Confidential Compute Receipts.