Guides
Pay an HTTP 402 Endpoint
Call a Tova-gated HTTP 402 service with tova.pay402(), verify its TEE execution receipt, and claim timeout refunds.
Prerequisites
- A funded Ring Vault PDA (
vault). - An active Shielded Mandate PDA (
mandate) bound to your agent public key (agent). - A registered Tova HTTP 402 endpoint URL (for local testing,
http://127.0.0.1:37402/api/demo-provider/infer).
Step 1: Call the endpoint with tova.pay402()
TovaClient.pay402() wraps the entire quote, escrow lock, retry, and TEE receipt verification flow into one call:
ts
import { TovaClient } from '@tova/sdk'
const tova = new TovaClient({
apiUrl: process.env.TOVA_API_URL ?? 'http://127.0.0.1:37402',
})
interface InferResponse {
output: string
model: string
settlementId: string
settlementAddress: string
requestHash: string
responseHash: string
slot: number
attestationSignature: string
attestationPubkey: string
hardwareType: string
claimTxSignature: string
feeLamports: string
encryptedReceipt: string
}
const result = await tova.pay402<InferResponse>(
'http://127.0.0.1:37402/api/demo-provider/infer',
{
method: 'POST',
agent: process.env.TOVA_AGENT_PUBKEY!,
vault: process.env.TOVA_VAULT_PDA!,
mandate: process.env.TOVA_MANDATE_PDA!,
body: {
prompt: 'Analyze recent Solana Privacy Ring slot utilization',
model: 'tova-tee-llama-3-8b',
},
},
)
if (!result.teeVerified) {
throw new Error('TEE execution receipt signature failed verification')
}
console.log('Settlement ID:', result.settlementId)
console.log('Hardware:', result.quote.hardwareType)
console.log('Response:', result.data.output)What pay402() returns
| Field | Type | Description |
|---|---|---|
status | number | Final HTTP status code (200 on settled delivery) |
data | T | Parsed JSON response body from the provider |
settlementId | string | u64 settlement ID locked in SettlementEscrow |
quote | object | Parsed X-Tova-Quote (provider, priceLamports, requestHash, deadlineSlot, attestationPubkey, hardwareType) |
teeVerified | boolean | true when the returned attestationSignature verifies against attestationPubkey over TOVA_TEE_RECEIPT_V1 |
Step 2: Run from the CLI or web console
From the terminal:
bash
tova settle pay402 \
--url http://127.0.0.1:37402/api/demo-provider/infer \
--prompt "Analyze recent Solana Privacy Ring slot utilization"From the browser, open Settle, choose an active mandate and provider, enter a prompt, and click Send HTTP 402 shielded call.
Step 3: Handle timeout refunds
If a provider never claims an Open escrow before deadlineSlot, reclaim the locked capacity and epoch budget by building refund_settlement:
ts
const refundTx = await tova.api.buildRefundSettlement(settlementAddress, {
caller: process.env.TOVA_AGENT_PUBKEY!,
})Sign and submit refundTx.transactionBase64 once clock.slot > escrow.deadline_slot. On Settle, clicking Refund on any Open settlement runs this flow directly.
Any signer (principal, agent, or keeper) can submit
refund_settlement once deadline_slot has passed. Funds remain in the vault's vault_escrow PDA and mandate.epoch_spent is restored when refunded within the same epoch.Common failures
| Error code | HTTP | Cause | Resolution |
|---|---|---|---|
MANDATE_REVOKED | 409 | Principal revoked the mandate | Issue a new mandate on Vaults |
MANDATE_EXPIRED | 409 | clock.slot > mandate.expiry_slot | Issue a new mandate with a future expirySlot |
BUDGET_EXCEEDED | 422 | Quote price exceeds per_call_cap_bound or remaining epoch_budget_bound | Wait for next epoch rollover or request a higher limit |
NULLIFIER_USED | 409 | Duplicate nullifierHash submitted | Generate a fresh salt and settlementId |
PROVIDER_CAPACITY_EXCEEDED | 422 | Provider's active_unsettled_lamports + amount > staked_capacity_lamports | Retry after open escrows settle (retryable: true) or route to another provider |
SETTLEMENT_NOT_EXPIRED | 409 | Refund called before deadline_slot | Wait until clock.slot > deadline_slot |
Next step
Decrypt and verify the settlement receipt off-chain in Viewing Keys & Disclosure.