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

FieldTypeDescription
statusnumberFinal HTTP status code (200 on settled delivery)
dataTParsed JSON response body from the provider
settlementIdstringu64 settlement ID locked in SettlementEscrow
quoteobjectParsed X-Tova-Quote (provider, priceLamports, requestHash, deadlineSlot, attestationPubkey, hardwareType)
teeVerifiedbooleantrue 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 codeHTTPCauseResolution
MANDATE_REVOKED409Principal revoked the mandateIssue a new mandate on Vaults
MANDATE_EXPIRED409clock.slot > mandate.expiry_slotIssue a new mandate with a future expirySlot
BUDGET_EXCEEDED422Quote price exceeds per_call_cap_bound or remaining epoch_budget_boundWait for next epoch rollover or request a higher limit
NULLIFIER_USED409Duplicate nullifierHash submittedGenerate a fresh salt and settlementId
PROVIDER_CAPACITY_EXCEEDED422Provider's active_unsettled_lamports + amount > staked_capacity_lamportsRetry after open escrows settle (retryable: true) or route to another provider
SETTLEMENT_NOT_EXPIRED409Refund called before deadline_slotWait until clock.slot > deadline_slot

Next step

Decrypt and verify the settlement receipt off-chain in Viewing Keys & Disclosure.