Approval Policies

Configure rules that govern autonomous transaction execution. Policies define which transactions agents can execute automatically and which require human approval.

Overview

Approval policies provide declarative control over agent transaction permissions. Define policies using YAML configuration files that specify conditions and actions for different transaction types.

Policy structure

policies:
  - name: policy_name
    conditions:
      # Transaction criteria
    action: auto_approve | require_human_approval | reject
    notification:
      channels: [email, slack, webhook]
      timeout: 3600

Basic example

Auto-approve small transfers, require approval for large amounts:

policies:
  - name: auto_approve_small_transfers
    conditions:
      transaction_type: transfer
      max_value_usd: 100
      daily_limit_usd: 500
    action: auto_approve

  - name: approve_large_transfers
    conditions:
      transaction_type: transfer
      min_value_usd: 100
    action: require_human_approval
    notification:
      channels: [email, slack]
      timeout: 3600

Condition types

Transaction type

Filter by operation type:

conditions:
  transaction_type: transfer | contract_call | token_approval | swap

Value limits

Set minimum and maximum transaction values:

conditions:
  max_value_usd: 100      # Maximum single transaction value
  min_value_usd: 50       # Minimum value for this policy
  daily_limit_usd: 1000   # Maximum daily total across all transactions

Asset filters

Restrict policies to specific tokens:

conditions:
  allowed_assets: [USDC, WETH, DAI]
  blocked_assets: [SHIB, DOGE]

Contract verification

Require verified contracts:

conditions:
  contract_verified: true
  min_contract_age_days: 90

Recipient constraints

Whitelist or blacklist addresses:

conditions:
  recipient_whitelist:
    - 0x1234567890abcdef1234567890abcdef12345678
    - 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd
  recipient_blacklist:
    - 0x0000000000000000000000000000000000000000

Time restrictions

Limit transaction execution to specific time windows:

conditions:
  allowed_hours: [9, 10, 11, 12, 13, 14, 15, 16, 17]  # Business hours
  allowed_days: [1, 2, 3, 4, 5]  # Monday-Friday
  timezone: "America/New_York"

Gas price limits

Prevent execution during high gas prices:

conditions:
  max_gas_price_gwei: 50
  max_priority_fee_gwei: 2

Actions

Auto approve

Execute transaction immediately without human intervention:

action: auto_approve

Require human approval

Pause execution and send notification for manual review:

action: require_human_approval
notification:
  channels: [email, slack, webhook]
  timeout: 3600  # Auto-reject after 1 hour
  escalation:
    after: 1800  # Escalate after 30 minutes
    to: [[email protected]]

Reject

Block transaction execution:

action: reject
notification:
  channels: [slack]
  message: "Transaction rejected by policy: unknown_contracts"

Notification channels

Email

Send approval requests via email:

notification:
  channels: [email]
  email:
    recipients: [[email protected], [email protected]]
    subject: "Transaction approval required"

Slack

Post to Slack channel with approval buttons:

notification:
  channels: [slack]
  slack:
    webhook_url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
    channel: "#agent-approvals"

Webhook

Send HTTP POST to custom endpoint:

notification:
  channels: [webhook]
  webhook:
    url: https://api.example.com/approvals
    headers:
      Authorization: "Bearer ${WEBHOOK_TOKEN}"
    method: POST

Policy evaluation

Policies are evaluated in order from top to bottom. The first matching policy determines the action.

Example evaluation flow:

policies:
  # Policy 1: Block unverified contracts
  - name: block_unknown_contracts
    conditions:
      transaction_type: contract_call
      contract_verified: false
    action: reject

  # Policy 2: Auto-approve small contract calls
  - name: auto_approve_small_calls
    conditions:
      transaction_type: contract_call
      max_value_usd: 50
    action: auto_approve

  # Policy 3: Require approval for large contract calls
  - name: approve_large_calls
    conditions:
      transaction_type: contract_call
    action: require_human_approval

Evaluation:

1. Contract call to unverified contract → Rejected (matches policy 1)

2. Contract call worth $25 to verified contract → Auto-approved (matches policy 2)

3. Contract call worth $200 to verified contract → Requires approval (matches policy 3)

Complex policies

Multi-condition policies

Combine multiple conditions with AND logic:

- name: high_value_business_hours
  conditions:
    transaction_type: transfer
    min_value_usd: 1000
    allowed_hours: [9, 10, 11, 12, 13, 14, 15, 16, 17]
    allowed_days: [1, 2, 3, 4, 5]
  action: require_human_approval

Rate limiting

Limit transaction velocity:

- name: rate_limit_transfers
  conditions:
    transaction_type: transfer
    max_hourly_count: 10
    max_hourly_value_usd: 5000
  action: require_human_approval
  notification:
    channels: [slack]
    message: "Hourly transaction limit reached"

Anomaly detection

Flag unusual patterns:

- name: detect_anomalies
  conditions:
    transaction_type: transfer
    value_deviation_percent: 200  # >200% of historical average
  action: require_human_approval
  notification:
    channels: [email, slack]
    priority: high

Loading policies

From file

import { Molt402Client } from '@molt402/sdk'

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: { type: 'private_key', key: process.env.AGENT_PRIVATE_KEY },
  policies: './policies.yaml'
})

From object

const policies = {
  policies: [
    {
      name: 'auto_approve_small',
      conditions: {
        transaction_type: 'transfer',
        max_value_usd: 100
      },
      action: 'auto_approve'
    }
  ]
}

const client = new Molt402Client({
  network: 'x402-mainnet',
  wallet: { type: 'private_key', key: process.env.AGENT_PRIVATE_KEY },
  policies
})

Dynamic updates

Update policies at runtime:

await client.updatePolicies('./new-policies.yaml')

Handling approval requests

Via SDK

Check pending approvals:

const pending = await client.getPendingApprovals()

for (const approval of pending) {
  console.log(`Transaction: ${approval.txHash}`)
  console.log(`Value: ${approval.valueUsd} USD`)
  console.log(`Policy: ${approval.matchedPolicy}`)

  // Approve or reject
  await client.approveTransaction(approval.id)
  // or
  await client.rejectTransaction(approval.id, 'Reason for rejection')
}

Via webhook

Receive approval requests at your endpoint:

POST /approvals
{
  "approval_id": "apr_1234567890",
  "transaction": {
    "hash": "0xabc...",
    "from": "0x123...",
    "to": "0x456...",
    "value": "100000000000000000",
    "value_usd": 250.50,
    "gas_estimate": "21000",
    "type": "transfer"
  },
  "policy": {
    "name": "approve_large_transfers",
    "action": "require_human_approval"
  },
  "approve_url": "https://api.molt402.dev/approvals/apr_1234567890/approve",
  "reject_url": "https://api.molt402.dev/approvals/apr_1234567890/reject",
  "expires_at": "2026-03-17T18:00:00Z"
}

Respond to approve:

curl -X POST https://api.molt402.dev/approvals/apr_1234567890/approve \
  -H "Authorization: Bearer YOUR_API_KEY"

Testing policies

Validate policy configuration before deployment:

const dryRun = await client.testPolicies({
  transaction: {
    type: 'transfer',
    value: '150',
    asset: 'USDC',
    recipient: '0x123...'
  },
  policies: './policies.yaml'
})

console.log(`Matched policy: ${dryRun.matchedPolicy}`)
console.log(`Action: ${dryRun.action}`)
console.log(`Would execute: ${dryRun.action === 'auto_approve'}`)

Best practices

Start restrictive: Begin with require_human_approval as the default action. Gradually add auto_approve policies as confidence builds.

Layer policies: Use multiple policies for defense in depth. Block known-bad patterns, approve known-good patterns, require review for everything else.

Monitor approvals: Track which policies trigger most frequently. Adjust thresholds based on actual agent behavior.

Set timeouts: Always configure approval timeouts. Transactions shouldn't pend indefinitely.

Log everything: Enable audit logging to track all policy evaluations and approval decisions.

Test thoroughly: Use testnet to validate policy behavior before mainnet deployment.

Example: Production policy set

policies:
  # Block list
  - name: block_zero_address
    conditions:
      recipient_blacklist: ["0x0000000000000000000000000000000000000000"]
    action: reject

  - name: block_unverified_contracts
    conditions:
      transaction_type: contract_call
      contract_verified: false
    action: reject

  # Auto-approve safe operations
  - name: auto_approve_tiny_transfers
    conditions:
      transaction_type: transfer
      max_value_usd: 10
      daily_limit_usd: 100
    action: auto_approve

  - name: auto_approve_whitelisted_contracts
    conditions:
      transaction_type: contract_call
      max_value_usd: 100
      recipient_whitelist:
        - 0x1234567890abcdef1234567890abcdef12345678
    action: auto_approve

  # Require approval for higher risk
  - name: approve_large_transfers
    conditions:
      transaction_type: transfer
      min_value_usd: 10
    action: require_human_approval
    notification:
      channels: [email, slack]
      timeout: 3600

  - name: approve_contract_calls
    conditions:
      transaction_type: contract_call
    action: require_human_approval
    notification:
      channels: [slack]
      timeout: 1800

  # Default deny
  - name: default_deny
    conditions: {}
    action: reject
    notification:
      channels: [slack]
      message: "Transaction matched no policy - rejected by default"

Troubleshooting

Policy not matching

Check condition syntax and values:

const debug = await client.debugPolicy({
  transaction: yourTransaction,
  policies: './policies.yaml'
})

console.log(debug.matchedPolicies)
console.log(debug.evaluationLog)

Approval timeout too short

Increase timeout or set up escalation:

notification:
  timeout: 7200  # 2 hours
  escalation:
    after: 3600  # Escalate after 1 hour
    to: [[email protected]]

Too many approval requests

Adjust policy thresholds or add more auto-approve rules:

# Before: Requires approval for everything >$10
- name: approve_transfers
  conditions:
    min_value_usd: 10
  action: require_human_approval

# After: Auto-approve up to $100
- name: auto_approve_medium
  conditions:
    max_value_usd: 100
  action: auto_approve

- name: approve_large
  conditions:
    min_value_usd: 100
  action: require_human_approval

Next steps

• Transaction simulation: Add pre-flight validation

• Security best practices: Production security checklist

• Monitoring and alerts: Set up observability