Policy Configuration

Fine-tune spending controls and security rules for your agents

Overview

The policy engine evaluates every transaction before it reaches the MPC signing layer. Policies are per-agent and can be updated at any time via the SDK or REST API.

Policy Types

Spending Limits

Control how much an agent can spend:

await aw.policies.update("agent_abc123", {
  maxTransactionAmount: "500",   // Max per single transaction
  dailyLimit: "5000",            // Rolling 24-hour total
  monthlyLimit: "50000",         // Rolling 30-day total
});

Rule	Description	Resets
`maxTransactionAmount`	Maximum amount for a single payment	Per transaction
`dailyLimit`	Maximum total over rolling 24 hours	Rolling window
`monthlyLimit`	Maximum total over rolling 30 days	Rolling window

Address Controls

Restrict which addresses an agent can send to:

await aw.policies.update("agent_abc123", {
  // Whitelist mode: only send to these addresses
  allowedAddresses: [
    "0xTrustedVendor1",
    "0xTrustedVendor2",
    "0xTrustedExchange",
  ],
 
  // Blacklist mode: block specific addresses
  blockedAddresses: [
    "0xKnownScam",
  ],
});

If allowedAddresses is set, only those addresses are permitted. If both are set, allowedAddresses takes priority.

Token Controls

Restrict which tokens an agent can transact with:

await aw.policies.update("agent_abc123", {
  allowedTokens: ["USDC", "USDT"],  // Only stablecoins
});

Velocity Controls

Limit transaction frequency to prevent runaway agents:

await aw.policies.update("agent_abc123", {
  velocityLimit: {
    maxCount: 100,        // Max number of transactions
    windowSeconds: 3600,  // Per hour
  },
});

Time-Based Controls

Restrict when transactions can occur:

await aw.policies.update("agent_abc123", {
  schedule: {
    timezone: "America/New_York",
    allowedHours: { start: 9, end: 17 },  // 9 AM - 5 PM
    allowedDays: [1, 2, 3, 4, 5],         // Monday - Friday
  },
});

Human Approval

Route high-value transactions to human review:

await aw.policies.update("agent_abc123", {
  requireHumanApproval: true,
  humanApprovalThreshold: "1000",  // Transactions above $1000
  approvalTimeout: 3600,            // 1 hour to approve before auto-reject
  approvers: [
    "user_admin1@company.com",
    "user_admin2@company.com",
  ],
});

Policy Evaluation Order

Policies are checked in this order. The first failure stops the transaction:

Agent Status — Is the agent active (not frozen)?
Token Check — Is this token allowed?
Address Check — Is this recipient allowed?
Amount Check — Does this exceed per-transaction limit?
Daily Limit — Would this exceed the rolling daily total?
Monthly Limit — Would this exceed the rolling monthly total?
Velocity Check — Has the agent exceeded its transaction rate?
Schedule Check — Is this within allowed hours?
Human Approval — Does this require human review?
Infrastructure Safety Net — Paratro-enforced hard limits

Policy Violation Events

When a policy blocks a transaction, you receive a detailed error:

{
  "code": "policy_violation",
  "type": "invalid_request_error",
  "message": "Transaction would exceed daily limit"
}

You can also receive these as webhook events:

await aw.webhooks.create({
  url: "https://your-app.com/webhooks",
  events: ["policy.violated"],
});

Policy Templates

Use templates for common configurations:

// Conservative: tight limits for testing
await aw.policies.applyTemplate("agent_abc123", "conservative");
 
// Standard: balanced limits for production
await aw.policies.applyTemplate("agent_abc123", "standard");
 
// Custom: define and reuse your own templates
await aw.policies.createTemplate("my-template", {
  maxTransactionAmount: "200",
  dailyLimit: "2000",
  allowedTokens: ["USDC"],
  velocityLimit: { maxCount: 50, windowSeconds: 3600 },
});
 
await aw.policies.applyTemplate("agent_abc123", "my-template");

Best Practices

Start restrictive, expand gradually — Begin with tight limits and increase as you gain confidence
Use allowedAddresses — Whitelist trusted addresses rather than relying solely on amount limits
Enable human approval for high-value — Set a threshold above which humans review transactions
Monitor policy violations — Track violations via webhooks to identify misconfigured agents
Use velocity limits — Prevent runaway loops where an agent repeatedly attempts transactions
Review policies weekly — As agent behaviors evolve, update policies to match