Advanced Policies

Advanced policy types and the rule engine for complex business requirements.

Policy Rules

Each policy consists of one or more rules. Rules define specific conditions and actions:

Rule Structure

{
  "ruleType": "SINGLE_AMOUNT",
  "operator": "GREATER_THAN",
  "value": "{\"amount\": 500}",
  "action": "REQUIRE_APPROVAL"
}

Field	Description
`ruleType`	Type of condition (see below)
`operator`	Comparison operator
`value`	JSON-encoded value for comparison
`action`	`ALLOW`, `DENY`, or `REQUIRE_APPROVAL`

Supported Rule Types

Rule Type	Description	Example Value
`MAX_AMOUNT`	Per-transaction amount	`"500"`
`DAILY_LIMIT`	Daily spend cap	`"1000"`
`WEEKLY_LIMIT`	Weekly spend cap	`"5000"`
`MONTHLY_LIMIT`	Monthly spend cap	`"20000"`
`BUDGET_CAP`	Budget allocation	`"{\"amount\": 50000, \"period\": \"MONTHLY\"}"`
`TIME_WINDOW`	Time window restriction	`"{\"start\": \"09:00\", \"end\": \"18:00\"}"`
`DAY_OF_WEEK`	Day restriction	`"[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"]"`
`DATE_RANGE`	Temporal validity	`"{\"start\": \"2025-07-01\", \"end\": \"2025-09-30\"}"`
`BLACKOUT_PERIOD`	Block during windows	`"{\"windows\": [{\"start\": \"02:00\", \"end\": \"06:00\", \"reason\": \"Maintenance\"}]}"`
`ALLOWED_CATEGORIES`	Allowed categories	`"[\"software\", \"infrastructure\"]"`
`BLOCKED_CATEGORIES`	Blocked categories	`"[\"gambling\", \"adult\"]"`
`ALLOWED_COUNTERPARTIES`	Allowed addresses	`"[\"0x123...\", \"0x456...\"]"`
`BLOCKED_COUNTERPARTIES`	Blocked addresses	`"[\"0xdead...\"]"`
`VELOCITY_LIMIT`	Transaction frequency	`"{\"maxCount\": 10, \"period\": \"HOUR\"}"`
`REQUIRE_APPROVAL_ABOVE`	Approval threshold	`"2500"`
`GEOGRAPHIC_RESTRICTION`	Blocked countries	`"[\"CU\", \"IR\", \"KP\", \"SY\", \"RU\"]"`
`TRUST_SCORE`	Min trust score	`"70"`
`COUNTERPARTY_STATUS`	Trust level requirement	`"{\"status\": \"TRUSTED\"}"`
`CONTRACT_ALLOWLIST`	Allowed contracts	`"{\"contracts\": [\"0x...\"], \"protocols\": [\"uniswap\"]}"`
`FAIRSCALE_MIN_SCORE`	Min Fairscale reputation (Solana)	`"50"`

Supported Operators

Operator	Aliases	Description
`EQUALS`	`EQ`	Exact match
`NOT_EQUALS`	`NEQ`	Not equal
`GREATER_THAN`	`GT`	Greater than
`GREATER_THAN_OR_EQUAL`	`GTE`, `GREATER_THAN_OR_EQUALS`	Greater or equal
`LESS_THAN`	`LT`	Less than
`LESS_THAN_OR_EQUAL`	`LTE`, `LESS_THAN_OR_EQUALS`	Less or equal
`IN`	`IN_LIST`	Value in list
`NOT_IN`	`NOT_IN_LIST`	Value not in list
`BETWEEN`	-	Within range
`NOT_BETWEEN`	-	Outside range

Rule Actions

ALLOW - If condition matches, allow the transaction
DENY - If condition matches, block the transaction
REQUIRE_APPROVAL - If condition matches, require manual approval

Example: High-Value Approval Rule

Block transactions over $500 unless manually approved:

{
  "name": "High Value Transaction Review",
  "policyType": "APPROVAL_THRESHOLD",
  "priority": 80,
  "rules": [
    {
      "ruleType": "SINGLE_AMOUNT",
      "operator": "GREATER_THAN",
      "value": "{\"amount\": 500}",
      "action": "REQUIRE_APPROVAL"
    }
  ]
}

Geographic Restrictions (OFAC)

Geographic restrictions include both built-in enforcement (always active) and configurable rules (via policies).

Built-in Enforcement

The policy evaluator automatically performs two checks before any other policy is evaluated:

Country check — If recipientCountry is provided in the payment context, it’s checked against the OFAC sanctioned countries list. Blocked immediately if matched.
Address sanctions screening — The recipient address is screened against sanctions lists via the configured provider (Chainalysis, TRM Labs, or a local OFAC SDN list). Blocked immediately if flagged.

Configure the sanctions provider via the SANCTIONS_PROVIDER environment variable:

chainalysis — Chainalysis Risk API (requires CHAINALYSIS_API_KEY)
trm — TRM Labs API (requires TRM_API_KEY)
local — Local OFAC SDN list (default, no API key needed)

To enable country-based blocking, include recipientCountry (ISO 3166-1 alpha-2, e.g., "US", "IR") in the PaymentContext when calling the evaluator. The SDK payment endpoints populate this automatically when available.

Configurable Rules

Add custom country allow/deny lists on top of the built-in checks:

curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [
      {
        "ruleType": "GEOGRAPHIC_RESTRICTION",
        "operator": "IN_LIST",
        "value": "[\"US\", \"GB\", \"DE\", \"FR\"]",
        "action": "ALLOW"
      }
    ]
  }'

OFAC Sanctioned Countries (Built-in)

Code	Country
CU	Cuba
IR	Iran
KP	North Korea
SY	Syria
RU	Russia
BY	Belarus
MM	Myanmar
VE	Venezuela
SD	Sudan
SS	South Sudan
LB	Lebanon
LY	Libya
SO	Somalia
YE	Yemen

Always consult legal counsel for compliance requirements. This is not legal advice.

Approval Thresholds

Require manual approval above certain amounts:

{
  "policyType": "APPROVAL_THRESHOLD",
  "rules": [
    {
      "type": "AMOUNT_THRESHOLD",
      "threshold": 500,
      "approvers": ["admin", "finance"]
    }
  ]
}

When triggered:

Payment returns REQUIRES_APPROVAL
Approvers are notified
Payment held until approved or denied

Conto records only one final approval decision for each request, even if multiple approvers act at nearly the same time. This prevents the same payment from being resolved twice. For external channels, email approvals use per-user confirmation links. Shared channels such as Slack, Telegram, WhatsApp, and generic webhooks deep-link back to the dashboard until the acting approver can be verified reliably.

Velocity Limits

Control transaction frequency:

curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [
      {
        "ruleType": "VELOCITY_LIMIT",
        "operator": "LESS_THAN",
        "value": "{\"maxCount\": 10, \"period\": \"HOUR\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "VELOCITY_LIMIT",
        "operator": "LESS_THAN",
        "value": "{\"maxAmount\": 1000, \"period\": \"DAILY\"}",
        "action": "ALLOW"
      }
    ]
  }'

Velocity counting is per-wallet, per-agent. It counts transactions with status CONFIRMED or PENDING. The current transaction is included in the count (+1).

Use cases:

Prevent rapid drain attacks
Detect unusual patterns
Rate limit agent activity

Category Restrictions

Allow or block specific categories:

curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [
      {
        "ruleType": "BLOCKED_CATEGORIES",
        "operator": "IN_LIST",
        "value": "[\"gambling\", \"adult\", \"weapons\"]",
        "action": "DENY"
      },
      {
        "ruleType": "ALLOWED_CATEGORIES",
        "operator": "IN_LIST",
        "value": "[\"infrastructure\", \"ai_services\", \"marketing\"]",
        "action": "ALLOW"
      }
    ]
  }'

Category matching is case-insensitive. If no category is provided in the payment request, ALLOWED_CATEGORIES rules with ALLOW action are skipped (not denied).

Contract Allowlist

Restrict agent interactions to approved smart contracts, protocols, and function selectors. Contract metadata is auto-populated from the Contract Registry.

Setting Up the Contract Registry

curl -X POST https://conto.finance/api/contract-registry \
  -H "Authorization: Bearer $CONTO_ORG_KEY" \
  -d '{
    "address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
    "protocolName": "uniswap",
    "protocolCategory": "DEX",
    "label": "Uniswap V2 Router",
    "chainId": "1"
  }'

Contract Allowlist Rules

{
  "policyType": "CONTRACT_ALLOWLIST",
  "rules": [
    {
      "ruleType": "CONTRACT_ALLOWLIST",
      "operator": "IN_LIST",
      "value": "{\"protocols\": [\"uniswap\", \"aave\"], \"categories\": [\"DEX\", \"LENDING\"]}",
      "action": "ALLOW"
    }
  ]
}

The value supports four filter types (all optional):

Field	Description	Example
`contracts`	Allowed contract addresses	`["0x7a25...", "0x1f98..."]`
`protocols`	Allowed protocol names	`["uniswap", "aave"]`
`categories`	Allowed protocol categories	`["DEX", "LENDING", "BRIDGE"]`
`functions`	Allowed 4-byte function selectors	`["0xa9059cbb", "0x095ea7b3"]`

Passing Contract Context in Payment Requests

Include targetContractAddress (and optionally functionSelector) in payment requests:

const result = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D',
  purpose: 'Swap USDC for ETH',
  targetContractAddress: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D',
  functionSelector: '0x38ed1739',
});

The evaluator automatically looks up protocolName and protocolCategory from the Contract Registry. If the caller provides them explicitly, those values take precedence over the registry lookup.

If a CONTRACT_ALLOWLIST rule with ALLOW action exists but the payment request does not include targetContractAddress, the request is denied (fail-closed). This prevents bypassing the allowlist by omitting context.

Budget Allocations

Allocate budgets by department or project:

{
  "policyType": "BUDGET_ALLOCATION",
  "rules": [
    {
      "type": "DEPARTMENT_BUDGET",
      "department": "ENGINEERING",
      "monthlyBudget": 50000,
      "rollover": false
    },
    {
      "type": "PROJECT_BUDGET",
      "projectId": "PROJECT_123",
      "totalBudget": 100000
    }
  ]
}

Expiration Policies

Time-limited permissions:

{
  "policyType": "EXPIRATION",
  "rules": [
    {
      "type": "VALID_UNTIL",
      "expiresAt": "2025-12-31T23:59:59Z"
    },
    {
      "type": "VALID_BETWEEN",
      "startDate": "2025-07-01",
      "endDate": "2025-09-30"
    }
  ]
}

Use cases:

Temporary elevated access
Contract-based limits
Trial periods

Composite Policies

Combine multiple conditions with AND/OR logic:

{
  "policyType": "COMPOSITE",
  "rules": [
    {
      "type": "AND",
      "conditions": [
        { "type": "AMOUNT_LESS_THAN", "amount": 1000 },
        { "type": "CATEGORY_IS", "category": "INFRASTRUCTURE" }
      ]
    },
    {
      "type": "OR",
      "conditions": [{ "type": "TRUSTED_COUNTERPARTY" }, { "type": "MANUAL_OVERRIDE" }]
    }
  ]
}

Example: High-Security Agent

Complete configuration for a high-security agent:

[
  {
    "name": "OFAC Compliance",
    "policyType": "GEOGRAPHIC",
    "priority": 100,
    "rules": [{ "type": "BLOCK_COUNTRIES", "countries": ["NK", "IR", "SY", "CU", "RU"] }]
  },
  {
    "name": "Whitelist Only",
    "policyType": "WHITELIST",
    "priority": 90,
    "rules": [{ "type": "ADDRESS_WHITELIST", "addresses": ["0x..."] }]
  },
  {
    "name": "Strict Limits",
    "policyType": "SPEND_LIMIT",
    "priority": 80,
    "rules": [
      { "type": "PER_TRANSACTION", "maxAmount": 100 },
      { "type": "DAILY", "maxAmount": 500 }
    ]
  },
  {
    "name": "All Require Approval",
    "policyType": "APPROVAL_THRESHOLD",
    "priority": 70,
    "rules": [{ "type": "AMOUNT_THRESHOLD", "threshold": 0 }]
  }
]

x402 Protocol Rules

These rules govern HTTP 402 micropayments made through the x402 protocol:

Rule Type	Description	Value Format
`X402_MAX_PER_REQUEST`	Maximum amount per x402 request	`{"maxAmount": N}`
`X402_PRICE_CEILING`	Price ceiling for any x402 payment	`{"maxPrice": N}`
`X402_MAX_PER_ENDPOINT`	Limit per API endpoint	`{"maxAmount": N, "maxCalls": N, "period": "DAILY"}`
`X402_MAX_PER_SERVICE`	Limit per service domain	`{"maxAmount": N, "maxCalls": N, "period": "DAILY"}`
`X402_ALLOWED_SERVICES`	Allowlist of service domains	`["api.example.com", "data.service.io"]`
`X402_BLOCKED_SERVICES`	Blocklist of service domains	`["malicious.site"]`
`X402_ALLOWED_FACILITATORS`	Allowed x402 facilitator addresses	`["0x..."]`
`X402_VELOCITY_PER_ENDPOINT`	Rate limit per endpoint	`{"maxCalls": N, "period": "HOUR"}`
`X402_SESSION_BUDGET`	Session-level spending budget	`{"maxAmount": N}`

MPP Protocol Rules

These rules govern Machine Payment Protocol (MPP) session-based micropayments:

Rule Type	Description	Value Format
`MPP_MAX_PER_REQUEST`	Maximum per MPP credential charge	`{"maxAmount": N}`
`MPP_PRICE_CEILING`	Price ceiling for MPP payments	`{"maxPrice": N}`
`MPP_MAX_PER_ENDPOINT`	Limit per MPP resource endpoint	`{"maxAmount": N, "maxCalls": N}`
`MPP_MAX_PER_SERVICE`	Limit per MPP service domain	`{"maxAmount": N, "maxCalls": N, "period": "DAILY"}`
`MPP_ALLOWED_SERVICES`	Allowlist of MPP service domains	`["api.example.com"]`
`MPP_BLOCKED_SERVICES`	Blocklist of MPP service domains	`["blocked.site"]`
`MPP_SESSION_BUDGET`	Maximum deposit per MPP session	`{"maxDeposit": N}`
`MPP_MAX_SESSION_DEPOSIT`	Hard cap on session deposit amount	`{"maxDeposit": N}`
`MPP_MAX_CONCURRENT_SESSIONS`	Max active sessions per agent	`{"maxSessions": N}`
`MPP_MAX_SESSION_DURATION`	Maximum session duration	`{"maxDurationMs": N}`
`MPP_BLOCK_SESSION_INTENT`	Block specific session intents	`["streaming"]`
`MPP_ALLOWED_METHODS`	Allowed HTTP methods for MPP	`["GET", "POST"]`
`MPP_VELOCITY_PER_ENDPOINT`	Rate limit per MPP endpoint	`{"maxCalls": N, "period": "HOUR"}`

Card Payment Rules

These rules govern card-based payments (Lithic virtual/physical cards):

Rule Type	Description	Value Format
`CARD_MAX_AMOUNT`	Maximum per card transaction	`"500"`
`CARD_ALLOWED_MCCS`	Allowed merchant category codes	`["5411", "5812"]`
`CARD_BLOCKED_MCCS`	Blocked merchant category codes	`["7995"]`
`CARD_ALLOWED_MERCHANTS`	Allowed merchant names	`["Amazon", "Stripe"]`
`CARD_BLOCKED_MERCHANTS`	Blocked merchant names	`["Casino.com"]`

Bulk Policy Operations

Create Multiple Policies

curl -X POST https://conto.finance/api/policies/bulk \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "policies": [
      { "name": "Policy 1", "policyType": "SPEND_LIMIT", ... },
      { "name": "Policy 2", "policyType": "TIME_WINDOW", ... }
    ]
  }'

Assign to Multiple Agents

curl -X PUT https://conto.finance/api/policies/bulk \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "assignments": [
      { "policyId": "policy_1", "agentIds": ["agent_a", "agent_b"] },
      { "policyId": "policy_2", "agentIds": ["agent_c"] }
    ]
  }'

Get Started

API

Quick Start

Conto Pay

CLI

SDK

AI Assistant

MCP Server

Policies

Integrations

Guides

Changelog

​Advanced Policies

​Policy Rules

​Rule Structure

​Supported Rule Types

​Supported Operators

​Rule Actions

​Example: High-Value Approval Rule

​Geographic Restrictions (OFAC)

​Built-in Enforcement

​Configurable Rules

​OFAC Sanctioned Countries (Built-in)

​Approval Thresholds

​Velocity Limits

​Category Restrictions

​Contract Allowlist

​Setting Up the Contract Registry

​Contract Allowlist Rules

​Passing Contract Context in Payment Requests

​Budget Allocations

​Expiration Policies

​Composite Policies

​Example: High-Security Agent

​x402 Protocol Rules

​MPP Protocol Rules

​Card Payment Rules

​Bulk Policy Operations

​Create Multiple Policies

​Assign to Multiple Agents

Advanced Policies

Policy Rules

Rule Structure

Supported Rule Types

Supported Operators

Rule Actions

Example: High-Value Approval Rule

Geographic Restrictions (OFAC)

Built-in Enforcement

Configurable Rules

OFAC Sanctioned Countries (Built-in)

Approval Thresholds

Velocity Limits

Category Restrictions

Contract Allowlist

Setting Up the Contract Registry

Contract Allowlist Rules

Passing Contract Context in Payment Requests

Budget Allocations

Expiration Policies

Composite Policies

Example: High-Security Agent

x402 Protocol Rules

MPP Protocol Rules

Card Payment Rules

Bulk Policy Operations

Create Multiple Policies

Assign to Multiple Agents