Agent Spending Controls

Non-custodial policy layer for AI agent wallets

Give your AI agents the ability to make payments whilst enforcing spending limits—without custodying keys.

---

The Problem

AI agents need to make autonomous payments, but developers face a dilemma:

• Give agents direct wallet access → Risk of runaway spending, no oversight, compliance gaps
• Use custodial solutions → Liability, trust issues, regulatory complications
• Build custom controls → Weeks of engineering, security risks, maintenance burden

We solve this: A non-custodial policy layer that wraps any wallet SDK, enforcing spending limits without ever touching your keys.

---

Live Demo

Real-time monitoring of multiple agents with different spending policies

Detailed audit trail showing ALLOWED and BLOCKED transactions

---

Quick Start

1. Clone and Install

git clone https://github.com/L1AD/agent-spending-controls.git
cd agent-spending-controls
npm install

2. Start the Policy API

npm run api

Runs on http://localhost:3001

3. Start the Dashboard (in a new terminal)

npm run dashboard

Open http://localhost:3002 to see real-time monitoring.

4. Run the Demo (in a new terminal)

npm run demo

⚠️ POC Mode: This demo runs in dry-run mode and does not execute real blockchain transactions. Policy enforcement (Gates 1 & 2) runs completely, but blockchain execution is simulated to avoid needing funded wallets. This demonstrates the policy layer without requiring gas fees.

This demonstrates:

• 🤖 3 agents with different spending limits (conservative, moderate, generous)
• ✅ Transactions being ALLOWED based on policy
• ❌ Transactions being BLOCKED when limits exceeded
• 📊 Real-time counter tracking and dashboard updates
• 🔒 Two-gate enforcement with tamper protection
• 💸 Simulated transaction execution (real blockchain code available but commented out)

---

How It Works

Two-Gate Enforcement Model

Developer Code
│
│ wallet.send(intent)
▼
┌────────────────────────────────────────┐
│   Policy SDK (Your Machine)           │
│                                        │
│   🚪 GATE 1: Validate Intent          │ ◄── Check policy, issue token
│   🚪 GATE 2: Verify Authorisation     │ ◄── Verify token, consume it
│   🔐 WDK: Sign & Broadcast            │ ◄── You keep the keys
└────────────────────────────────────────┘
│
└──► Blockchain

Key Security Features:

• ✅ Intent Fingerprinting - Tamper detection via SHA-256 hashing
• ✅ Single-Use Tokens - JWT tokens with 60-second TTL, consumed on first use
• ✅ Immediate Reservation - Amount reserved at Gate 1, preventing race conditions
• ✅ Non-Custodial - Your keys never leave your infrastructure

Developer Integration

Instead of using a wallet SDK directly:

// ❌ Direct WDK (no policy enforcement)
const wdk = new WDK(seedPhrase);
const account = await wdk.getAccount('ethereum', 0);
await account.sendTransaction({ to: '0x...', value: parseEther('1.0') });

Wrap it with our policy layer:

// ✅ With spending controls
import { PolicyWallet, PolicyError } from 'agent-spending-controls';

const wallet = new PolicyWallet(wdk, {
apiUrl: 'http://localhost:3001',
orgId: 'your-org',
walletId: 'your-wallet',
agentId: 'agent-1'
});

try {
await wallet.send({
chain: 'ethereum',
asset: 'eth',
to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1',
amount: '1000000000000000000' // 1 ETH
});
console.log('✅ Payment approved and executed');
} catch (error) {
if (error instanceof PolicyError) {
console.log(`❌ Blocked: ${error.message}`);
console.log(`   Code: ${error.code}`);
console.log(`   Remaining today: ${error.details.counters.remainingDaily} ETH`);
}
}

---

Features

✅ Currently Implemented (Phase 1 - POC)

Feature	Description
Per-Transaction Limits	Maximum amount per single transaction
Daily Limits	Maximum total spending per 24-hour period (midnight reset)
Hourly Limits	Maximum total spending per hour (UTC hour boundaries)
Recipient Whitelist	Only allow transactions to pre-approved addresses
Transaction Frequency	Maximum X transactions per time period (e.g., 3 per hour)
Multi-Agent Management	Different limits for each agent
Real-Time Monitoring	Live dashboard with auto-refresh
Audit Trail	Append-only log of every policy decision
Tamper Protection	Intent fingerprinting prevents modification
Single-Use Authorisations	Tokens consumed on first verification
Ethereum Support	Native ETH and ERC-20 tokens

🚀 Planned (See POLICY_CONTROLS.md for full list)

• Time-Based Limits - Weekly, monthly caps
• Velocity Controls - Cooldown periods, burst protection
• Recipient Controls - Blacklists, address screening
• Multi-Chain - Bitcoin, Solana, Polygon, Arbitrum, etc.
• Approval Workflows - Two-person rule, supervisor approval for large amounts
• Fraud Detection - Anomaly detection, behavioural analysis
• Compliance - KYC/AML integration, sanctions screening, reporting

Want to contribute? See 100+ potential controls and pick one to implement!

---

Architecture

Project Structure

agent-spending-controls/
├── src/
│   ├── api/                    # Policy enforcement API
│   │   ├── server.ts           # Express server (port 3001)
│   │   ├── policy-engine.ts    # Spending limit evaluation
│   │   ├── validate.ts         # Gate 1: Validate intent
│   │   ├── verify.ts           # Gate 2: Verify authorisation
│   │   ├── auth.ts             # JWT token management
│   │   ├── storage.ts          # In-memory data store
│   │   └── types.ts            # API type definitions
│   │
│   ├── sdk/                    # Client-side SDK
│   │   ├── policy-wallet.ts    # Wrapper around wallet SDKs
│   │   ├── types.ts            # SDK types and PolicyError
│   │   └── index.ts            # Public exports
│   │
│   └── dashboard/              # Real-time monitoring UI
│       ├── server.ts           # Dashboard server (port 3002)
│       └── public/
│           └── index.html      # Auto-refreshing UI
│
├── examples/
│   └── multi-agent-demo.ts     # 3 agents with different limits
│
├── docs/
│   ├── POLICY_CONTROLS.md      # 100+ potential policy controls
│   └── images/                 # Screenshots
│
├── ARCHITECTURE.md             # Detailed technical documentation
└── CONTRIBUTING.md             # How to contribute

Data Flow

┌──────────────────────────────────────────────────────────────┐
│ 1. Agent calls wallet.send(intent)                           │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 2. SDK → POST /validate-intent                               │
│    • Policy engine evaluates spending limits                 │
│    • Immediately reserves amount in daily counter            │
│    • Issues JWT token with intent fingerprint                │
│    • Returns: { decision: 'allow', auth: 'token...', ... }  │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 3. SDK → POST /verify-authorisation                          │
│    • Verifies JWT signature and expiry (60s TTL)             │
│    • Checks token hasn't been used before                    │
│    • Validates intent fingerprint matches (tamper check)     │
│    • Marks token as consumed (single-use)                    │
│    • Returns: { status: 'valid' }                            │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ 4. SDK → WDK.sign() → Broadcast to blockchain                │
│    • Developer's keys sign the transaction                   │
│    • Transaction executed on-chain                           │
│    • Returns: { hash, fee }                                  │
└──────────────────────────────────────────────────────────────┘

---

Why Use This?

vs. Direct Wallet SDK

Feature	Direct Wallet SDK	With Spending Controls
Spending Limits	❌ None	✅ Per-agent limits
Audit Trail	❌ No logging	✅ Full audit log
Monitoring	❌ No visibility	✅ Real-time dashboard
Multi-Agent	❌ Complex DIY	✅ Built-in management
Compliance	❌ DIY	✅ Regulatory-ready
Tamper Protection	❌ None	✅ Fingerprinting + single-use tokens
Key Security	✅ You control	✅ You control

vs. Custodial Solutions

Feature	Custodial Wallet Service	Agent Spending Controls
Key Custody	❌ Third-party holds keys	✅ You keep keys
Liability	❌ High (custodian risk)	✅ Low (non-custodial)
Trust Required	❌ Must trust custodian	✅ Minimal trust needed
Policy Enforcement	✅ Yes	✅ Yes
Vendor Lock-in	❌ High	✅ Wraps any wallet SDK
Compliance	⚠️ Custodian’s responsibility	✅ Your control

---

Use Cases

1. AI Shopping Agents

Agent can purchase items up to $100/day, preventing runaway spending on expensive items.

2. Automated Treasury Management

DeFi agent can rebalance positions with per-transaction limits and daily caps.

3. Customer Service Bots

Support agent can issue refunds up to $50 without human approval, larger amounts require oversight.

4. Research & Development

Grant access to multiple research agents, each with different budgets for experiments.

5. Multi-Agent Marketplaces

Platform with hundreds of agents, each with custom spending policies.

---

Roadmap

Phase 1: Proof of Concept ✅ (Current)

• Basic spending limits (daily, per-transaction)
• Hourly spending limits
• Recipient whitelist controls
• Transaction frequency limits
• Two-gate enforcement model
• Real-time monitoring dashboard
• Audit logging
• Ethereum support (ETH + ERC-20)
• Multi-agent management

Phase 2: Production-Ready SDK (2-4 weeks)

• npm package distribution
• Persistent storage (PostgreSQL)
• Redis for token management
• Comprehensive test suite
• SDK for multiple wallet providers
• Docker deployment
• Production security hardening

Phase 3: Advanced Controls (1-2 months)

• Weekly/monthly limits
• Recipient blacklists
• Advanced velocity controls & rate limiting
• Multi-chain support (Bitcoin, Solana)
• Approval workflows
• Webhooks & notifications

Phase 4: Enterprise Features (3+ months)

• Fraud detection & anomaly detection
• Compliance reporting (KYC/AML)
• Multi-organisation support
• Role-based access control
• API rate limiting
• SaaS offering

Want to help? Check CONTRIBUTING.md and POLICY_CONTROLS.md!

---

Documentation

• ARCHITECTURE.md - Detailed technical documentation
• POLICY_CONTROLS.md - 100+ potential policy controls
• CONTRIBUTING.md - How to contribute
• Tether WDK Docs - Wallet SDK documentation

---

Security

Best Practises

⚠️ NEVER commit sensitive data:

• Seed phrases
• Private keys
• API keys
• Production credentials

All sensitive configuration belongs in .env (gitignored).

Current Limitations (POC)

This is a proof of concept. Before production use:

• Replace in-memory storage with PostgreSQL
• Add Redis for distributed token management
• Implement rate limiting on API endpoints
• Add comprehensive input validation
• Security audit of JWT implementation
• Add monitoring & alerting
• Implement backup & recovery procedures

---

FAQ

Q: Do you custody my keys? A: No. Your keys remain on your infrastructure. We only enforce policy before you sign.

Q: Does this work with any wallet SDK? A: Currently demonstrated with Tether WDK. The SDK wrapper pattern works with any wallet library.

Q: What happens if your API goes down? A: Agents can’t make payments (fail-closed design). In production, deploy your own policy API with high availability.

Q: Can I use this in production? A: This is a POC. See “Current Limitations” above. We’re working towards production-ready releases.

Q: Does the demo execute real blockchain transactions? A: No. The demo runs in dry-run mode and simulates blockchain execution. Policy enforcement (the core innovation) runs completely. To enable real transactions, uncomment the production code in src/sdk/policy-wallet.ts and fund your wallet with ETH for gas.

Q: How do I add my own policy controls? A: Check CONTRIBUTING.md and POLICY_CONTROLS.md for guidance.

Q: Is there a hosted version? A: Not yet. Phase 1 is self-hosted. Hosted SaaS coming in Phase 4.

---

Contributing

We welcome contributions! This project is young and there’s lots to build.

High-value contributions:

• Implement policy controls from POLICY_CONTROLS.md
• Add support for more wallet SDKs
• Write tests (unit, integration, security)
• Improve documentation & examples
• Add multi-chain support

See CONTRIBUTING.md for detailed guidelines.

---

License

MIT License - see LICENSE for details.

---

Acknowledgements

• Tether WDK - Multi-chain wallet SDK
• Agentic Commerce - Inspiration for agent-driven economy

---

Connect

• GitHub Issues: Report bugs or request features
• Twitter: @L1AD
• Email:

---