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 & pathDescription
GET /healthReturns { status, cluster, programId, slot, dbOk, contractVersion, asOf }
GET /v1/protocol/statsReturns { programId, cluster, launchWallet, kaloMint, feeBps, totalRings, activeMandates, attestedProviders, settledEscrows, totalShieldedCommitments, asOf }

Privacy Rings

Method & pathRequest / queryResponse
GET /v1/rings?owner=&mint=&limit=&cursor=RingsPage
GET /v1/rings/:address?viewingKey= or X-Kalo-Viewing-KeyPrivacyRingDetail (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 & pathRequest / queryResponse
GET /v1/mandates`?ring=&owner=&agent=&status=active\revoked\expired\all`MandatesPage
GET /v1/mandates/:addressPath addressAuthorityMandate
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 & pathRequest / queryResponse
GET /v1/providersNoneProvidersPage (ordered by settledCount desc)
GET /v1/providers/:addressPath addressEnclaveProvider
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 & pathRequest / queryResponse
GET /v1/settlements`?ring=&mandate=&provider=&state=locked\settled\refunded&viewingKey=`SettlementsPage
GET /v1/settlements/:address?viewingKey= or X-Kalo-Viewing-KeySealedEscrow
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 & pathDescription
POST /v1/transactions/submitSubmit a signed transaction ({ id, signedTransactionBase64?, signature? }) -> TxStatusResponse
GET /v1/transactions/:idPoll transaction status (built, submitted, confirmed, finalized, failed, expired)
GET /v1/eventsServer-Sent Events stream (ring_created, utxo_shielded, utxo_unshielded, mandate_issued, mandate_revoked, enclave_registered, escrow_locked, escrow_settled, escrow_refunded)
POST /rpcSolana JSON-RPC relay for browser wallet reads
POST /auth/nonce, POST /auth/verify, POST /auth/logout, GET /auth/sessionSign-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.

MethodparamsResult 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:

json
{
  "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

CodeHTTPMeaning
PAYMENT_REQUIRED402Paid request missing locked SealedEscrow
MANDATE_REVOKED403AuthorityMandate has been revoked
MANDATE_EXPIRED403AuthorityMandate passed expiresAt
CAP_EXCEEDED403Amount exceeds perCallCap or remaining epochBudget
CATEGORY_FORBIDDEN403Provider category bit not permitted by categoryMask
ENCLAVE_INACTIVE403Provider enclave is inactive or past expiresSlot
NULLIFIER_SPENT409UTXO nullifier already consumed in NullifierSet
ESCROW_EXPIRED409Escrow is already settled or refunded
ESCROW_NOT_EXPIRED409Escrow has not yet passed timeoutSlot
INVALID_TEE_RECEIPT422Ed25519 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.

Confidential commerce infrastructure for autonomous software.

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

Open consoleRead the docs