Guides

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:

  • EnclaveRegistry at ["enclave_registry", enclave_pubkey]
  • ReputationAccumulator at ["reputation", enclave_pubkey]

In the web console

  1. Open Attested Providers and connect your provider authority wallet.
  2. Click Register enclave.
  3. Provide the service name, description, endpoint URL, enclave Ed25519 public key, hardware type (IntelTDX = 0 or AmdSevSnp = 1), 32-byte measurementHash, serviceCategory bit (1, 2, 4, 8, or 16), per-call price in base units, and settlement mint.
  4. Sign and submit register_enclave.

Via the REST API

ts
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 PDA
IMPORTANTexpires_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.

ts
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

  1. Reads the raw request body and computes requestHash = sha256Hex(bodyText || req.url).
  2. Checks for the X-Kalo-Escrow header. If absent, creates a fresh price commitment and returns HTTP 402 with both JSON body and X-Kalo-* response headers.
  3. If X-Kalo-Escrow is present, calls config.verifyEscrow(escrowAddress, requestHash). Returning false rejects the call with HTTP 402.
  4. Runs handler(bodyText, req), serializes the result, computes outputHash = sha256Hex(serialized), builds the 32-byte receipt digest SHA256(escrow_pda_bytes || request_hash_bytes || output_hash_bytes), and signs it with enclaveSecret32.
  5. If X-Kalo-Viewing-Key is present, encrypts the response body with AES-256-GCM (encryptedResponse) and omits plaintext result.
  6. Returns HTTP 200 with X-Kalo-Protocol: kalo-402/v1 and X-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:

ts
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.

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs