Reference
REST & SPR Indexer API
Every public Hono REST endpoint, unsigned v0 transaction builder, Helius SPR-compatible JSON-RPC method, SIWS auth route, SSE stream, and error code.
Contract version and conventions
- Contract version:
0.1.0 - Timestamps: ISO-8601 UTC strings (
asOf, createdAt, expiresAt, settledAt) - Token amounts: Decimal base-unit strings (
BaseUnits, PositiveU64, U64) to preserve exact 64-bit precision in JSON - Pagination: List endpoints accept
?limit=<n>&cursor=<token> and return { items, page, asOf } - Rate limits: Mutating
/v1/* routes allow 120 requests per window; /auth/verify allows 30 - Viewing key disclosure: Pass
X-Kalo-Viewing-Key header or ?viewingKey= query parameter on Ring and Settlement reads to populate plaintext fields
Health and protocol stats
| Method & path | Description |
|---|
GET /health | Returns { status, cluster, programId, slot, dbOk, contractVersion, asOf } |
GET /v1/protocol/stats | Returns { programId, cluster, launchWallet, kaloMint, feeBps, totalRings, activeMandates, attestedProviders, settledEscrows, totalShieldedCommitments, asOf } |
Privacy Rings
| Method & path | Request / query | Response |
|---|
GET /v1/rings | ?owner=&mint=&limit=&cursor= | RingsPage |
GET /v1/rings/:address | ?viewingKey= or X-Kalo-Viewing-Key | PrivacyRingDetail (includes utxos[]) |
POST /v1/rings/build | { owner, mint, symbol?, decimals?, complianceMode, auditorPubkey? } | TxBuildResponse (derivedAddresses.ringAddress) |
POST /v1/rings/:address/shield/build | { owner, amountBaseUnits, commitmentHex?, encryptedNoteHex?, viewTag? } | TxBuildResponse (derivedAddresses.commitment, viewTag) |
POST /v1/rings/:address/unshield/build | { owner, recipient, nullifierHex, amountBaseUnits, proofHex? } | TxBuildResponse |
Authority Mandates
| Method & path | Request / query | Response |
|---|
GET /v1/mandates | `?ring=&owner=&agent=&status=active\ | revoked\ | expired\ | all` | MandatesPage |
GET /v1/mandates/:address | Path address | AuthorityMandate |
POST /v1/mandates/build | { owner, ringAddress, agentPubkey, label?, perCallCap, epochBudget, epochDurationSec?, categoryMask?, expiresAt } | TxBuildResponse (derivedAddresses.mandateAddress) |
POST /v1/mandates/:address/revoke/build | { owner } | TxBuildResponse |
Attested Providers & Blind Reputation
| Method & path | Request / query | Response |
|---|
GET /v1/providers | None | ProvidersPage (ordered by settledCount desc) |
GET /v1/providers/:address | Path address | EnclaveProvider |
POST /v1/providers/register/build | { authority, name, description?, endpointUrl, enclavePubkey, hardwareType, measurementHash, serviceCategory?, priceBaseUnits, mint, symbol?, attestationQuoteHex? } | TxBuildResponse (derivedAddresses.providerAddress) |
POST /v1/providers/:address/verify-reputation | { sponsorRing?, minSettledCount? } | ReputationVerification |
Sealed 402 Settlements & Live Demo Provider
| Method & path | Request / query | Response |
|---|
GET /v1/settlements | `?ring=&mandate=&provider=&state=locked\ | settled\ | refunded&viewingKey=` | SettlementsPage |
GET /v1/settlements/:address | ?viewingKey= or X-Kalo-Viewing-Key | SealedEscrow |
POST /v1/settlements/lock/build | { agentPubkey, ringAddress, mandateAddress, providerAddress, requestHash, amountBaseUnits, timeoutSlots? } | TxBuildResponse (derivedAddresses.escrowAddress, nullifier, commitmentIn) |
POST /v1/settlements/:address/settle/build | { providerAuthority, outputHash, teeSignatureHex, encryptedReceiptHex? } | TxBuildResponse |
POST /v1/settlements/:address/refund/build | { caller } | TxBuildResponse |
POST /v1/demo/infer | { prompt, mandateAddress?, providerAddress?, amountBaseUnits?, viewingKey?, simulateHeaders? } | DemoInferChallenge (402 when X-Kalo-Mode: challenge) or DemoInferResult (200 when X-Kalo-Mode: execute or X-Kalo-Escrow is set) |
Transaction relay, RPC relay, SIWS auth, and SSE
| Method & path | Description |
|---|
POST /v1/transactions/submit | Submit a signed transaction ({ id, signedTransactionBase64?, signature? }) -> TxStatusResponse |
GET /v1/transactions/:id | Poll transaction status (built, submitted, confirmed, finalized, failed, expired) |
GET /v1/events | Server-Sent Events stream (ring_created, utxo_shielded, utxo_unshielded, mandate_issued, mandate_revoked, enclave_registered, escrow_locked, escrow_settled, escrow_refunded) |
POST /rpc | Solana JSON-RPC relay for browser wallet reads |
POST /auth/nonce, POST /auth/verify, POST /auth/logout, GET /auth/session | Sign-In With Solana (SIWS) header-transport session routes |
Helius SPR-compatible JSON-RPC (POST /v1/spr/rpc)
Accepts JSON-RPC 2.0 payloads ({ jsonrpc: "2.0", id, method, params }). When HELIUS_SPR_URL is configured on the server, requests proxy directly to Helius mainnet SPR.
| Method | params | Result shape |
|---|
getUserRecords | { owner?: string } | { records: [{ ringAddress, mint, merkleRoot, commitmentCount, complianceMode }] } |
getEncryptedUtxosByTags | { tags?: string[] } | { utxos: [{ commitment, ringAddress, leafIndex, viewTag, encryptedNote, spent, slot }] } (max 100) |
getShieldedTransactionsByTags | { ring?: string } | { transactions: [{ escrowAddress, ringAddress, nullifier, commitmentIn, providerCommitment, feeCommitment, state, lockTxSignature, settleTxSignature }] } (max 50) |
Error envelope and status codes
Every failed response returns one structured JSON envelope:
{
"error": {
"code": "CAP_EXCEEDED",
"message": "Call amount exceeds mandate per-call cap.",
"retryable": false,
"stage": "validation",
"fieldErrors": {},
"requestId": "req_..."
}
}
stage is one of: validation, auth, read, upload, build, wallet, co_sign, simulation, send, confirmation.
Kalo domain error codes
| Code | HTTP | Meaning |
|---|
PAYMENT_REQUIRED | 402 | Paid request missing locked SealedEscrow |
MANDATE_REVOKED | 403 | AuthorityMandate has been revoked |
MANDATE_EXPIRED | 403 | AuthorityMandate passed expiresAt |
CAP_EXCEEDED | 403 | Amount exceeds perCallCap or remaining epochBudget |
CATEGORY_FORBIDDEN | 403 | Provider category bit not permitted by categoryMask |
ENCLAVE_INACTIVE | 403 | Provider enclave is inactive or past expiresSlot |
NULLIFIER_SPENT | 409 | UTXO nullifier already consumed in NullifierSet |
ESCROW_EXPIRED | 409 | Escrow is already settled or refunded |
ESCROW_NOT_EXPIRED | 409 | Escrow has not yet passed timeoutSlot |
INVALID_TEE_RECEIPT | 422 | Ed25519 receipt signature failed verification |
Base API error codes
VALIDATION_ERROR (400), UNAUTHORIZED (401), ORIGIN_NOT_ALLOWED (403), NOT_FOUND (404), PROGRAM_UNAVAILABLE (409), CONFIGURATION_REQUIRED (409), IDEMPOTENCY_CONFLICT (409), TRANSACTION_EXPIRED (409), PAYLOAD_TOO_LARGE (413), UNSUPPORTED_MEDIA_TYPE (415), SIMULATION_FAILED (422), CHAIN_REFUSED (422), RATE_LIMITED (429), INTERNAL_ERROR (500), UPSTREAM_UNAVAILABLE (502).
Fixture scenarios for client testing
Pass X-Fixture (or ?fixture=) on read or build endpoints to test UI states deterministically: empty, waiting, revoked, refunded, or any error code listed above.