Reference

SPEND.md File Format

Complete reference for configuring your AI agent's economic capabilities. SPEND.md uses YAML frontmatter with Markdown headers for organization.

File Structure

A SPEND.md file is organized into sections using Markdown headers. Each section contains YAML configuration. Here's the complete structure:

# SPEND.md

## Identity
agent_name: string (required)
owner: string (required)
description: string
version: string

## Spending
spend:
  monthly_limit: amount
  daily_limit: amount
  per_transaction: amount
  currency: string
  allowed_categories: [list]
  blocked_categories: [list]
  allowlist: [list]
  blocklist: [list]
  require_https: boolean
  geographic_restrictions: [list]

## Earning
earn:
  enabled: boolean
  stripe_connect: string
  api_pricing:
    per_request: amount
    per_token: amount
  subscriptions:
    - tier: string
      price: amount
      interval: string
  tips: boolean
  withdraw_threshold: amount

## Approval
approval:
  auto_approve_under: amount
  require_confirmation_over: amount
  notify_on_all: boolean
  approval_channels: [list]
  timeout_action: string

## Notifications
notifications:
  email: string
  webhook: string
  slack: string
  events: [list]

## Security
security:
  ip_allowlist: [list]
  require_signed_requests: boolean
  api_key_rotation_days: number
  audit_retention_days: number

## Metadata
metadata:
  tags: [list]
  environment: string
  custom: object

Identity

Identifies your agent and its owner. This section is required.

## Identity
agent_name: my-assistant
owner: team@company.com
description: Customer support AI agent
version: 1.0.0

Field	Type	Required	Description
agent_name	string	Yes	Unique identifier for your agent
owner	string	Yes	Email address of the responsible party
description	string	No	Human-readable description of the agent
version	string	No	Semantic version of this configuration

Spending

Controls how and where your agent can spend money. All limits are enforced in real-time.

## Spending
spend:
  monthly_limit: 500 USD
  daily_limit: 50 USD
  per_transaction: 25 USD
  currency: USD
  
  allowed_categories:
    - software_services
    - cloud_hosting
    - api_services
    - development_tools
  
  blocked_categories:
    - gambling
    - adult_content
  
  allowlist:
    - openai.com
    - anthropic.com
    - github.com
    - aws.amazon.com
  
  blocklist:
    - suspicious-site.com
  
  require_https: true
  
  geographic_restrictions:
    - US
    - EU
    - CA

Spending Limits

Field	Format	Description
monthly_limit	`amount currency`	Maximum spend per calendar month
daily_limit	`amount currency`	Maximum spend per day (UTC)
per_transaction	`amount currency`	Maximum single transaction amount
currency	`ISO 4217`	Default currency (USD, EUR, GBP, etc.)

Merchant Categories

Control which merchant categories are allowed or blocked. Uses standard MCC groups:

Common Allowed Categories

software_services
cloud_hosting
api_services
development_tools
data_services
professional_services

Always Blocked by Default

gambling
adult_content
cryptocurrency
money_transfer
securities

Merchant Allowlist/Blocklist

Specify individual merchants by domain. The allowlist takes precedence if both are defined.

Tip: Start with a strict allowlist and expand as needed. It's easier to add merchants than to recover from unauthorized spending.

Earning

Enable your agent to earn money through API calls, subscriptions, or tips. Requires Stripe Connect integration.

## Earning
earn:
  enabled: true
  stripe_connect: acct_1234567890
  
  api_pricing:
    per_request: 0.01 USD
    per_token: 0.0001 USD
  
  subscriptions:
    - tier: basic
      price: 9.99 USD
      interval: monthly
    - tier: pro
      price: 29.99 USD
      interval: monthly
  
  tips: true
  withdraw_threshold: 100 USD

Field	Type	Description
enabled	boolean	Enable/disable earning capabilities
stripe_connect	string	Stripe Connect account ID
api_pricing	object	Pricing for API calls (per_request and/or per_token)
subscriptions	array	Subscription tiers with prices
tips	boolean	Allow users to tip the agent
withdraw_threshold	amount	Minimum balance before auto-withdraw

Approval

Define when transactions require human approval. Creates a balance between autonomy and oversight.

## Approval
approval:
  auto_approve_under: 10 USD
  require_confirmation_over: 50 USD
  notify_on_all: true
  
  approval_channels:
    - email
    - slack
  
  timeout_action: deny
  timeout_minutes: 30

Field	Description
auto_approve_under	Transactions below this amount are auto-approved
require_confirmation_over	Transactions above this require explicit approval
notify_on_all	Send notifications for all transactions
approval_channels	Where to send approval requests (email, slack, webhook)
timeout_action	Action on timeout: `deny` or `approve`
timeout_minutes	Minutes to wait before timeout_action

Notifications

Configure where and when to receive notifications about agent activity.

## Notifications
notifications:
  email: team@company.com
  webhook: https://api.company.com/spend-webhook
  slack: https://hooks.slack.com/services/T00/B00/XXX
  
  events:
    - transaction.completed
    - transaction.declined
    - transaction.pending_approval
    - limit.approaching
    - limit.exceeded
    - card.created
    - card.frozen

Available Events

Transaction Events

transaction.completed
transaction.declined
transaction.pending_approval
transaction.refunded

Limit Events

limit.approaching (80% reached)
limit.exceeded
limit.reset

Security

Additional security controls for your agent's wallet.

## Security
security:
  ip_allowlist:
    - 192.168.1.0/24
    - 10.0.0.0/8
  
  require_signed_requests: true
  api_key_rotation_days: 90
  audit_retention_days: 365

See the Security Guide for comprehensive security best practices.

Metadata

Optional metadata for organizing and filtering agents.

## Metadata
metadata:
  tags:
    - production
    - customer-support
    - tier-1
  
  environment: production
  
  custom:
    team: support-team
    cost_center: CC-12345
    jira_project: SUP

Complete Example

Here's a production-ready SPEND.md with all sections configured:

# SPEND.md

## Identity
agent_name: support-agent-prod
owner: team@company.com
description: Production customer support AI agent
version: 2.1.0

## Spending
spend:
  monthly_limit: 1000 USD
  daily_limit: 100 USD
  per_transaction: 50 USD
  currency: USD
  
  allowed_categories:
    - software_services
    - cloud_hosting
    - api_services
  
  allowlist:
    - openai.com
    - anthropic.com
    - github.com
    - twilio.com
  
  require_https: true
  geographic_restrictions:
    - US
    - EU

## Earning
earn:
  enabled: true
  stripe_connect: acct_prod_123
  api_pricing:
    per_request: 0.005 USD
  tips: true
  withdraw_threshold: 500 USD

## Approval
approval:
  auto_approve_under: 25 USD
  require_confirmation_over: 100 USD
  notify_on_all: true
  approval_channels:
    - slack
  timeout_action: deny
  timeout_minutes: 15

## Notifications
notifications:
  slack: https://hooks.slack.com/services/T00/B00/XXX
  webhook: https://api.company.com/webhooks/spend
  events:
    - transaction.completed
    - transaction.declined
    - limit.approaching

## Security
security:
  ip_allowlist:
    - 10.0.0.0/8
  require_signed_requests: true
  api_key_rotation_days: 30
  audit_retention_days: 365

## Metadata
metadata:
  tags:
    - production
    - customer-support
  environment: production
  custom:
    team: support
    cost_center: CC-100