Guides

Issue an Agent Mandate

Delegate bounded per-call and epoch spending authority to an agent signing key, and revoke it in one transaction.

Prerequisites

  • An existing funded Ring Vault.
  • The agent's Solana public key (agent). The agent only needs enough SOL in its own keypair to pay transaction fees and escrow rent, never the spending treasury.

Step 1: Choose policy parameters

FieldMeaningValidation rule
perCallCapLamportsMaximum spend allowed in a single open_settlementPositive u64
epochBudgetLamportsMaximum cumulative spend per epoch window>= perCallCapLamports
epochDurationSlotsLength of one budget epoch in Solana slots10 to 50,000,000 (~216,000 slots is ~24 hours at 400 ms/slot)
expirySlotFinal Solana slot when the mandate can open settlementsMust be greater than clock.slot
allowedProviderOptional provider PDA to restrict spendingOmit to set openProviders: true
auditorKeyTagOptional 32-byte hex tag for scoped audit decryption64 hex chars

Step 2: Issue the mandate

Web console

  1. Open Vaults and select your funded Ring Vault.
  2. Fill in the Issue mandate form: agent public key, per-call cap, epoch budget, epoch duration in slots, and expiry slot.
  3. Click Issue mandate, approve the wallet signature, and wait for confirmation. The new mandate appears in the mandate list with status Active.

TypeScript SDK

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

const tova = new TovaClient({ apiUrl: 'http://127.0.0.1:37402' })

const built = await tova.api.buildIssueMandate({
  principal: process.env.PRINCIPAL_PUBKEY!,
  vault: process.env.TOVA_VAULT_PDA!,
  agent: process.env.TOVA_AGENT_PUBKEY!,
  perCallCapLamports: '50000000',     // 0.05 SOL max per HTTP 402 call
  epochBudgetLamports: '500000000',   // 0.5 SOL max per epoch
  epochDurationSlots: 216_000,
  expirySlot: 350_000_000,
})

console.log('Mandate PDA:', built.targetAddress)
console.log('Unsigned v0 tx:', built.transactionBase64)

Sign built.transactionBase64 with the principal wallet and submit it via tova.api.submitTransaction({ id: built.id, signedTransactionBase64 }).

If you omit mandateId, the API assigns a deterministic timestamp-based u64. Pass an explicit mandateId string when you want to precompute the PDA (["mandate", vault, mandate_id_u64_le]).

Step 3: Verify the active mandate via CLI

bash
tova mandate list --vault <vaultPda>
tova mandate get <mandatePda>

Check that status is "Active", active is true, and agent matches the keypair your agent process signs with.

Step 4: Revoke a mandate

Revocation takes one principal-signed transaction and immediately blocks new open_settlement calls.

Web console

Open Vaults, locate the mandate row, and click Revoke.

TypeScript SDK

ts
const revokeBuilt = await tova.api.buildRevokeMandate(mandatePda, {
  principal: process.env.PRINCIPAL_PUBKEY!,
})

Sign and submit revokeBuilt.transactionBase64. On confirmation, Mandate.active becomes false and MandateRevokedEvent is emitted. Any Open escrows created before revocation still resolve by claim_settlement or timeout refund_settlement.

Common failures

ErrorCauseFix
InvalidMandateLimitsper_call_cap_bound == 0, epoch_budget_bound < per_call_cap_bound, or epoch_duration_slots == 0Ensure 0 < perCallCapLamports <= epochBudgetLamports and epochDurationSlots >= 10
MandateExpiredexpiry_slot <= clock.slotFetch the current slot and set expirySlot ahead of it
MandateRevokedCalling revoke_mandate on a mandate that is already inactiveCheck mandate.active before revoking

Next step

Use your active mandate to pay a live HTTP 402 provider in Pay an HTTP 402 Endpoint.