Spending Policies

Configure spending policies for AI agent accounts with on-chain enforcement via Solana smart contracts. Define amount limits, merchant allowlists, time restrictions, and multi-signature requirements—all validated cryptographically before payment execution.

Overview

Spending policies provide programmable authorization controls for autonomous AI agents:

Amount Limits: Per-transaction, daily, weekly, monthly spending caps
Merchant Allowlists: Restrict payments to approved Solana addresses
Time-Based Rules: Scheduled payment windows and blackout periods
Multi-Signature: Require multiple approvals for high-value payments
On-Chain Enforcement: Policies enforced by Solana smart contracts
Category Restrictions: Spending limits by service category (APIs, compute, data)

Creating Policies

Basic Policy

const policy = await mppfi.policies.create({
  agentId: 'agt_7xK9mN2pQ1',
  name: 'Production Agent Policy',
  rules: [
    {
      type: 'amount_limit',
      period: 'daily',
      limit: { amount: 500.00, currency: 'USDC' }
    },
    {
      type: 'merchant_allowlist',
      addresses: [
        'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P', // OpenAI
        '8qN5L3kZ9xM2vY7cB4jT6wE1rP9sU5hG3fD8aQ2nK7m', // Anthropic
        'F3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3k'  // AWS
      ]
    }
  ],
  enforcement: 'on_chain' // Enforced by Solana smart contract
});

console.log(`Policy ID: ${policy.id}`);
console.log(`Contract address: ${policy.blockchain.contract_address}`);

Response:

{
  "id": "pol_4zT8mN9pQ3",
  "object": "policy",
  "agent_id": "agt_7xK9mN2pQ1",
  "name": "Production Agent Policy",
  "status": "active",
  "enforcement": "on_chain",
  "blockchain": {
    "network": "solana-mainnet",
    "contract_address": "PoLiCy7xN3vQ8mK2jR5wT9zL4cF6hG1dS3aE5yU2nB",
    "deployed_at": "2025-01-15T10:30:00Z",
    "tx_signature": "3JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA"
  },
  "rules": [...],
  "created_at": "2025-01-15T10:30:00Z"
}

Policy Rules

1. Amount Limits

Restrict spending over time periods:

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

Example with multiple periods:

rules: [
  {
    type: 'amount_limit',
    period: 'daily',
    limit: { amount: 500.00, currency: 'USDC' }
  },
  {
    type: 'amount_limit',
    period: 'weekly',
    limit: { amount: 2000.00, currency: 'USDC' }
  },
  {
    type: 'amount_limit',
    period: 'monthly',
    limit: { amount: 7500.00, currency: 'USDC' }
  }
]

2. Merchant Allowlists

Only allow payments to approved Solana addresses:

{
  type: 'merchant_allowlist',
  addresses: [
    'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
    '8qN5L3kZ9xM2vY7cB4jT6wE1rP9sU5hG3fD8aQ2nK7m',
    'F3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3k'
  ],
  description: 'Approved AI service providers'
}

Domain-based allowlist (via MPP):

from mppfi import PolicyRule

rule = PolicyRule.merchant_allowlist(
    domains=[
        'api.openai.com',
        'api.anthropic.com',
        'api.together.ai',
        'aws.amazon.com'
    ],
    # MPPFi resolves domains to Solana addresses via MPP
    resolve_via_mpp=True
)

3. Transaction Amount Limits

Per-transaction maximums:

{
  type: 'per_transaction_limit',
  limit: {
    amount: 100.00,
    currency: 'USDC'
  },
  description: 'No single payment above $100'
}

4. Category Restrictions

Spending limits by service category:

{
  type: 'category_limit',
  categories: {
    'ai_services': { amount: 300.00, period: 'daily' },
    'cloud_compute': { amount: 200.00, period: 'daily' },
    'data_storage': { amount: 50.00, period: 'daily' },
    'api_calls': { amount: 100.00, period: 'daily' }
  },
  currency: 'USDC'
}

5. Time-Based Controls

Restrict when payments can occur:

{
  type: 'time_restriction',
  allowed_days: [1, 2, 3, 4, 5], // Monday-Friday (1=Monday, 7=Sunday)
  allowed_hours: { start: 9, end: 17 }, // 9 AM - 5 PM
  timezone: 'America/New_York'
}

Example with blackout periods:

{
  type: 'time_restriction',
  blackout_periods: [
    {
      start: '2025-12-24T00:00:00Z',
      end: '2025-12-26T23:59:59Z',
      reason: 'Holiday freeze'
    }
  ]
}

6. Multi-Signature Requirements

Require multiple approvals for high-value payments:

use mppfi::{PolicyRule, MultiSigConfig};

let rule = PolicyRule::MultiSignature {
    threshold_amount: 1000.0,
    threshold_currency: "USDC".to_string(),
    required_signers: 2,
    authorized_pubkeys: vec![
        "5kN3vQ8mK2jR5wT9zL4cF6hG1dS3aE5yU2nB7xP4mL9w".to_string(), // Admin 1
        "3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3kZ1".to_string(), // Admin 2
        "7jT6wE1rP9sU5hG3fD8aQ2nK7mY4vB6cL8xN5zR9wQ2".to_string(), // Admin 3
    ],
    approval_timeout: 86400, // 24 hours in seconds
};

7. Velocity Limits

Maximum number of transactions per time period:

{
    'type': 'velocity_limit',
    'max_transactions': 20,
    'period': 'hourly',
    'description': 'Prevent rapid-fire payments'
}

8. Balance Requirements

Minimum balance thresholds:

{
  type: 'balance_requirement',
  minimum_balance: {
    amount: 100.00,
    currency: 'USDC'
  },
  description: 'Always maintain $100 minimum'
}

Complete Policy Example

const comprehensivePolicy = await mppfi.policies.create({
  agentId: 'agt_7xK9mN2pQ1',
  name: 'Enterprise AI Agent Policy',
  description: 'Production policy for autonomous trading agent',
  rules: [
    // Amount limits
    {
      type: 'amount_limit',
      period: 'daily',
      limit: { amount: 1000.00, currency: 'USDC' }
    },
    {
      type: 'amount_limit',
      period: 'monthly',
      limit: { amount: 20000.00, currency: 'USDC' }
    },
    // Per-transaction limit
    {
      type: 'per_transaction_limit',
      limit: { amount: 250.00, currency: 'USDC' }
    },
    // Merchant allowlist
    {
      type: 'merchant_allowlist',
      addresses: [
        'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
        '8qN5L3kZ9xM2vY7cB4jT6wE1rP9sU5hG3fD8aQ2nK7m',
        'F3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3k'
      ]
    },
    // Category limits
    {
      type: 'category_limit',
      categories: {
        'ai_services': { amount: 600.00, period: 'daily' },
        'data_apis': { amount: 300.00, period: 'daily' },
        'cloud_compute': { amount: 100.00, period: 'daily' }
      },
      currency: 'USDC'
    },
    // Time restrictions
    {
      type: 'time_restriction',
      allowed_days: [1, 2, 3, 4, 5],
      allowed_hours: { start: 6, end: 22 },
      timezone: 'America/New_York'
    },
    // Multi-sig for large payments
    {
      type: 'multi_signature',
      threshold_amount: 500.00,
      threshold_currency: 'USDC',
      required_signers: 2,
      authorized_pubkeys: [
        '5kN3vQ8mK2jR5wT9zL4cF6hG1dS3aE5yU2nB7xP4mL9w',
        '3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3kZ1'
      ],
      approval_timeout: 3600
    },
    // Velocity control
    {
      type: 'velocity_limit',
      max_transactions: 50,
      period: 'hourly'
    },
    // Minimum balance
    {
      type: 'balance_requirement',
      minimum_balance: { amount: 200.00, currency: 'USDC' }
    }
  ],
  enforcement: 'on_chain',
  metadata: {
    environment: 'production',
    team: 'ai-trading',
    cost_center: 'research-001',
    owner: '[email protected]'
  }
});

Policy Management

Update Policy

from mppfi import Client

client = Client(api_key='sk_live_...')

# Update policy rules
updated_policy = client.policies.update(
    policy_id='pol_4zT8mN9pQ3',
    rules=[
        # New rule
        {
            'type': 'amount_limit',
            'period': 'weekly',
            'limit': {'amount': 3000.00, 'currency': 'USDC'}
        },
        # Keep existing rules
        *existing_policy.rules
    ]
)

print(f"Updated policy: {updated_policy.id}")
print(f"New contract TX: {updated_policy.blockchain.tx_signature}")

Note: Updating a policy deploys a new smart contract on Solana. The old contract is deprecated but remains on-chain for audit purposes.

Disable Policy Temporarily

await mppfi.policies.disable('pol_4zT8mN9pQ3', {
  reason: 'Emergency maintenance window',
  duration_hours: 2,
  requires_mfa: true
});

// Re-enable automatically after 2 hours, or manually:
await mppfi.policies.enable('pol_4zT8mN9pQ3');

Archive Policy

// Archive old policy (keeps on-chain record)
client.policies().archive("pol_4zT8mN9pQ3").await?;

// Policy remains visible in history but can't be used

Policy Enforcement

On-Chain Validation

All policies are enforced by Solana smart contracts before payment execution:

// Attempt payment
try {
  const payment = await mppfi.payments.create({
    agentId: 'agt_7xK9mN2pQ1',
    amount: 600.00, // Exceeds daily limit of $500
    currency: 'USDC',
    destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P'
  });
} catch (error) {
  console.error('Policy violation:', error);
  // PolicyViolationError: Daily limit of 500.00 USDC exceeded
  // Current: 450.00 USDC spent today
  // Requested: 600.00 USDC
  // Available: 50.00 USDC
  // Policy: pol_4zT8mN9pQ3
  // Rule: amount_limit (daily)
}

Pre-Flight Validation

Check if payment will pass policy validation:

validation = client.payments.validate_policy(
    agent_id='agt_7xK9mN2pQ1',
    amount=300.00,
    currency='USDC',
    destination='GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
    category='ai_services'
)

if validation.approved:
    # Proceed with payment
    payment = client.payments.create({...})
else:
    print(f"Blocked: {validation.reason}")
    print(f"Violated rules: {validation.violated_rules}")
    for rule in validation.violated_rules:
        print(f"  - {rule.type}: {rule.message}")
        print(f"    Limit: {rule.limit}, Current: {rule.current}")

Response:

{
  "approved": false,
  "reason": "Daily spending limit exceeded",
  "violated_rules": [
    {
      "type": "amount_limit",
      "period": "daily",
      "limit": 500.00,
      "current": 450.00,
      "requested": 300.00,
      "would_exceed": true,
      "available": 50.00
    }
  ],
  "warnings": [],
  "policy_id": "pol_4zT8mN9pQ3"
}

Multi-Signature Approvals

Request Approval for High-Value Payment

// Payment requires multi-sig approval
const payment = await mppfi.payments.create({
  agentId: 'agt_7xK9mN2pQ1',
  amount: 1200.00, // Above $500 threshold
  currency: 'USDC',
  destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P'
});

console.log(`Payment status: ${payment.status}`); // 'pending_approval'
console.log(`Approval ID: ${payment.approval_request.id}`);
console.log(`Required signatures: ${payment.approval_request.required_signers}`);
console.log(`Expires at: ${payment.approval_request.expires_at}`);

// Notify approvers
payment.approval_request.approvers.forEach(approver => {
  sendNotification(approver.pubkey, {
    message: `Approval required for $${payment.amount} payment`,
    approval_url: `https://app.mppfi.xyz/approvals/${payment.approval_request.id}`
  });
});

Sign Approval

from solana.keypair import Keypair
from mppfi import Client

client = Client(api_key='sk_live_...')

# Load approver keypair
approver_keypair = Keypair.from_secret_key(bytes.fromhex(APPROVER_PRIVATE_KEY))

# Sign approval
approval = client.approvals.sign(
    approval_id='apr_5xL9mN3pQ7',
    signer_pubkey=str(approver_keypair.public_key),
    signature=approver_keypair.sign_message(approval_message)
)

print(f"Signatures: {approval.signature_count}/{approval.required_signers}")

if approval.status == 'approved':
    print(f"Payment executing: {approval.payment_id}")
    print(f"TX signature: {approval.payment.blockchain.signature}")

Approval Status

let approval = client.approvals().get("apr_5xL9mN3pQ7").await?;

println!("Status: {}", approval.status); // pending | approved | rejected | expired
println!("Signatures: {}/{}", approval.signature_count, approval.required_signers);

for signer in &approval.signers {
    println!("- {}: {}", signer.pubkey, signer.signed_at);
}

Policy Analytics

Spending Summary

const summary = await mppfi.policies.getSpendingSummary('pol_4zT8mN9pQ3', {
  period: 'monthly',
  year: 2025,
  month: 1
});

console.log('Monthly Spending Summary:');
console.log(`Total spent: ${summary.total_spent} ${summary.currency}`);
console.log(`Limit: ${summary.limit} ${summary.currency}`);
console.log(`Utilization: ${(summary.utilization * 100).toFixed(1)}%`);
console.log(`Transactions: ${summary.transaction_count}`);
console.log(`Average per transaction: ${summary.average_transaction}`);

console.log('\nTop merchants:');
summary.top_merchants.forEach((merchant, index) => {
  console.log(`${index + 1}. ${merchant.name}: ${merchant.amount} ${merchant.currency}`);
});

console.log(`\nViolations: ${summary.violation_count}`);
console.log(`Approvals required: ${summary.approval_count}`);

Violation History

violations = client.policies.get_violations(
    policy_id='pol_4zT8mN9pQ3',
    start_date='2025-01-01',
    end_date='2025-01-31'
)

for violation in violations:
    print(f"{violation.timestamp}:")
    print(f"  Rule: {violation.rule_type}")
    print(f"  Message: {violation.message}")
    print(f"  Attempted amount: {violation.attempted_amount}")
    print(f"  Limit: {violation.limit}")
    print(f"  TX hash: {violation.attempted_tx_hash}")
    print()

Policy Compliance Report

const report = await mppfi.policies.getComplianceReport('pol_4zT8mN9pQ3', {
  period: 'quarterly',
  year: 2025,
  quarter: 1
});

console.log('Quarterly Compliance Report:');
console.log(`Compliance rate: ${report.compliance_rate}%`);
console.log(`Total transactions: ${report.total_transactions}`);
console.log(`Approved: ${report.approved_count}`);
console.log(`Blocked: ${report.blocked_count}`);
console.log(`Required approval: ${report.approval_required_count}`);

// Download PDF report
const pdf = await mppfi.policies.downloadComplianceReport(report.id);

Best Practices

1. Start Restrictive, Loosen Gradually

Begin with conservative limits and adjust based on actual usage:

// Week 1: Conservative
{
  type: 'amount_limit',
  period: 'daily',
  limit: { amount: 100.00, currency: 'USDC' }
}

// After monitoring for 2 weeks, adjust:
{
  type: 'amount_limit',
  period: 'daily',
  limit: { amount: 500.00, currency: 'USDC' } // Based on p95 usage
}

2. Layer Multiple Controls

Use defense-in-depth with complementary rules:

rules = [
    # Per-transaction limit
    {'type': 'per_transaction_limit', 'limit': 250.00},
    # Daily aggregate limit
    {'type': 'amount_limit', 'period': 'daily', 'limit': 1000.00},
    # Monthly cap
    {'type': 'amount_limit', 'period': 'monthly', 'limit': 20000.00},
    # Merchant allowlist
    {'type': 'merchant_allowlist', 'addresses': [...]},
    # Multi-sig for large amounts
    {'type': 'multi_signature', 'threshold_amount': 500.00, ...}
]

3. Use Metadata for Governance

Tag policies for tracking and audits:

metadata: {
  environment: 'production',
  department: 'ai-research',
  cost_center: 'ml-training-003',
  owner: '[email protected]',
  created_by: '[email protected]',
  approved_by: '[email protected]',
  last_reviewed: '2025-01-15',
  next_review: '2025-04-15',
  compliance_tier: 'tier-1'
}

4. Monitor Policy Effectiveness

Set up alerts for policy events:

await mppfi.webhooks.create({
  url: 'https://api.yourcompany.com/webhooks/policy-events',
  events: [
    'policy.violation',
    'policy.approval_required',
    'policy.limit_approaching',
    'policy.updated'
  ]
});

5. Regular Policy Reviews

Schedule quarterly policy reviews:

# Set policy review reminder
reminder = client.policies.set_review_reminder(
    policy_id='pol_4zT8mN9pQ3',
    frequency='quarterly',
    notify=['[email protected]', '[email protected]']
)

Emergency Procedures

Policy Override

Temporarily bypass policies for emergencies (requires elevated privileges):

// Requires MFA and admin role
const override = await mppfi.policies.createOverride({
  policyId: 'pol_4zT8mN9pQ3',
  reason: 'Emergency infrastructure scaling - production outage',
  duration_hours: 2,
  max_amount: 5000.00,
  authorized_by: '[email protected]',
  mfa_token: '123456',
  approval_chain: [
    { role: 'cto', approved_at: '2025-01-15T10:30:00Z' },
    { role: 'cfo', approved_at: '2025-01-15T10:32:00Z' }
  ]
});

console.log(`Override active until: ${override.expires_at}`);
console.log(`Max additional spend: ${override.max_amount}`);

// Override expires automatically and is logged immutably on-chain

Policy Freeze

Lock policy to prevent modifications during audits:

freeze = client.policies.freeze(
    policy_id='pol_4zT8mN9pQ3',
    reason='Q1 2025 financial audit in progress',
    freeze_until='2025-02-15T00:00:00Z',
    frozen_by='[email protected]'
)

# All modification attempts will fail until freeze expires

Rate Limits

Policy endpoints have the following rate limits:

Endpoint

Limit

Window

Create policy

10 requests

1 minute

Update policy

20 requests

1 minute

Validate policy

1000 requests

1 minute

Get policy

500 requests

1 minute

Next Steps

Execute Payments under policy controls
Configure Webhooks for policy events
Review Authorization Engine architecture
Explore API Reference for policy endpoints

PreviousMPP Payments NextWebhooks

Last updated 3 hours ago

Was this helpful?

Good afternoon

hashtagOverview

hashtagCreating Policies

hashtagBasic Policy

hashtagPolicy Rules

hashtag1. Amount Limits

hashtag2. Merchant Allowlists

hashtag3. Transaction Amount Limits

hashtag4. Category Restrictions

hashtag5. Time-Based Controls

hashtag6. Multi-Signature Requirements

hashtag7. Velocity Limits

hashtag8. Balance Requirements

hashtagComplete Policy Example

hashtagPolicy Management

hashtagUpdate Policy

hashtagDisable Policy Temporarily

hashtagArchive Policy

hashtagPolicy Enforcement

hashtagOn-Chain Validation

hashtagPre-Flight Validation

hashtagMulti-Signature Approvals

hashtagRequest Approval for High-Value Payment

hashtagSign Approval

hashtagApproval Status

hashtagPolicy Analytics

hashtagSpending Summary

hashtagViolation History

hashtagPolicy Compliance Report

hashtagBest Practices

hashtag1. Start Restrictive, Loosen Gradually

hashtag2. Layer Multiple Controls

hashtag3. Use Metadata for Governance

hashtag4. Monitor Policy Effectiveness

hashtag5. Regular Policy Reviews

hashtagEmergency Procedures

hashtagPolicy Override

hashtagPolicy Freeze

hashtagRate Limits

hashtagNext Steps

Overview

Creating Policies

Basic Policy

Policy Rules

1. Amount Limits

2. Merchant Allowlists

3. Transaction Amount Limits

4. Category Restrictions

5. Time-Based Controls

6. Multi-Signature Requirements

7. Velocity Limits

8. Balance Requirements

Complete Policy Example

Policy Management

Update Policy

Disable Policy Temporarily

Archive Policy

Policy Enforcement

On-Chain Validation

Pre-Flight Validation

Multi-Signature Approvals

Request Approval for High-Value Payment

Sign Approval

Approval Status

Policy Analytics

Spending Summary

Violation History

Policy Compliance Report

Best Practices

1. Start Restrictive, Loosen Gradually

2. Layer Multiple Controls

3. Use Metadata for Governance

4. Monitor Policy Effectiveness

5. Regular Policy Reviews

Emergency Procedures

Policy Override

Policy Freeze

Rate Limits

Next Steps