Start

5-Minute Quickstart

Run a shielded HTTP 402 settlement from zero using the web console, @tova/sdk, or the tova CLI.

What you will complete

By the end of this walkthrough you will inspect protocol state, execute a shielded HTTP 402 request against the live attested inference endpoint (POST /api/demo-provider/infer), verify its Ed25519 TEE Execution Receipt, and decrypt the settlement payload with a Viewing Key.

Option 1: Web console

  1. Open Vaults and connect a Solana wallet.
  2. Select SOL or USDC, enter a deposit amount, and click Create & deposit to build and submit create_vault and deposit_shielded.
  3. Select the funded vault, enter an agent public key, per-call ceiling, epoch budget, epoch duration in slots, and expiry slot, then click Issue mandate.
  4. Open Settle, choose the active mandate and registered provider, enter a prompt, and click Send HTTP 402 shielded call.
  5. Toggle between Public ledger and Viewing key on the settlement row to compare the on-chain commitment and nullifier against the locally decrypted amount, fee, and response hash.

Option 2: TypeScript SDK

Install @tova/sdk in your agent project:

bash
npm install @tova/sdk

Create a script that reads an active vault and mandate from the API, runs tova.pay402(), and decrypts the returned receipt:

ts
import { TovaClient, decryptViewingPayload } from '@tova/sdk'

const API_URL = process.env.TOVA_API_URL ?? 'http://127.0.0.1:37402'
const tova = new TovaClient({ apiUrl: API_URL })

const [{ items: vaults }, { items: mandates }] = await Promise.all([
  tova.api.vaults(),
  tova.api.mandates({ status: 'Active' }),
])

const vault = vaults[0]
const mandate = mandates[0]
if (!vault || !mandate) {
  throw new Error('Create a funded vault and an active mandate first.')
}

const result = await tova.pay402<{
  output: string
  responseHash: string
  attestationSignature: string
  attestationPubkey: string
  slot: number
  feeLamports: string
  encryptedReceipt: string
}>(`${API_URL}/api/demo-provider/infer`, {
  agent: mandate.agent,
  vault: vault.address,
  mandate: mandate.address,
  body: { prompt: 'Summarize shielded 402 receipt verification' },
})

console.log('Settlement ID:', result.settlementId)
console.log('TEE verified:', result.teeVerified)
console.log('Output:', result.data.output)

const viewingKey = process.env.TOVA_VIEWING_KEY ?? '00'.repeat(32)
const decrypted = decryptViewingPayload(viewingKey, result.data.encryptedReceipt)
console.log('Decrypted receipt:', decrypted)

Behind that single tova.pay402() call, the SDK runs four steps:

  1. Sends POST /api/demo-provider/infer and parses the HTTP 402 X-Tova-Quote header.
  2. Calls POST /v1/settlements/open/build to lock the shielded commitment and 192-byte Groth16 proof envelope under your mandate.
  3. Retries POST /api/demo-provider/infer with X-Tova-Settlement: <settlementId>.
  4. Verifies the provider's Ed25519 signature over TOVA_TEE_RECEIPT_V1 || settlement_id || request_hash || response_hash || slot and returns teeVerified: true.

Option 3: CLI

Install the @tova/cli package to expose the tova binary, then check protocol health and counters:

bash
tova status

Real output from a running Tova API (http://127.0.0.1:37402):

json
{
  "health": {
    "status": "fixture",
    "mode": "fixture",
    "cluster": "localnet",
    "programId": "C5K5LF7CGN5zKf7mxHxy5PYQHnvzHEui7dtkLZ1ytmb9",
    "asOf": "2026-11-22T10:53:20.305Z"
  },
  "stats": {
    "programId": "C5K5LF7CGN5zKf7mxHxy5PYQHnvzHEui7dtkLZ1ytmb9",
    "feeRecipient": "CMR92vY5iHC1o6pVCrpSpK1qrye4yQdWPkp4fukeUrbC",
    "feeBps": 25,
    "paused": false,
    "cluster": "localnet",
    "shieldedVaultCount": 2,
    "activeMandateCount": 1,
    "totalMandateCount": 2,
    "registeredProviderCount": 2,
    "settledReceiptCount": 2,
    "openEscrowCount": 1,
    "refundedEscrowCount": 1,
    "totalProtocolFeesLamports": "250000",
    "totalBurnedTova": "0",
    "burnCount": 0
  }
}

Execute a live shielded 402 call from the terminal:

bash
tova settle pay402 --prompt "Summarize shielded 402 receipt verification"

Decrypt the encryptedReceipt string returned in the JSON output:

bash
tova decrypt <encryptedReceiptBase64> --key <viewingKeyHex32>
Set TOVA_API_URL to point the CLI at any Tova API instance. Without it, tova targets http://127.0.0.1:37402.