Guide

Security

Understanding the SPEND.md security model and best practices for keeping your AI agent's wallet secure.

Security Model

SPEND.md implements a defense-in-depth security model with multiple layers of protection. Even if one layer is compromised, others remain to prevent unauthorized transactions.

Spending Controls

Hard limits on amounts, merchants, and categories. Enforced at the payment processor level—can't be bypassed.

Approval Workflows

Human-in-the-loop for high-value transactions. Configurable thresholds with timeout defaults.

Real-time Monitoring

Instant notifications for all transactions. Anomaly detection for unusual patterns.

Complete Audit Trail

Every transaction logged with full context. Immutable audit logs for compliance.

Best Practices

Principle of Least Privilege

Give your agent only the access it needs. Start restrictive and expand as necessary.

## Spending - Start Restrictive
spend:
  # Low initial limits
  monthly_limit: 50 USD
  daily_limit: 10 USD
  per_transaction: 5 USD
  
  # Strict allowlist - only known merchants
  allowlist:
    - openai.com
    - anthropic.com
  
  # No categories allowed except through allowlist
  allowed_categories: []
  
  # HTTPS required
  require_https: true

Tip: It's easier to increase limits after observing normal usage patterns than to recover from unauthorized spending.

Use Approval Workflows

Require human approval for transactions above a threshold. Set appropriate timeouts.

## Approval - Human in the Loop
approval:
  # Auto-approve only small transactions
  auto_approve_under: 5 USD
  
  # Require explicit approval for larger amounts
  require_confirmation_over: 25 USD
  
  # Always notify
  notify_on_all: true
  
  # Default to deny on timeout (safer)
  timeout_action: deny
  timeout_minutes: 15
  
  # Multiple approval channels for redundancy
  approval_channels:
    - slack
    - email

Secure API Keys

Treat API keys like passwords. Never commit them to version control.

Use environment variables

Store API keys in environment variables, not in code or config files.

Rotate keys regularly

Set up automatic key rotation every 30-90 days using the security.api_key_rotation_days setting.

Use separate keys per environment

Never use production keys (sk_live_) in development or testing.

Monitor key usage

Review API key activity in the dashboard. Revoke unused or suspicious keys immediately.

IP Allowlisting

Restrict API access to known IP addresses, especially for production environments.

## Security
security:
  ip_allowlist:
    # Production servers
    - 203.0.113.0/24
    
    # Office network
    - 198.51.100.0/24
    
    # CI/CD pipeline
    - 192.0.2.50/32

Enable Signed Requests

Require request signatures to prevent tampering and replay attacks.

## Security
security:
  require_signed_requests: true

When enabled, all API requests must include a valid signature in the X-Spend-Signature header. See the API documentation for implementation details.

Common Threats & Mitigations

Compromised Agent

If your AI agent is compromised (prompt injection, jailbreak), an attacker could attempt unauthorized spending.

Mitigations:

  • • Strict spending limits cap potential damage
  • • Merchant allowlists prevent spending at unauthorized sites
  • • Approval workflows require human confirmation for large amounts
  • • Real-time alerts enable fast response

API Key Leak

Accidentally committing API keys to public repositories or exposing them in logs.

Mitigations:

  • • Use environment variables, never hardcode keys
  • • IP allowlisting restricts key usage to known sources
  • • Automatic key rotation limits exposure window
  • • GitHub secret scanning alerts on detected keys

Card Skimming / Fraud

Card details intercepted or used fraudulently at unexpected merchants.

Mitigations:

  • • Virtual cards with unique numbers per use case
  • • Merchant allowlists block unknown merchants
  • • Geographic restrictions prevent international fraud
  • • Instant freeze capability via CLI or API

Incident Response

If you suspect unauthorized activity, take these steps immediately:

1

Freeze All Cards

spend card freeze --all
2

Revoke API Keys

spend api-key revoke --all
3

Review Transaction History

spend transactions --status completed --from 2026-01-01
4

Contact Support

Email security@spend.md with details of the suspected incident. We'll help investigate and recover.

Compliance & Certifications

SPEND.md is designed with compliance in mind:

PCI DSS Level 1

Card data handling

SOC 2 Type II

Security controls

GDPR Compliant

Data protection

256-bit Encryption

Data at rest and in transit

Full Security Configuration

Here's a complete security-focused SPEND.md configuration:

# SPEND.md - Security-Hardened Configuration

## Identity
agent_name: secure-agent
owner: security@company.com

## Spending - Strict Controls
spend:
  monthly_limit: 100 USD
  daily_limit: 25 USD
  per_transaction: 10 USD
  
  # Explicit allowlist only
  allowlist:
    - openai.com
    - anthropic.com
  
  # No category fallback
  allowed_categories: []
  
  # Block high-risk categories
  blocked_categories:
    - gambling
    - cryptocurrency
    - money_transfer
  
  # HTTPS required
  require_https: true
  
  # Geographic restrictions
  geographic_restrictions:
    - US

## Approval - Human in Loop
approval:
  auto_approve_under: 1 USD
  require_confirmation_over: 10 USD
  notify_on_all: true
  approval_channels:
    - slack
    - email
  timeout_action: deny
  timeout_minutes: 10

## Notifications - Full Visibility
notifications:
  email: security@company.com
  slack: https://hooks.slack.com/...
  events:
    - transaction.completed
    - transaction.declined
    - transaction.pending_approval
    - limit.approaching
    - limit.exceeded
    - card.created
    - card.frozen
    - security.alert

## Security - Maximum Protection
security:
  ip_allowlist:
    - 10.0.0.0/8
  require_signed_requests: true
  api_key_rotation_days: 30
  audit_retention_days: 730  # 2 years