Getting Started

Quickstart

Create a Privacy Ring, issue an agent mandate, and run your first settled HTTP 402 call.

Two ways to run your first settlement

You can complete a full Sealed 402 Settlement in the browser through the Kalo console or programmatically with @kalo/sdk. Both paths execute the same four stages against kalo_protocol (7gvg3hFxPbtSkxjCoPHEXMPSen7X9H21y96JPVBbf47S).

Path 1: Web console

  1. Open Rings & Shielded Treasury and connect a Solana wallet.
  2. Click Create Ring, choose a settlement mint (USDC, SOL, or another SPL mint) and compliance mode (Permissionless or Allowlisted), and optionally attach an auditor public key. Sign the create_ring transaction.
  3. Select the new Ring, click Shield funds, enter an amount in base units, and sign shield_deposit. Toggle Viewing key to decrypt the shielded UTXO note locally.
  4. Open Authority Mandates, click Issue mandate, and bind an agent Ed25519 public key to your Ring with a per-call cap, epoch budget, epoch duration (at least 60 seconds), service category bitmask, and expiry timestamp.
  5. Open Sealed 402 Console, pick the active mandate and an attested provider from Attested Providers, enter a prompt, and click Run sealed 402.
  6. Inspect the four-stage trace (402 Challenge, Shielded Lock, TEE Receipt, Atomic Release) and toggle between Public chain (opaque commitments and hashes) and Viewing key (decrypted price, fee, request summary, and response).

Path 2: TypeScript SDK

Install @kalo/sdk (requires Node 20+ and @solana/web3.js 1.99.0):

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

1. Initialize KaloClient

Create a client configured with the Kalo API base URL, the delegated agent public key, the Ring address, the active mandate address, and an optional viewing key for local response decryption.

ts
import { KaloClient } from '@kalo/sdk'

const kalo = new KaloClient({
  apiUrl: 'http://127.0.0.1:41202',
  agentPubkey: process.env.KALO_AGENT_PUBKEY!,
  ringAddress: process.env.KALO_RING_ADDRESS!,
  defaultMandate: process.env.KALO_MANDATE_ADDRESS!,
  defaultViewingKey: process.env.KALO_VIEWING_KEY,
})

2. Call a gated HTTP 402 endpoint

kalo.fetch() strips PII headers before the request leaves the client, negotiates the HTTP 402 challenge, calls /v1/settlements/lock/build to lock the SealedEscrow, retries with X-Kalo-Escrow, verifies the provider's Ed25519 TEE receipt, and decrypts encryptedResponse when a viewing key is supplied.

ts
interface InferenceSignal {
  signal: string
  inputLen: number
}

const res = await kalo.fetch<InferenceSignal>('https://provider.kalo.local/infer', {
  method: 'POST',
  maxPriceBaseUnits: 100_000n, // 0.10 USDC ceiling on the client side
  headers: {
    Authorization: 'Bearer internal-token',
    'X-Forwarded-For': '198.51.100.8',
    'X-Kalo-Intent': 'inference',
  },
  body: JSON.stringify({ prompt: 'Evaluate SOL basis spread' }),
})

console.log({
  escrowAddress: res.escrowAddress,
  receiptVerified: res.receiptVerified,
  piiStrippedHeaders: res.piiStrippedHeaders,
  piiFilterLatencyMs: res.piiFilterLatencyMs,
  data: res.data,
})

The returned KaloFetchResponse<T> includes:

FieldTypeMeaning
statusnumberHTTP status from the provider (200 after settlement)
okbooleantrue when execution and receipt verification succeeded
escrowAddressstringBase58 address of the SealedEscrow PDA
requestHashstring0x-prefixed SHA-256 hash of the request payload
outputHashstring0x-prefixed SHA-256 hash of the provider's response
teeSignaturestring0x-prefixed 64-byte Ed25519 signature from the enclave
enclavePubkeystringBase58 Ed25519 public key of the attested enclave
receiptVerifiedbooleantrue once verifyTeeReceipt() passes locally
piiStrippedHeadersstring[]Header names removed before dispatch
piiFilterLatencyMsnumberElapsed filter duration in milliseconds
encryptedBody`string \null`AES-256-GCM hex ciphertext when X-Kalo-Viewing-Key was sent
dataTDecrypted response object (or plaintext result if no viewing key was passed)

3. Gate your own API with kaloGate()

Any Fetch API, Hono, or edge route can require sealed 402 settlement by wrapping its handler in kaloGate():

ts
import { kaloGate } from '@kalo/sdk'

const gatedHandler = 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', // 0.04 USDC
    verifyEscrow: async (escrowAddress, requestHash) => {
      // Check SealedEscrow on-chain or via GET /v1/settlements/:address
      return escrowAddress.length >= 32 && requestHash.startsWith('0x')
    },
  },
  async (bodyText) => {
    return { signal: 'long_vol', inputLen: bodyText.length }
  },
)

Revoke an agent in one transaction

If an agent misbehaves or its task finishes, open Authority Mandates and click Revoke mandate, or build the transaction through POST /v1/mandates/:address/revoke/build. The revoke_mandate instruction flips mandate.revoked = true on-chain, causing any subsequent lock_sealed_402 call to fail with MandateRevoked (6005).

Next steps

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs