v1.4 Agent Mandates

Shipped: 2026-04-07 | Phases: 2 (27–28) | Plans: 13 | Audit: Passed after remediation

The fastest-shipping milestone (1 day) and the first to prove that agent payment ceilings can be enforced on-chain. Agent mandates won 1st place in two tracks at the Colosseum hackathon, and this milestone made the on-chain enforcement real.

What Shipped

Phase 27: Agent Mandate Protocol

The on-chain agent spending control primitive.

• AgentMandate PDA — Represents an agent's spending authority with configurable limits:
  • Daily spending limit
  • Lifetime spending limit
  • Per-service spending limit
  • Minimum pull amount (anti-dust protection)
  • Pull cooldown (rate limiting)
• 7 Anchor instructions:
  • create_agent_mandate — Establish spending limits for an agent
  • agent_pull — Execute a payment within mandate bounds
  • revoke — Permanently revoke agent spending authority
  • adjust — Modify spending limits (upward only for safety)
  • pause / resume — Temporarily suspend agent spending
  • drain — Withdraw remaining mandate balance
• Ephemeral PullApproval reuse — agent_pull reuses the existing PullApproval PDA pattern with zero transfer hook changes required
• Full LiteSVM test suite — 13 passing scenarios covering creation, pulls, limits, cooldowns, revocation, pause/resume, and drain
• CU profiling — agent_pull confirmed within 300K compute units

Phase 28: SDK + x402 + CLI + Observability

The developer surface for agent mandates.

• 15 SDK methods — Convenience methods for the full agent mandate lifecycle
• x402 client/server middleware:
  • VelaPaymentHandler (client) — Translate HTTP 402 responses into mandate creation requests
  • createX402Middleware (server, Hono) — Accept mandate-based payments for API access
• 9 CLI commands — Agent mandate management via the vela CLI tool
• Helius webhook registration — For agent mandate events (creation, pull, revocation)

Key Architecture

AgentMandate PDA Design

The AgentMandate account stores:

pub struct AgentMandate {
    pub merchant: Pubkey,         // Who authorized the agent
    pub agent: Pubkey,            // The agent's identity
    pub mint: Pubkey,             // Token mint for payments
    pub daily_limit: u64,         // Max spend per day
    pub daily_spent: u64,         // Amount spent today
    pub daily_reset: i64,         // Timestamp of last daily reset
    pub lifetime_limit: u64,      // Max total spend
    pub lifetime_spent: u64,      // Total amount spent
    pub per_service_limit: u64,   // Max spend per service
    pub min_pull_amount: u64,     // Anti-dust minimum
    pub pull_cooldown: i64,       // Seconds between pulls
    pub last_pull: i64,           // Timestamp of last pull
    pub active: bool,             // Paused/resumed state
}

Ephemeral PullApproval in agent_pull

The key design insight: agent_pull reuses the existing PullApproval PDA without modifying the transfer hook. The agent pull:

1. Validates mandate limits (daily, lifetime, per-service, cooldown, min amount)
2. Creates an ephemeral PullApproval PDA
3. Executes the transfer through the existing hook path
4. The transfer hook validates the PullApproval (same as regular pulls)

This means zero changes to the transfer hook program for agent support.

x402 Adapter

The x402 (HTTP 402 Payment Required) adapter translates the standard HTTP payment protocol into VelaPay mandate operations:

• Client receives 402 → Checks for matching mandate → Creates one if needed → Retries with payment proof
• Server sends 402 → Middleware intercepts → Verifies mandate payment → Forwards request

This enables pay-per-request API access powered by VelaPay mandates.

Why This Matters

Agent payments won 1st place in two tracks at the Colosseum hackathon. But existing solutions have fundamental limitations:

Solution	Enforcement	Limitation
MCPay	Per-request	No spending ceiling — each request is independent
Latinum	Wallet-middleware	Off-chain enforcement — agent can exceed limits if middleware is bypassed
VelaPay	On-chain	Spending ceiling enforced by the blockchain. No bypass possible.

VelaPay is the first platform where an agent's spend ceiling is cryptographically enforced. The mandate PDA is the spending limit, and the transfer hook is the enforcement mechanism.

What the Audit Found

The v1.4 audit caught several issues that were fixed before shipping:

SDK/x402 Security Gaps

• x402 verification trusted request-provided challenge state too much
• Malformed proofs could produce server errors instead of payment failures
• Nonce consumption happened before proof verification
• POST retries could lose request bodies

CLI/Runtime Gaps

• agent-pull --mandate didn't propagate the mandate argument to the SDK builder
• Published CLI entrypoint wasn't Node-safe
• Packaged CLI eagerly loaded LiteSVM-native code even for non-simulate commands

Protocol Gaps

• Negative min_pull_interval values were accepted
• Mandate/service limits could be adjusted below already-recorded spend
• agent_pull lacked explicit InsufficientMandateBalance preflight check

All fixed and regression-covered before milestone closure.

Final Validation

Command	Result
cd vela-sdk && bun test	PASS
cd vela-sdk && bun run check	PASS
cd vela-sdk && bun run build	PASS
cd vela-sdk && node ./bin/vela --help	PASS
cd vela-protocol && anchor build && cargo test	PASS

Key Lessons

1. Reuse existing primitives — Agent mandates leveraged the PullApproval PDA and transfer hook without modification. Building on existing infrastructure is faster and safer than creating parallel paths.
2. Ephemeral PDAs are powerful — Creating a temporary PullApproval for agent pulls means the transfer hook doesn't need to know about agents at all. Separation of concerns at the protocol level.
3. Security audit matters even for "simple" features — The audit found real security issues in x402 proof verification. A focused milestone is not an excuse to skip security review.
4. CU budgeting early — Profiling agent_pull within 300K CU in Phase 27 prevented budget surprises in later milestones.

Links

• ← v1.3 Merchant Login UX
• v1.5 Hosted Checkout & Billing →
• ← Back to Overview