Reference

@kalo/sdk API Reference

Complete TypeScript API reference for KaloClient, kalo.fetch(), kaloGate(), filterPiiHeaders(), and cryptographic helpers.

Installation

bash
npm install @kalo/sdk @solana/web3.js

Package entry point: @kalo/sdk (v0.1.0, ESM, TypeScript declarations included, peer/runtime dependency @solana/web3.js 1.99.0).

KaloClient

Agent-side HTTP 402 client that handles pre-execution PII filtering, challenge negotiation, SealedEscrow locking, Ed25519 receipt verification, and viewing-key decryption.

Constructor

ts
new KaloClient(config: KaloClientConfig)
OptionTypeRequiredDescription
apiUrlstringYesBase URL of the Kalo API server (used for /v1/settlements/lock/build)
agentPubkeystringYesBase58 Ed25519 public key of the delegated agent
ringAddressstringYesBase58 address of the funding PrivacyRing PDA
defaultMandatestringNoDefault AuthorityMandate PDA address used when options.mandate is omitted
defaultViewingKeystringNoDefault viewing key sent via X-Kalo-Viewing-Key and used to decrypt encryptedResponse
fetchtypeof globalThis.fetchNoCustom Fetch implementation (defaults to globalThis.fetch)

kalo.fetch<T>(url, options?)

Executes a confidential HTTP 402 request and returns Promise<KaloFetchResponse<T>>.

KaloFetchOptions extends standard RequestInit:

OptionTypeRequiredDescription
mandatestringNoOverrides defaultMandate for this call (throws if neither is set)
viewingKeystringNoOverrides defaultViewingKey for this call
maxPriceBaseUnitsbigintNoClient-side ceiling; throws before locking if BigInt(challenge.amountBaseUnits) > maxPriceBaseUnits
method, headers, bodyRequestInitNoStandard fetch parameters; method defaults to 'POST'

KaloFetchResponse<T>:

PropertyTypeDescription
statusnumberHTTP status code from provider
okbooleantrue on successful execution
escrowAddressstringDerived SealedEscrow PDA address ('' if provider did not return 402)
requestHashstring0x SHA-256 request digest
outputHashstring0x SHA-256 response digest
teeSignaturestring0x 64-byte Ed25519 signature
enclavePubkeystringBase58 enclave signing public key
receiptVerifiedbooleanResult of local verifyTeeReceipt() check
piiStrippedHeadersstring[]Header keys removed by filterPiiHeaders()
piiFilterLatencyMsnumberFilter execution duration in milliseconds
encryptedBody`string \null`AES-256-GCM ciphertext if encryptedResponse was returned
dataTParsed response payload (decrypted if viewingKey was supplied)

kaloGate(config, handler)

Provider-side Fetch API middleware that gates any route behind HTTP 402 challenge negotiation and Confidential Compute receipt signing.

ts
function kaloGate(config: KaloGateConfig, handler: GateHandler): (req: Request) => Promise<Response>

KaloGateConfig

FieldTypeRequiredDescription
providerAddressstringYesBase58 EnclaveRegistry PDA address
enclavePubkeystringYesBase58 enclave Ed25519 public key
enclaveSecret32Uint8ArrayYes32-byte raw Ed25519 private seed held inside the TEE
mintstringYesSettlement token mint address
symbolstringNoAsset ticker (defaults to 'USDC')
priceBaseUnitsstringYesDecimal string price per call in mint base units
verifyEscrow(escrowAddress: string, requestHash: string) => Promise<boolean>NoHook to verify SealedEscrow state on-chain before running handler

GateHandler

ts
type GateHandler = (bodyText: string, req: Request) => Promise<unknown> | unknown

filterPiiHeaders(headers, extraBlocked?)

Removes sensitive and identifying headers before outbound HTTP 402 dispatch.

ts
function filterPiiHeaders(
  headers: HeadersInit | Record<string, string> | undefined,
  extraBlocked?: readonly string[],
): PiiFilterResult

Returns { cleanHeaders: Record<string, string>, stripped: string[], latencyMs: number }. See HTTP 402 Wire Format for the full 16-header default blocklist.

Cryptographic helpers

All functions are exported directly from @kalo/sdk:

FunctionSignatureDescription
stripHex(hex: string) => stringRemoves a leading 0x or 0X prefix
sha256Hex`(input: string \Buffer \Uint8Array) => string`Returns 0x-prefixed 32-byte SHA-256 hex digest
createCommitment(amountBaseUnits: bigint, blindingHex?: string) => { commitment: string; blinding: string }Computes `SHA256("kalo:spr:commitment:v1" \\amount \\blinding)` with a 32-byte blinding factor
deriveNullifier(commitmentHex: string, ownerPubkey: string) => stringComputes a fresh 32-byte 0x nullifier bound to commitment and owner
encryptWithViewingKey(plaintext: string, viewingKey: string) => stringEncrypts UTF-8 plaintext with AES-256-GCM (`iv \\tag \\ciphertext) keyed by SHA256("kalo:vk:v1:" \\viewingKey)`
decryptWithViewingKey`(ciphertextHex: string, viewingKey: string) => string \null`Decrypts AES-256-GCM ciphertext; returns null if key is wrong or payload is tampered
buildReceiptDigest(escrowAddress: string, requestHashHex: string, outputHashHex: string) => BufferComputes the 32-byte digest `SHA256(escrow_pda_bytes \\req_bytes \\out_bytes)`
signReceiptEd25519(digest: Buffer, secret32: Uint8Array) => stringSigns a 32-byte digest with a 32-byte Ed25519 seed, returning 0x-prefixed 64-byte hex
verifyTeeReceipt(digest: Buffer, signatureHex: string, enclavePubkey: string) => booleanVerifies a 64-byte Ed25519 receipt signature against a Base58 Solana public key

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs