Policy Engine

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. The first policy violation stops the transaction immediately.

Policy Types

Spending Limits

Control how much an agent can spend:

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

Rule	Description	Window
`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 allowedAddresses and blockedAddresses 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",
  ],
});

Human approval is available on Growth and Enterprise plans. When a transaction requires approval, a webhook event is sent and the transaction enters a pending_approval state.

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 in the allowedTokens list?

Address Check

Is the recipient in allowedAddresses and not in blockedAddresses?

Amount Check

Does this exceed maxTransactionAmount?

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 (velocityLimit)?

Schedule Check

Is this within allowed hours and days?

Human Approval

Does this require human review based on the threshold?

Infrastructure Safety Net

Paratro-enforced hard limits (cannot be overridden).

Policy Violation Events

When a policy blocks a transaction, the API returns a detailed error:

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

You can also receive violations 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 in your agent’s behavior.

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.

Getting Started

Platform

Core Features

Guides

Overview

Policy Types

Spending Limits

Address Controls

Token Controls

Velocity Controls

Time-Based Controls

Human Approval

Policy Evaluation Order

Policy Violation Events

Policy Templates

Best Practices

​Overview

​Policy Types

​Spending Limits

​Address Controls

​Token Controls

​Velocity Controls

​Time-Based Controls

​Human Approval

​Policy Evaluation Order

​Policy Violation Events

​Policy Templates

​Best Practices

Overview

Policy Types

Spending Limits

Address Controls

Token Controls

Velocity Controls

Time-Based Controls

Human Approval

Policy Evaluation Order

Policy Violation Events

Policy Templates

Best Practices