> ## 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 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 in a fixed order. 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, 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

<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** | All pass but one requires approval |
| **APPROVED**           | All checks pass                    |

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)             |
    | 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)       |
| `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": "09:00-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": "60", "action": "ALLOW" }]
  }
]
```

## Best Practices

<AccordionGroup>
  <Accordion title="Layer Your Policies">
    Create policies at different priority levels:

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

Each policy type supports specific rule types. Here is the complete set:

<AccordionGroup>
  <Accordion title="Spend Limits">
    | Rule Type       | Description                   |
    | --------------- | ----------------------------- |
    | `MAX_AMOUNT`    | Per-transaction limit         |
    | `DAILY_LIMIT`   | Daily cumulative spend        |
    | `WEEKLY_LIMIT`  | Weekly cumulative spend       |
    | `MONTHLY_LIMIT` | Monthly cumulative spend      |
    | `BUDGET_CAP`    | Budget allocation with period |
  </Accordion>

  <Accordion title="Time Controls">
    | Rule Type             | Description                       |
    | --------------------- | --------------------------------- |
    | `TIME_WINDOW`         | Allowed hours (start/end)         |
    | `DAY_OF_WEEK`         | Allowed days                      |
    | `DATE_RANGE`          | Valid date range                  |
    | `BLACKOUT_PERIOD`     | Block during maintenance/holidays |
    | `MAINTENANCE_WINDOW`  | Alias for blackout period         |
    | `BLOCKED_TIME_WINDOW` | Alias for blackout period         |
  </Accordion>

  <Accordion title="Counterparty & Address">
    | Rule Type                | Description                   |
    | ------------------------ | ----------------------------- |
    | `ALLOWED_COUNTERPARTIES` | Whitelist recipient addresses |
    | `BLOCKED_COUNTERPARTIES` | Blacklist recipient addresses |
    | `TRUST_SCORE`            | Minimum trust score threshold |
    | `COUNTERPARTY_STATUS`    | Required trust level          |
  </Accordion>

  <Accordion title="Category & Contract">
    | Rule Type            | Description                                                              |
    | -------------------- | ------------------------------------------------------------------------ |
    | `ALLOWED_CATEGORIES` | Whitelist spending categories                                            |
    | `BLOCKED_CATEGORIES` | Blacklist spending categories                                            |
    | `CONTRACT_ALLOWLIST` | Whitelist smart contracts, protocols, categories, and function selectors |
    | `ALLOWED_CONTRACTS`  | Alias for contract allowlist                                             |
    | `PROTOCOL_ALLOWLIST` | Alias for contract allowlist                                             |

    <Tip>Contract metadata (protocol name and category) is auto-populated from your org's **Contract Registry**. Register known contracts via `POST /api/contract-registry` with `address`, `protocolName`, and `protocolCategory`. When an agent includes `targetContractAddress` in a payment request, the evaluator enriches it automatically.</Tip>
  </Accordion>

  <Accordion title="Geographic & Compliance">
    | Rule Type                | Description                                    |
    | ------------------------ | ---------------------------------------------- |
    | `GEOGRAPHIC_RESTRICTION` | Country restrictions (OFAC)                    |
    | `VELOCITY_LIMIT`         | Transaction frequency limits                   |
    | `REQUIRE_APPROVAL_ABOVE` | Approval threshold for high-value transactions |
    | `FAIRSCALE_MIN_SCORE`    | Minimum Fairscale reputation score (Solana)    |

    <Note>OFAC sanctions screening and address sanctions checks run automatically, no policy rule needed. `GEOGRAPHIC_RESTRICTION` rules add configurable country allow/block lists on top of the built-in checks.</Note>
  </Accordion>

  <Accordion title="Card Payment">
    | Rule Type                | Description                       |
    | ------------------------ | --------------------------------- |
    | `CARD_ALLOWED_MCCS`      | Whitelist merchant category codes |
    | `CARD_BLOCKED_MCCS`      | Blocklist merchant category codes |
    | `CARD_ALLOWED_MERCHANTS` | Whitelist merchant names          |
    | `CARD_BLOCKED_MERCHANTS` | Blocklist merchant names          |
    | `CARD_MAX_AMOUNT`        | Maximum card payment amount       |
  </Accordion>

  <Accordion title="x402 Protocol">
    | Rule Type                    | Description                             |
    | ---------------------------- | --------------------------------------- |
    | `X402_PRICE_CEILING`         | Max amount per API call                 |
    | `X402_MAX_PER_ENDPOINT`      | Max spend per endpoint per period       |
    | `X402_MAX_PER_SERVICE`       | Max spend per service domain per period |
    | `X402_ALLOWED_SERVICES`      | Whitelist service domains               |
    | `X402_BLOCKED_SERVICES`      | Blocklist service domains               |
    | `X402_ALLOWED_FACILITATORS`  | Whitelist facilitator addresses         |
    | `X402_VELOCITY_PER_ENDPOINT` | Rate limit per endpoint                 |
    | `X402_SESSION_BUDGET`        | Max spend per session                   |
  </Accordion>

  <Accordion title="MPP Protocol">
    | Rule Type                     | Description                             |
    | ----------------------------- | --------------------------------------- |
    | `MPP_PRICE_CEILING`           | Max amount per MPP call                 |
    | `MPP_MAX_PER_ENDPOINT`        | Max spend per endpoint per period       |
    | `MPP_MAX_PER_SERVICE`         | Max spend per service domain per period |
    | `MPP_ALLOWED_SERVICES`        | Whitelist service domains               |
    | `MPP_BLOCKED_SERVICES`        | Blocklist service domains               |
    | `MPP_VELOCITY_PER_ENDPOINT`   | Rate limit per endpoint                 |
    | `MPP_SESSION_BUDGET`          | Max spend per session                   |
    | `MPP_MAX_SESSION_DEPOSIT`     | Max deposit per session                 |
    | `MPP_MAX_CONCURRENT_SESSIONS` | Max concurrent sessions                 |
    | `MPP_MAX_SESSION_DURATION`    | Max session duration (hours)            |
    | `MPP_BLOCK_SESSION_INTENT`    | Block session intent (one-time only)    |
    | `MPP_ALLOWED_METHODS`         | Whitelist payment methods               |
  </Accordion>
</AccordionGroup>

## 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>