Policies

Programmable spending rules that control what agents can and cannot do with their wallets.

Overview

The Policy Engine evaluates every payment request against a wallet's configured rules before the transaction reaches the ledger. Policies are fail-closed: if the engine encounters an error during evaluation, the transaction is denied.

Rule Types

Rule	Field	Description
Max Transaction Amount	`maxTransactionAmount`	Rejects payments exceeding this value
Daily Spending Limit	`dailySpendingLimit`	Caps total spending per calendar day (UTC)
Approved Recipients	`approvedRecipients`	Whitelist -- only these wallet IDs can receive funds
Blocked Recipients	`blockedRecipients`	Blacklist -- these wallet IDs are always rejected
Time Restrictions	`timeRestrictions`	Limits transactions to specific hours/days
Human Approval	`requireHumanApproval`	Flags transactions for manual review

Rules with null values are not enforced. Multiple rules on a single policy are AND-combined: all must pass.

Creating Policies

import { Wallgent } from '@wallgent/sdk';

const wg = new Wallgent('wg_test_abc123');

await wg.policies.create('wal_01J_wallet_id', {
  name: 'Production Safeguards',
  maxTransactionAmount: '50.00',
  dailySpendingLimit: '200.00',
  approvedRecipients: ['wal_vendor_a', 'wal_vendor_b'],
  requireHumanApproval: false,
});

Evaluation Flow

Payment Request
      |
      v
  Load enabled policies for wallet
      |
      v
  For each policy:
    Run all non-null rules
    Short-circuit on first DENY
      |
      v
  All passed?  -->  Allow transaction
  Any denied?  -->  Return POLICY_DENIED error
  Engine error? --> DENY (fail-closed)

Every evaluation is logged to the policy_evaluations table with the result, reason, and evaluation data.

Managing Policies

// List policies for a wallet
const policies = await wg.policies.list('wal_01J_wallet_id');

// Update a policy
await wg.policies.update('pol_01J_policy_id', {
  dailySpendingLimit: '500.00',
  enabled: true,
});

// Disable a policy
await wg.policies.update('pol_01J_policy_id', {
  enabled: false,
});

// Delete a policy
await wg.policies.delete('pol_01J_policy_id');

Daily Limit Calculation

The daily spending limit sums all posted debit entries for the wallet's account within the current UTC day. If adding the new payment would exceed the limit, the request is denied with error code POLICY_DENIED and a reason describing the remaining budget.

Best Practices

Start restrictive. Set tight limits initially and relax them as you gain confidence in the agent's behavior.
Use approved recipients. Whitelist known vendor wallets rather than relying solely on amount limits.
Enable human approval for high-value or unusual transaction patterns during early deployment.
Monitor evaluations. Check the policy evaluation logs in the dashboard to understand denial patterns.