Skip to main content

​
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
});
RuleDescriptionWindow
maxTransactionAmountMaximum amount for a single paymentPer transaction
dailyLimitMaximum total over rolling 24 hoursRolling window
monthlyLimitMaximum total over rolling 30 daysRolling 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:
1

Agent Status

Is the agent active (not frozen)?
2

Token Check

Is this token in the allowedTokens list?
3

Address Check

Is the recipient in allowedAddresses and not in blockedAddresses?
4

Amount Check

Does this exceed maxTransactionAmount?
5

Daily Limit

Would this exceed the rolling daily total?
6

Monthly Limit

Would this exceed the rolling monthly total?
7

Velocity Check

Has the agent exceeded its transaction rate (velocityLimit)?
8

Schedule Check

Is this within allowed hours and days?
9

Human Approval

Does this require human review based on the threshold?
10

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.