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
- Open Rings & Shielded Treasury and connect a Solana wallet.
- Click Create Ring, choose a settlement mint (USDC, SOL, or another SPL mint) and compliance mode (
PermissionlessorAllowlisted), and optionally attach an auditor public key. Sign thecreate_ringtransaction. - 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. - 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
60seconds), service category bitmask, and expiry timestamp. - Open Sealed 402 Console, pick the active mandate and an attested provider from Attested Providers, enter a prompt, and click Run sealed 402.
- 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):
npm install @kalo/sdk @solana/web3.js1. 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.
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.
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:
| Field | Type | Meaning | |
|---|---|---|---|
status | number | HTTP status from the provider (200 after settlement) | |
ok | boolean | true when execution and receipt verification succeeded | |
escrowAddress | string | Base58 address of the SealedEscrow PDA | |
requestHash | string | 0x-prefixed SHA-256 hash of the request payload | |
outputHash | string | 0x-prefixed SHA-256 hash of the provider's response | |
teeSignature | string | 0x-prefixed 64-byte Ed25519 signature from the enclave | |
enclavePubkey | string | Base58 Ed25519 public key of the attested enclave | |
receiptVerified | boolean | true once verifyTeeReceipt() passes locally | |
piiStrippedHeaders | string[] | Header names removed before dispatch | |
piiFilterLatencyMs | number | Elapsed filter duration in milliseconds | |
encryptedBody | `string \ | null` | AES-256-GCM hex ciphertext when X-Kalo-Viewing-Key was sent |
data | T | Decrypted 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():
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
- Learn how the on-chain accounts fit together in Core Concepts.
- Walk through Ring creation and shielding in Creating a Privacy Ring.
- See every provider option in Gating an API with HTTP 402.