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
| Field | Meaning | Validation rule |
|---|---|---|
perCallCapLamports | Maximum spend allowed in a single open_settlement | Positive u64 |
epochBudgetLamports | Maximum cumulative spend per epoch window | >= perCallCapLamports |
epochDurationSlots | Length of one budget epoch in Solana slots | 10 to 50,000,000 (~216,000 slots is ~24 hours at 400 ms/slot) |
expirySlot | Final Solana slot when the mandate can open settlements | Must be greater than clock.slot |
allowedProvider | Optional provider PDA to restrict spending | Omit to set openProviders: true |
auditorKeyTag | Optional 32-byte hex tag for scoped audit decryption | 64 hex chars |
Step 2: Issue the mandate
Web console
- Open Vaults and select your funded Ring Vault.
- Fill in the Issue mandate form: agent public key, per-call cap, epoch budget, epoch duration in slots, and expiry slot.
- Click Issue mandate, approve the wallet signature, and wait for confirmation. The new mandate appears in the mandate list with status
Active.
TypeScript SDK
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
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
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
| Error | Cause | Fix |
|---|---|---|
InvalidMandateLimits | per_call_cap_bound == 0, epoch_budget_bound < per_call_cap_bound, or epoch_duration_slots == 0 | Ensure 0 < perCallCapLamports <= epochBudgetLamports and epochDurationSlots >= 10 |
MandateExpired | expiry_slot <= clock.slot | Fetch the current slot and set expirySlot ahead of it |
MandateRevoked | Calling revoke_mandate on a mandate that is already inactive | Check mandate.active before revoking |
Next step
Use your active mandate to pay a live HTTP 402 provider in Pay an HTTP 402 Endpoint.