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
- Open Vaults and connect a Solana wallet.
- Select SOL or USDC, enter a deposit amount, and click Create & deposit to build and submit
create_vaultanddeposit_shielded. - 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.
- Open Settle, choose the active mandate and registered provider, enter a prompt, and click Send HTTP 402 shielded call.
- 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:
npm install @tova/sdkCreate a script that reads an active vault and mandate from the API, runs tova.pay402(), and decrypts the returned receipt:
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:
- Sends
POST /api/demo-provider/inferand parses theHTTP 402X-Tova-Quoteheader. - Calls
POST /v1/settlements/open/buildto lock the shielded commitment and 192-byte Groth16 proof envelope under your mandate. - Retries
POST /api/demo-provider/inferwithX-Tova-Settlement: <settlementId>. - Verifies the provider's Ed25519 signature over
TOVA_TEE_RECEIPT_V1 || settlement_id || request_hash || response_hash || slotand returnsteeVerified: true.
Option 3: CLI
Install the @tova/cli package to expose the tova binary, then check protocol health and counters:
tova statusReal output from a running Tova API (http://127.0.0.1:37402):
{
"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:
tova settle pay402 --prompt "Summarize shielded 402 receipt verification"Decrypt the encryptedReceipt string returned in the JSON output:
tova decrypt <encryptedReceiptBase64> --key <viewingKeyHex32>TOVA_API_URL to point the CLI at any Tova API instance. Without it, tova targets http://127.0.0.1:37402.What to read next
- Understand how encrypted UTXO commitments and nullifiers work in Ring Vaults.
- Configure per-call and epoch ceilings in Issue an Agent Mandate.
- Wrap your own paid HTTP endpoint in Register a TEE Provider.