Spending Policies

Configure cryptographically-enforced spending rules for agent accounts. Define velocity limits, merchant restrictions, multi-sig requirements, and time-based controls—all validated on-chain via x402.

---

Overview

Spending policies provide programmable authorization for autonomous agent operations:

• Velocity Limits - Daily/monthly spending caps

• Merchant Whitelists - Approved payee restrictions

• Multi-Sig Thresholds - Amount-based approval requirements

• Time-Based Rules - Scheduled and time-locked controls

• Cryptographic Enforcement - On-chain validation via x402

---

Creating Policies

Basic Policy

const policy = await vault.policies.create({
  accountId: 'acc_7k3m9n2p4q1r',
  name: 'Production Spending Policy',
  rules: [
    {
      type: 'velocity_limit',
      period: 'daily',
      limit: { amount: 5000, currency: 'USDC' }
    },
    {
      type: 'merchant_whitelist',
      allowedPayees: [
        'openai.com',
        'anthropic.com',
        'vercel.com',
        'aws.amazon.com'
      ]
    }
  ],
  enforcement: 'cryptographic' // On-chain validation
});

---

Policy Rules

Velocity Limits

Restrict spending over time periods:

{
  type: 'velocity_limit',
  period: 'daily', // 'hourly' | 'daily' | 'weekly' | 'monthly'
  limit: { amount: 5000, currency: 'USDC' }
}

Merchant Whitelisting

Only allow payments to approved merchants:

{
  type: 'merchant_whitelist',
  allowedPayees: [
    'vercel.com.x402',
    'aws.amazon.com.x402',
    'openai.com.x402'
  ]
}

Multi-Sig Thresholds

Require multiple approvals for large payments:

{
  type: 'threshold_multisig',
  threshold: { amount: 1000, currency: 'USDC' },
  requiredSigners: 2,
  authorizedKeys: [
    '0xabc...', // Deployer key
    '0xdef...'  // Backup key
  ],
  timeout: '24h' // Approval window
}

Time-Based Controls

Restrict when payments can occur:

{
  type: 'time_restriction',
  allowedDays: [1, 2, 3, 4, 5], // Monday-Friday
  allowedHours: { start: 9, end: 17 }, // 9 AM - 5 PM
  timezone: 'America/New_York'
}

---

Complete Policy Example

const comprehensivePolicy = await vault.policies.create({
  accountId: 'acc_7k3m9n2p4q1r',
  name: 'Enterprise Agent Policy',
  rules: [
    // Velocity limits
    {
      type: 'velocity_limit',
      period: 'daily',
      limit: { amount: 10000, currency: 'USDC' }
    },
    {
      type: 'velocity_limit',
      period: 'monthly',
      limit: { amount: 200000, currency: 'USDC' }
    },
    // Merchant whitelist
    {
      type: 'merchant_whitelist',
      allowedPayees: [
        'aws.amazon.com.x402',
        'gcp.google.com.x402',
        'vercel.com.x402',
        'openai.com.x402',
        'anthropic.com.x402'
      ]
    },
    // Multi-sig for large payments
    {
      type: 'threshold_multisig',
      threshold: { amount: 5000, currency: 'USDC' },
      requiredSigners: 2,
      authorizedKeys: [
        '0xkey1...', // Engineering lead
        '0xkey2...', // Finance approver
        '0xkey3...'  // Backup
      ]
    },
    // Time restrictions
    {
      type: 'time_restriction',
      allowedDays: [1, 2, 3, 4, 5],
      allowedHours: { start: 9, end: 17 },
      timezone: 'America/New_York'
    },
    // Geographic restrictions
    {
      type: 'geo_restriction',
      allowedCountries: ['US', 'CA', 'GB', 'EU'],
      blockedCountries: ['KP', 'IR', 'SY']
    }
  ],
  enforcement: 'cryptographic',
  metadata: {
    department: 'engineering',
    cost_center: 'cloud-ops',
    owner: '[email protected]'
  }
});

---

Policy Management

Update Policy

const updated = await vault.policies.update('pol_abc123', {
  rules: [
    // Add new rule
    {
      type: 'velocity_limit',
      period: 'weekly',
      limit: { amount: 30000, currency: 'USDC' }
    },
    // Keep existing rules
    ...existingPolicy.rules
  ]
});

Disable Policy Temporarily

await vault.policies.disable('pol_abc123', {
  reason: 'Emergency maintenance window',
  duration: '2h'
});

// Re-enable
await vault.policies.enable('pol_abc123');

Delete Policy

// Remove policy from account
await vault.policies.delete('pol_abc123');

---

Policy Enforcement

Cryptographic Validation

All policies are enforced on-chain via x402:

// Payment attempt
const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r',
  to: 'merchant.x402',
  amount: 6000,
  currency: 'USDC'
});

// If violates policy (e.g., exceeds daily limit):
// Error: PolicyViolationError
// {
//   code: 'policy_violation',
//   rule: 'velocity_limit',
//   message: 'Daily limit of 5000 USDC exceeded',
//   current: 6000,
//   limit: 5000,
//   policyId: 'pol_abc123'
// }

Policy Validation

Check if payment would violate policies before sending:

const validation = await vault.policies.validate({
  accountId: 'acc_7k3m9n2p4q1r',
  payment: {
    to: 'merchant.x402',
    amount: 3000,
    currency: 'USDC'
  }
});

console.log(validation);
// {
//   allowed: true,
//   violations: [],
//   warnings: [
//     {
//       rule: 'velocity_limit',
//       message: 'This payment will use 60% of daily limit',
//       remaining: 2000
//     }
//   ]
// }

---

Multi-Signature Approvals

Request Approval

// Payment requires multi-sig
const approval = await vault.approvals.request({
  paymentId: 'pay_pending_123',
  requiredSigners: 2,
  message: 'Approve $5,000 payment to AWS for compute',
  expiresAt: '2026-03-14T10:00:00Z'
});

// Notify approvers
approval.approvers.forEach(approver => {
  sendNotification(approver, approval.approvalUrl);
});

Sign Approval

// Approver 1 signs
await vault.approvals.sign('appr_xyz789', {
  signer: '0xkey1...',
  signature: '0xsig1...'
});

// Approver 2 signs
await vault.approvals.sign('appr_xyz789', {
  signer: '0xkey2...',
  signature: '0xsig2...'
});

// Payment executes automatically when threshold met

---

Policy Analytics

Spending Summary

const summary = await vault.policies.getSpendingSummary('pol_abc123', {
  period: 'monthly',
  month: 3,
  year: 2026
});

console.log(summary);
// {
//   totalSpent: 45200,
//   dailyAverage: 1500,
//   limitUtilization: 0.226, // 22.6% of monthly limit
//   topMerchants: [
//     { name: 'aws.amazon.com', amount: 18500 },
//     { name: 'openai.com', amount: 12200 },
//     { name: 'vercel.com', amount: 8900 }
//   ],
//   violations: 0
// }

Violation History

const violations = await vault.policies.getViolations('pol_abc123', {
  startDate: '2026-03-01',
  endDate: '2026-03-31'
});

violations.forEach(v => {
  console.log(`${v.timestamp}: ${v.rule} - ${v.message}`);
  console.log(`  Attempted: ${v.attemptedAmount}`);
  console.log(`  Limit: ${v.limit}`);
});

---

Best Practices

1. Start Restrictive

Begin with tight limits and loosen as needed:

// Initial policy
{
  type: 'velocity_limit',
  period: 'daily',
  limit: { amount: 1000, currency: 'USDC' } // Conservative start
}

// Monitor for 30 days, then adjust
{
  type: 'velocity_limit',
  period: 'daily',
  limit: { amount: 5000, currency: 'USDC' } // Based on usage data
}

2. Layer Multiple Rules

Combine complementary rules for defense-in-depth:

rules: [
  { type: 'velocity_limit', period: 'daily', limit: 5000 },
  { type: 'velocity_limit', period: 'monthly', limit: 100000 },
  { type: 'merchant_whitelist', allowedPayees: [...] },
  { type: 'threshold_multisig', threshold: 1000, requiredSigners: 2 }
]

3. Use Metadata for Tracking

Tag policies for easy management:

metadata: {
  environment: 'production',
  department: 'engineering',
  cost_center: 'cloud-ops-001',
  owner: '[email protected]',
  created_by: '[email protected]',
  last_reviewed: '2026-03-01'
}

4. Regular Policy Reviews

Schedule quarterly reviews:

// Set reminder webhook
await vault.webhooks.create({
  events: ['policy.review_due'],
  url: 'https://api.yourapp.com/policy-review',
  schedule: {
    frequency: 'quarterly',
    reminderDays: 7
  }
});

---

Emergency Procedures

Policy Override

Temporarily bypass policies for emergencies:

// Requires elevated privileges
const override = await vault.policies.createOverride({
  policyId: 'pol_abc123',
  reason: 'Emergency infrastructure scaling',
  duration: '1h',
  authorizedBy: '[email protected]',
  mfaToken: '123456'
});

// Override expires automatically
// All activity logged immutably

Policy Freeze

Lock policy to prevent modifications:

await vault.policies.freeze('pol_abc123', {
  reason: 'Under audit review',
  freezeUntil: '2026-04-01T00:00:00Z'
});

// Attempts to modify will fail

---

Next Steps

• x402 Payments - Execute payments under policies

• Agent Accounts - Manage account policies

• Authorization Engine - Policy architecture

• REST API Reference - Policy endpoints

---

Cryptographically-enforced spending rules