Skip to main content

​
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

Spend Limit

Control maximum amounts per transaction, day, week, or month

Time Window

Restrict transactions to specific hours and days

Counterparty

Control which recipients are allowed based on trust

Geographic

OFAC sanctions screening and country restrictions — built-in and configurable

Category

Allow or block specific spending categories

Contract Allowlist

Restrict interactions to approved smart contracts and protocols via Contract Registry

Approval Threshold

Require manual approval above certain amounts

Velocity

Limit transaction frequency to prevent rapid drain

Whitelist

Only allow specific pre-approved addresses

x402 Controls

Price ceilings, service allowlists, and budget caps for x402 micropayments

MPP Controls

Session budgets, concurrency limits, and duration caps for MPP payments

Budget Allocation

Allocate budgets by department or project with period tracking

Expiration

Time-limited permissions with start and end dates

Card Payment

MCC restrictions, merchant filtering, and amount limits for card payments

​
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 database policy rules
  5. Counterparty Rules — Block list, trust requirements, network intelligence
  6. Relationship Limits — Per-counterparty spend limits from AgentRelationship records
  7. Final Decision — Aggregate results
OutcomeCondition
DENIEDAny check denies
REQUIRES_APPROVALAll pass but one requires approval
APPROVEDAll checks pass
For a hands-on walkthrough of how evaluation works, see the Policy Testing guide.

​
Creating Policies

​
Via Dashboard

1

Navigate to Policies

Go to Policies in the sidebar and click New Policy.
2

Configure Policy

FieldDescription
NameHuman-readable name
TypePolicy type (spend limit, time window, etc.)
Priority0-100 (higher = evaluated first)
DescriptionWhat this policy does
3

Add Rules

Define the specific rules for this policy.
4

Assign to Agents

Select which agents this policy applies to.

​
Via API

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_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

PropertyTypeDescription
namestringHuman-readable name
descriptionstringDetailed description
policyTypeenumType of policy
prioritynumberEvaluation order (0-100)
isActivebooleanWhether policy is enforced
rulesarraySpecific 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

curl -X POST https://conto.finance/api/cards/{cardId}/policies \
  -H "Authorization: Bearer $CONTO_ORG_KEY" \
  -d '{
    "policyId": "policy_abc123"
  }'

​
Assign to Agent

curl -X POST https://conto.finance/api/agents/{agentId}/policies \
  -H "Authorization: Bearer $CONTO_ORG_KEY" \
  -d '{
    "policyId": "policy_abc123"
  }'

​
Example: Standard Agent Setup

A typical agent configuration with multiple policies: 
[
  {
    "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

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)
Begin with strict policies and relax based on operational needs. Recommended starting limits for new agents: 100/tx,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:1,000, weekly: 5,000, monthly: $20,000). Override these with policy-level limits for tighter control.
Don’t block high-value transactions entirely - require approval:
{
  "policyType": "APPROVAL_THRESHOLD",
  "rules": [
    { "ruleType": "REQUIRE_APPROVAL_ABOVE", "operator": "GREATER_THAN", "value": "500", "action": "REQUIRE_APPROVAL" }
  ]
}
Use descriptions to explain policy intent:
{
  "name": "OFAC Compliance",
  "description": "Blocks transactions to OFAC-sanctioned countries. Required for regulatory compliance. Do not modify without legal approval."
}

​
Available Rule Types

Each policy type supports specific rule types. Here is the complete set:
Rule TypeDescription
MAX_AMOUNTPer-transaction limit
DAILY_LIMITDaily cumulative spend
WEEKLY_LIMITWeekly cumulative spend
MONTHLY_LIMITMonthly cumulative spend
BUDGET_CAPBudget allocation with period
Rule TypeDescription
TIME_WINDOWAllowed hours (start/end)
DAY_OF_WEEKAllowed days
DATE_RANGEValid date range
BLACKOUT_PERIODBlock during maintenance/holidays
MAINTENANCE_WINDOWAlias for blackout period
BLOCKED_TIME_WINDOWAlias for blackout period
Rule TypeDescription
ALLOWED_COUNTERPARTIESWhitelist recipient addresses
BLOCKED_COUNTERPARTIESBlacklist recipient addresses
TRUST_SCOREMinimum trust score threshold
COUNTERPARTY_STATUSRequired trust level
Rule TypeDescription
ALLOWED_CATEGORIESWhitelist spending categories
BLOCKED_CATEGORIESBlacklist spending categories
CONTRACT_ALLOWLISTWhitelist smart contracts, protocols, categories, and function selectors
ALLOWED_CONTRACTSAlias for contract allowlist
PROTOCOL_ALLOWLISTAlias for contract allowlist
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.
Rule TypeDescription
GEOGRAPHIC_RESTRICTIONCountry restrictions (OFAC)
VELOCITY_LIMITTransaction frequency limits
REQUIRE_APPROVAL_ABOVEApproval threshold for high-value transactions
FAIRSCALE_MIN_SCOREMinimum Fairscale reputation score (Solana)
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.
Rule TypeDescription
CARD_ALLOWED_MCCSWhitelist merchant category codes
CARD_BLOCKED_MCCSBlocklist merchant category codes
CARD_ALLOWED_MERCHANTSWhitelist merchant names
CARD_BLOCKED_MERCHANTSBlocklist merchant names
CARD_MAX_AMOUNTMaximum card payment amount
Rule TypeDescription
X402_PRICE_CEILINGMax amount per API call
X402_MAX_PER_ENDPOINTMax spend per endpoint per period
X402_MAX_PER_SERVICEMax spend per service domain per period
X402_ALLOWED_SERVICESWhitelist service domains
X402_BLOCKED_SERVICESBlocklist service domains
X402_ALLOWED_FACILITATORSWhitelist facilitator addresses
X402_VELOCITY_PER_ENDPOINTRate limit per endpoint
X402_SESSION_BUDGETMax spend per session
Rule TypeDescription
MPP_PRICE_CEILINGMax amount per MPP call
MPP_MAX_PER_ENDPOINTMax spend per endpoint per period
MPP_MAX_PER_SERVICEMax spend per service domain per period
MPP_ALLOWED_SERVICESWhitelist service domains
MPP_BLOCKED_SERVICESBlocklist service domains
MPP_VELOCITY_PER_ENDPOINTRate limit per endpoint
MPP_SESSION_BUDGETMax spend per session
MPP_MAX_SESSION_DEPOSITMax deposit per session
MPP_MAX_CONCURRENT_SESSIONSMax concurrent sessions
MPP_MAX_SESSION_DURATIONMax session duration (hours)
MPP_BLOCK_SESSION_INTENTBlock session intent (one-time only)
MPP_ALLOWED_METHODSWhitelist payment methods

​
Violation Details

When a payment is denied, detailed violation info is returned: 
{
  "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.

​
Next Steps

Spend Limits

Configure amount-based limits

Time Windows

Set up time-based restrictions