Configure policies

Goal

Define a tight spending envelope for an agent. Verify it blocks the wrong payments and allows the right ones. Roll it out.

Prerequisites

• A registered agent at KYA Level 1 or higher.
• API key and Ed25519 signing key.

Step 1: Compose the policy

Python

policy = client.policies.create(
    agent_id=agent.id,
    max_per_tx=50.00,
    max_daily=500.00,
    max_monthly=5000.00,
    allowed_categories=["cloud_compute", "api_consumption"],
    counterparty_whitelist=["0xA1b2...", "0xC3d4..."],
    escalation_threshold=200.00,
)
print(policy.id, policy.version)

TypeScript

const policy = await client.policies.create({
  agentId: agent.id,
  maxPerTx: 50.00,
  maxDaily: 500.00,
  maxMonthly: 5000.00,
  allowedCategories: ['cloud_compute', 'api_consumption'],
  counterpartyWhitelist: ['0xA1b2...', '0xC3d4...'],
  escalationThreshold: 200.00,
});
console.log(policy.id, policy.version);

The Merkle root commits to OrisL2PolicyRegistry within the minute.

Step 2: Pre-evaluate before sending

Python

cases = [
    (10.00, "api_consumption", "0xA1b2..."),     # should allow
    (75.00, "api_consumption", "0xA1b2..."),     # should deny per_tx
    (10.00, "marketing_ads", "0xA1b2..."),       # should deny category
    (10.00, "api_consumption", "0xUnknown..."),  # should deny counterparty
]
for amount, category, to in cases:
    v = client.policies.evaluate(
        agent_id=agent.id, to_address=to, amount=amount, category=category,
    )
    print(amount, category, to, "->", v.allow, v.deny_reason)

TypeScript

const cases = [
  { amount: 10.00, category: 'api_consumption', to: '0xA1b2...' },
  { amount: 75.00, category: 'api_consumption', to: '0xA1b2...' },
  { amount: 10.00, category: 'marketing_ads', to: '0xA1b2...' },
  { amount: 10.00, category: 'api_consumption', to: '0xUnknown...' },
];
for (const c of cases) {
  const v = await client.policies.evaluate({ agentId: agent.id, ...c });
  console.log(c, '->', v.allow, v.denyReason);
}

Step 3: Update a rule

Python

client.policies.update(policy.id, max_daily=750.00)

TypeScript

await client.policies.update(policy.id, { maxDaily: 750.00 });

The Redis cache is invalidated atomically. The next transaction sees the new rule.

Verification

The current policy version appears on every signed bundle. Read result.policy_version on a payment to confirm the rules in effect at payment time.

Troubleshooting

• OrisPolicyDeny with deny_reason="counterparty_not_allowed" — the destination is not in counterparty_whitelist. Add it or remove the rule.
• OrisPolicyDeny with deny_reason="amount_cap" — max_per_tx exceeded. Use escalation if the payment is legitimate.
• Policy update has no effect — verify policy.version incremented. A no-op update returns the existing version.

Where to go next

• Spending policies feature for the rule reference.
• L2 Policy for the cryptographic ground truth.
• Payment execution to send the first payment under the policy.