Skip to main content

​
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"
}
FieldDescription
ruleTypeType of condition (see below)
operatorComparison operator
valueJSON-encoded value for comparison
actionALLOW, DENY, or REQUIRE_APPROVAL

​
Supported Rule Types

Rule TypeDescriptionExample Value
MAX_AMOUNTPer-transaction amount"500"
DAILY_LIMITDaily spend cap"1000"
WEEKLY_LIMITWeekly spend cap"5000"
MONTHLY_LIMITMonthly spend cap"20000"
BUDGET_CAPBudget allocation"{\"amount\": 50000, \"period\": \"MONTHLY\"}"
TIME_WINDOWTime window restriction"{\"start\": \"09:00\", \"end\": \"18:00\"}"
DAY_OF_WEEKDay restriction"[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"]"
DATE_RANGETemporal validity"{\"start\": \"2025-07-01\", \"end\": \"2025-09-30\"}"
BLACKOUT_PERIODBlock during windows"{\"windows\": [{\"start\": \"02:00\", \"end\": \"06:00\", \"reason\": \"Maintenance\"}]}"
ALLOWED_CATEGORIESAllowed categories"[\"software\", \"infrastructure\"]"
BLOCKED_CATEGORIESBlocked categories"[\"gambling\", \"adult\"]"
ALLOWED_COUNTERPARTIESAllowed addresses"[\"0x123...\", \"0x456...\"]"
BLOCKED_COUNTERPARTIESBlocked addresses"[\"0xdead...\"]"
VELOCITY_LIMITTransaction frequency"{\"maxCount\": 10, \"period\": \"HOUR\"}"
REQUIRE_APPROVAL_ABOVEApproval threshold"2500"
GEOGRAPHIC_RESTRICTIONBlocked countries"[\"CU\", \"IR\", \"KP\", \"SY\", \"RU\"]"
TRUST_SCOREMin trust score"70"
COUNTERPARTY_STATUSTrust level requirement"{\"status\": \"TRUSTED\"}"
CONTRACT_ALLOWLISTAllowed contracts"{\"contracts\": [\"0x...\"], \"protocols\": [\"uniswap\"]}"
FAIRSCALE_MIN_SCOREMin Fairscale reputation (Solana)"50"

​
Supported Operators

OperatorAliasesDescription
EQUALSEQExact match
NOT_EQUALSNEQNot equal
GREATER_THANGTGreater than
GREATER_THAN_OR_EQUALGTE, GREATER_THAN_OR_EQUALSGreater or equal
LESS_THANLTLess than
LESS_THAN_OR_EQUALLTE, LESS_THAN_OR_EQUALSLess or equal
ININ_LISTValue in list
NOT_INNOT_IN_LISTValue 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:
  1. Country check — If recipientCountry is provided in the payment context, it’s checked against the OFAC sanctioned countries list. Blocked immediately if matched.
  2. 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)

CodeCountry
CUCuba
IRIran
KPNorth Korea
SYSyria
RURussia
BYBelarus
MMMyanmar
VEVenezuela
SDSudan
SSSouth Sudan
LBLebanon
LYLibya
SOSomalia
YEYemen
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

​
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

Register known contracts so the policy evaluator can enrich payment requests with protocol metadata: 
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):
FieldDescriptionExample
contractsAllowed contract addresses["0x7a25...", "0x1f98..."]
protocolsAllowed protocol names["uniswap", "aave"]
categoriesAllowed protocol categories["DEX", "LENDING", "BRIDGE"]
functionsAllowed 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 TypeDescriptionValue Format
X402_MAX_PER_REQUESTMaximum amount per x402 request{"maxAmount": N}
X402_PRICE_CEILINGPrice ceiling for any x402 payment{"maxPrice": N}
X402_MAX_PER_ENDPOINTLimit per API endpoint{"maxAmount": N, "maxCalls": N, "period": "DAILY"}
X402_MAX_PER_SERVICELimit per service domain{"maxAmount": N, "maxCalls": N, "period": "DAILY"}
X402_ALLOWED_SERVICESAllowlist of service domains["api.example.com", "data.service.io"]
X402_BLOCKED_SERVICESBlocklist of service domains["malicious.site"]
X402_ALLOWED_FACILITATORSAllowed x402 facilitator addresses["0x..."]
X402_VELOCITY_PER_ENDPOINTRate limit per endpoint{"maxCalls": N, "period": "HOUR"}
X402_SESSION_BUDGETSession-level spending budget{"maxAmount": N}

​
MPP Protocol Rules

These rules govern Machine Payment Protocol (MPP) session-based micropayments:
Rule TypeDescriptionValue Format
MPP_MAX_PER_REQUESTMaximum per MPP credential charge{"maxAmount": N}
MPP_PRICE_CEILINGPrice ceiling for MPP payments{"maxPrice": N}
MPP_MAX_PER_ENDPOINTLimit per MPP resource endpoint{"maxAmount": N, "maxCalls": N}
MPP_MAX_PER_SERVICELimit per MPP service domain{"maxAmount": N, "maxCalls": N, "period": "DAILY"}
MPP_ALLOWED_SERVICESAllowlist of MPP service domains["api.example.com"]
MPP_BLOCKED_SERVICESBlocklist of MPP service domains["blocked.site"]
MPP_SESSION_BUDGETMaximum deposit per MPP session{"maxDeposit": N}
MPP_MAX_SESSION_DEPOSITHard cap on session deposit amount{"maxDeposit": N}
MPP_MAX_CONCURRENT_SESSIONSMax active sessions per agent{"maxSessions": N}
MPP_MAX_SESSION_DURATIONMaximum session duration{"maxDurationMs": N}
MPP_BLOCK_SESSION_INTENTBlock specific session intents["streaming"]
MPP_ALLOWED_METHODSAllowed HTTP methods for MPP["GET", "POST"]
MPP_VELOCITY_PER_ENDPOINTRate limit per MPP endpoint{"maxCalls": N, "period": "HOUR"}

​
Card Payment Rules

These rules govern card-based payments (Lithic virtual/physical cards):
Rule TypeDescriptionValue Format
CARD_MAX_AMOUNTMaximum per card transaction"500"
CARD_ALLOWED_MCCSAllowed merchant category codes["5411", "5812"]
CARD_BLOCKED_MCCSBlocked merchant category codes["7995"]
CARD_ALLOWED_MERCHANTSAllowed merchant names["Amazon", "Stripe"]
CARD_BLOCKED_MERCHANTSBlocked 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"] }
    ]
  }'