> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Overview

> Control agent spending with policies

# Policy System

The policy system is the core of Conto's spending controls. Policies define rules that govern how AI agents can spend funds.

## What is a Policy?

A policy is a set of rules that determine whether a payment should be:

* **APPROVED** - Payment can proceed
* **DENIED** - Payment is blocked
* **REQUIRES\_APPROVAL** - Manual approval needed

## Policy Types

<CardGroup cols={2}>
  <Card title="Spend Limit" icon="dollar-sign" href="/policies/spend-limits">
    Control maximum amounts per transaction, day, week, or month
  </Card>

  <Card title="Time Window" icon="clock" href="/policies/time-windows">
    Restrict transactions to specific hours and days
  </Card>

  <Card title="Counterparty" icon="user-check" href="/policies/counterparties">
    Control which recipients are allowed based on trust
  </Card>

  <Card title="Geographic" icon="globe" href="/policies/advanced#geographic-restrictions-ofac">
    OFAC sanctions screening and country restrictions, built-in and configurable
  </Card>

  <Card title="AgentScore Compliance" icon="shield-check" href="/policies/advanced#agentscore-commerce-rules">
    Require verified humans, enforce jurisdiction allowlists, and trigger identity step-up before settlement
  </Card>

  <Card title="Category" icon="tag">
    Allow or block specific spending categories
  </Card>

  <Card title="Contract Allowlist" icon="file-contract" href="/policies/advanced#contract-allowlist">
    Restrict interactions to approved smart contracts and protocols via Contract Registry
  </Card>

  <Card title="Approval Threshold" icon="check-circle">
    Require manual approval above certain amounts
  </Card>

  <Card title="Velocity" icon="gauge">
    Limit transaction frequency to prevent rapid drain
  </Card>

  <Card title="Whitelist" icon="list-check">
    Only allow specific pre-approved addresses
  </Card>

  <Card title="x402 Controls" icon="bolt" href="/policies/advanced#x402-protocol-rules">
    Price ceilings, service allowlists, and session budget caps for x402 micropayments
  </Card>

  <Card title="MPP Controls" icon="signal" href="/policies/advanced#mpp-protocol-rules">
    Session budgets, concurrency limits, and duration caps for MPP payments
  </Card>

  <Card title="Budget Allocation" icon="chart-pie" href="/policies/advanced#budget-allocations">
    Allocate budgets by department or project with period tracking
  </Card>

  <Card title="Expiration" icon="calendar-xmark" href="/policies/advanced#expiration-policies">
    Time-limited permissions with start and end dates
  </Card>

  <Card title="Card Payment" icon="credit-card" href="/policies/advanced#card-payment-rules">
    MCC restrictions, merchant filtering, and amount limits for card payments
  </Card>
</CardGroup>

## Policy Evaluation

Policies are evaluated fail-closed. When multiple policies are assigned, **all must pass**. The first DENY stops evaluation immediately.

### Evaluation Order

1. **Pre-checks**: Agent must be ACTIVE with linked wallets
2. **Geographic & Sanctions**: OFAC country check + address sanctions screening (always active, no policy needed)
3. **Counterparty Trust**: Pre-fetch trust level and network trust score for use in policy rules
4. **Wallet Policies**: Spend limits, wallet-level time windows (timezone-aware), and other configured policy rules
5. **Merchant Identity Gates**: Optional AgentScore assess results can add verified-human, KYC, sanctions, and jurisdiction context before final settlement
6. **Counterparty Rules**: Block list, trust requirements, network intelligence
7. **Relationship Limits**: Per-counterparty spend limits from `AgentRelationship` records
8. **Final Decision**: Aggregate results

Protocol-specific budget rules only count matching protocol transactions. x402 session budgets use
the x402 `sessionId` recorded with each payment, and MPP session budgets use the MPP `sessionId`,
so ordinary wallet transfers do not reduce protocol session allowance.

<Info>
  The default local sanctions provider now reads from Conto's `SanctionedAddress` table instead of
  a hardcoded demo list. That table is seeded by migration with known high-confidence OFAC matches
  and refreshed by the `sanctions-list-refresh` background job, so sanctions screening starts with
  a safe baseline even before the first feed sync completes.
</Info>

| Outcome                | Condition                                                      |
| ---------------------- | -------------------------------------------------------------- |
| **DENIED**             | Any check denies                                               |
| **REQUIRES\_APPROVAL** | No denial, and at least one rule or workflow requires approval |
| **APPROVED**           | All checks pass                                                |

### Evaluation Semantics

Policy rules use simple AND logic. Every active policy assigned to the selected agent or wallet is evaluated, and every rule inside those policies must pass unless it is a `DENY` or `REQUIRE_APPROVAL` trigger that does not match.

| Action             | Meaning                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `ALLOW`            | The condition describes what is permitted. If the condition does not match, the payment is denied.         |
| `DENY`             | The condition describes what is blocked. If the condition matches, the payment is denied.                  |
| `REQUIRE_APPROVAL` | The condition describes what needs review. If it matches and no DENY fires, the payment requires approval. |

<Warning>
  `priority` is sort order, not override precedence. A higher-priority `ALLOW` cannot override a
  lower-priority deny or a failed allowlist. Use one wider allowlist rule when you need alternatives,
  not two competing policies.
</Warning>

For a hands-on walkthrough of how evaluation works, see the [Policy Testing guide](/guides/policy-testing).

## Creating Policies

### Via Dashboard

<Steps>
  <Step title="Navigate to Policies">
    Go to **Policies** in the sidebar and click **New Policy**.
  </Step>

  <Step title="Configure Policy">
    | Field       | Description                                                          |
    | ----------- | -------------------------------------------------------------------- |
    | Name        | Human-readable name                                                  |
    | Type        | Policy type (spend limit, time window, etc.)                         |
    | Priority    | 0-100 (higher = evaluated first, but never overrides a failing rule) |
    | Description | What this policy does                                                |
  </Step>

  <Step title="Add Rules">
    Define the specific rules for this policy.
  </Step>

  <Step title="Assign to Agents">
    Select which agents this policy applies to.
  </Step>
</Steps>

### Via API

```bash theme={null}
curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Spend Limit",
    "description": "Limits daily spending to $1000",
    "policyType": "SPEND_LIMIT",
    "priority": 50,
    "isActive": true
  }'
```

## Policy Properties

| Property      | Type    | Description                                       |
| ------------- | ------- | ------------------------------------------------- |
| `name`        | string  | Human-readable name                               |
| `description` | string  | Detailed description                              |
| `policyType`  | enum    | Type of policy                                    |
| `priority`    | number  | Evaluation order (0-100), not override precedence |
| `isActive`    | boolean | Whether policy is enforced                        |
| `rules`       | array   | Specific rules for this policy                    |

## Assigning Policies

Policies can be assigned to:

* **Agents** - Apply to specific agents
* **Wallets** - Apply to specific wallets
* **Cards** - Apply to specific payment cards

### Assign to Card

```bash theme={null}
curl -X POST https://conto.finance/api/cards/{cardId}/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -d '{
    "policyId": "cmm5c0pol000l49h7dmsuc11p"
  }'
```

### Assign to Agent

```bash theme={null}
curl -X POST https://conto.finance/api/agents/{agentId}/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -d '{
    "policyId": "cmm5c0pol000l49h7dmsuc11p"
  }'
```

## Example: Standard Agent Setup

A typical agent configuration with multiple policies:

```json theme={null}
[
  {
    "name": "Spend Limits",
    "policyType": "SPEND_LIMIT",
    "priority": 50,
    "rules": [
      { "ruleType": "MAX_AMOUNT", "operator": "LTE", "value": "200", "action": "ALLOW" },
      { "ruleType": "DAILY_LIMIT", "operator": "LTE", "value": "1000", "action": "ALLOW" },
      { "ruleType": "MONTHLY_LIMIT", "operator": "LTE", "value": "10000", "action": "ALLOW" }
    ]
  },
  {
    "name": "Business Hours",
    "policyType": "TIME_WINDOW",
    "priority": 50,
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"18:00\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN",
        "value": ["Mon", "Tue", "Wed", "Thu", "Fri"],
        "action": "ALLOW"
      }
    ]
  },
  {
    "name": "Trusted Vendors Only",
    "policyType": "COUNTERPARTY",
    "priority": 50,
    "rules": [{ "ruleType": "TRUST_SCORE", "operator": "GTE", "value": "0.6", "action": "ALLOW" }]
  }
]
```

## Best Practices

<AccordionGroup>
  <Accordion title="Layer Your Policies">
    Create policies at different priority levels to make evaluation and debugging easier:

    * **HIGH (90-100)**: Security/Compliance (sanctions, blocked addresses)
    * **MEDIUM (40-60)**: Business Rules (limits, time windows)
    * **LOW (0-20)**: Defaults (catch-all rules)

    Priority changes evaluation order only. It does not let an allow rule override a stricter rule
    that runs later.
  </Accordion>

  <Accordion title="Start Restrictive">
    Begin with strict policies and relax based on operational needs. Recommended starting limits for new agents: $100/tx, $500/day, \$5,000/month.

    * Day 1: \$100/day limit, 3 trusted vendors
    * Week 2: \$500/day, add 5 more vendors
    * Month 2: \$1,000/day, category-based restrictions

    Note: Auto-created wallet defaults are higher (daily: $1,000, weekly: $5,000, monthly: \$20,000). Override these with policy-level limits for tighter control.
  </Accordion>

  <Accordion title="Use Approval Thresholds">
    Don't block high-value transactions entirely - require approval:

    ```json theme={null}
    {
      "policyType": "APPROVAL_THRESHOLD",
      "rules": [
        { "ruleType": "REQUIRE_APPROVAL_ABOVE", "operator": "GREATER_THAN", "value": "500", "action": "REQUIRE_APPROVAL" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Document Your Policies">
    Use descriptions to explain policy intent:

    ```json theme={null}
    {
      "name": "OFAC Compliance",
      "description": "Blocks transactions to OFAC-sanctioned countries. Required for regulatory compliance. Do not modify without legal approval."
    }
    ```
  </Accordion>
</AccordionGroup>

## Available Rule Types

The value formats, operators, and caveats for every rule type live in [Advanced Policies](/policies/advanced). Quick index:

| Category                                                                   | Rule Types                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Spend limits](/policies/advanced#supported-rule-types)                    | `MAX_AMOUNT`, `DAILY_LIMIT`, `WEEKLY_LIMIT`, `MONTHLY_LIMIT`, `BUDGET_CAP`                                                                                                                                                                                                                                     |
| [Time controls](/policies/advanced#supported-rule-types)                   | `TIME_WINDOW`, `DAY_OF_WEEK`, `DATE_RANGE`, `BLACKOUT_PERIOD` (aliases: `MAINTENANCE_WINDOW`, `BLOCKED_TIME_WINDOW`)                                                                                                                                                                                           |
| [Counterparty & address](/policies/advanced#supported-rule-types)          | `ALLOWED_COUNTERPARTIES`, `BLOCKED_COUNTERPARTIES`, `TRUST_SCORE`, `COUNTERPARTY_STATUS`                                                                                                                                                                                                                       |
| [Category & contract](/policies/advanced#contract-allowlist)               | `ALLOWED_CATEGORIES`, `BLOCKED_CATEGORIES`, `CONTRACT_ALLOWLIST` (aliases: `ALLOWED_CONTRACTS`, `PROTOCOL_ALLOWLIST`)                                                                                                                                                                                          |
| [Geographic & compliance](/policies/advanced#geographic-restrictions-ofac) | `GEOGRAPHIC_RESTRICTION`, `VELOCITY_LIMIT`, `REQUIRE_APPROVAL_ABOVE`, `FAIRSCALE_MIN_SCORE`                                                                                                                                                                                                                    |
| [Card payment](/policies/advanced#card-payment-rules)                      | `CARD_MAX_AMOUNT`, `CARD_ALLOWED_MCCS`, `CARD_BLOCKED_MCCS`, `CARD_ALLOWED_MERCHANTS`, `CARD_BLOCKED_MERCHANTS`                                                                                                                                                                                                |
| [x402 protocol](/policies/advanced#x402-protocol-rules)                    | `X402_MAX_PER_REQUEST`, `X402_PRICE_CEILING`, `X402_MAX_PER_ENDPOINT`, `X402_MAX_PER_SERVICE`, `X402_ALLOWED_SERVICES`, `X402_BLOCKED_SERVICES`, `X402_ALLOWED_FACILITATORS`, `X402_VELOCITY_PER_ENDPOINT`, `X402_SESSION_BUDGET`                                                                              |
| [MPP protocol](/policies/advanced#mpp-protocol-rules)                      | `MPP_MAX_PER_REQUEST`, `MPP_PRICE_CEILING`, `MPP_MAX_PER_ENDPOINT`, `MPP_MAX_PER_SERVICE`, `MPP_ALLOWED_SERVICES`, `MPP_BLOCKED_SERVICES`, `MPP_VELOCITY_PER_ENDPOINT`, `MPP_SESSION_BUDGET`, `MPP_MAX_SESSION_DEPOSIT`, `MPP_MAX_CONCURRENT_SESSIONS`, `MPP_MAX_SESSION_DURATION`, `MPP_BLOCK_SESSION_INTENT` |
| [AgentScore commerce](/policies/advanced#agentscore-commerce-rules)        | `AGENTSCORE_REQUIRE_VERIFIED`, `AGENTSCORE_ALLOWED_JURISDICTIONS`, `AGENTSCORE_BLOCKED_JURISDICTIONS`                                                                                                                                                                                                          |

## Violation Details

When a payment is denied, detailed violation info is returned:

```json theme={null}
{
  "status": "DENIED",
  "reasons": ["Would exceed daily limit"],
  "violations": [
    {
      "type": "DAILY_LIMIT",
      "limit": 1000,
      "current": 1150,
      "message": "[Wallet limit] Would exceed daily limit: $-150.00 remaining of $1000 daily limit",
      "source": "wallet_limit"
    },
    {
      "type": "PER_TX_LIMIT",
      "limit": 200,
      "current": 300,
      "message": "[Policy: High-Value Guard] Amount 300 exceeds per-transaction limit of 200",
      "source": "policy_rule",
      "policyName": "High-Value Guard"
    }
  ]
}
```

Each violation includes a `source` field indicating whether the denial came from a **wallet-level limit** (`"wallet_limit"`) or a **policy rule** (`"policy_rule"`). Policy rule violations also include `policyName`.

## Engine Architecture

Each rule type is evaluated by a dedicated strategy module. The engine looks up
the strategy for a rule's `ruleType` from a registry and delegates evaluation.
New rule types can be added without modifying the core engine, register a new
strategy and update the SKILL.md docs.

## Next Steps

<CardGroup cols={2}>
  <Card title="Spend Limits" icon="dollar-sign" href="/policies/spend-limits">
    Configure amount-based limits
  </Card>

  <Card title="Time Windows" icon="clock" href="/policies/time-windows">
    Set up time-based restrictions
  </Card>
</CardGroup>