Policy rule reference

Rule shape

{
  "ruleType": "MAX_AMOUNT",
  "operator": "LTE",
  "value": "500",
  "action": "ALLOW"
}

Field	Purpose
`ruleType`	What the rule evaluates
`operator`	How the request value is compared
`value`	String value, or JSON encoded object/array
`action`	`ALLOW`, `DENY`, or `REQUIRE_APPROVAL`. Defaults to `ALLOW` when omitted

Operators

Operator	Meaning
`EQUALS`, `NOT_EQUALS`	Exact match or mismatch
`GREATER_THAN`, `GTE`, `LESS_THAN`, `LTE`	Numeric comparison
`IN`, `IN_LIST`, `NOT_IN`, `NOT_IN_LIST`	List membership
`BETWEEN`, `NOT_BETWEEN`	Range comparison

Supported rule types

Category	Rule types
Amount limits	`MAX_AMOUNT`, `DAILY_LIMIT`, `WEEKLY_LIMIT`, `MONTHLY_LIMIT`, `BUDGET_CAP`
Approval	`REQUIRE_APPROVAL_ABOVE`
Time	`TIME_WINDOW`, `DAY_OF_WEEK`, `DATE_RANGE`, `BLACKOUT_PERIOD` (aliases `MAINTENANCE_WINDOW`, `BLOCKED_TIME_WINDOW`)
Category	`ALLOWED_CATEGORIES`, `BLOCKED_CATEGORIES`
Counterparty	`ALLOWED_COUNTERPARTIES`, `BLOCKED_COUNTERPARTIES`, `TRUST_SCORE`, `COUNTERPARTY_STATUS`, `COUNTERPARTY_APPROVAL_STATUS`
Agent identity	`AGENT_ENVIRONMENT`, `AGENT_RISK_TIER`, `AGENT_OWNER_ROLE`, `AGENT_TAG`, `ATTESTATION_LEVEL`
Contract controls	`CONTRACT_ALLOWLIST` (aliases `ALLOWED_CONTRACTS`, `PROTOCOL_ALLOWLIST`)
Velocity	`VELOCITY_LIMIT`
Geographic	`GEOGRAPHIC_RESTRICTION`
x402	`X402_MAX_PER_REQUEST` (alias `X402_PRICE_CEILING`), `X402_ALLOWED_SERVICES`, `X402_BLOCKED_SERVICES`, `X402_ALLOWED_FACILITATORS`, `X402_MAX_PER_SERVICE`, `X402_MAX_PER_ENDPOINT`, `X402_VELOCITY_PER_ENDPOINT`, `X402_SESSION_BUDGET`
MPP	`MPP_MAX_PER_REQUEST` (alias `MPP_PRICE_CEILING`), `MPP_MAX_SESSION_DEPOSIT`, `MPP_SESSION_BUDGET`, `MPP_MAX_CONCURRENT_SESSIONS`, `MPP_MAX_SESSION_DURATION`, `MPP_BLOCK_SESSION_INTENT`, `MPP_ALLOWED_SERVICES`, `MPP_BLOCKED_SERVICES`, `MPP_MAX_PER_SERVICE`, `MPP_MAX_PER_ENDPOINT`, `MPP_VELOCITY_PER_ENDPOINT`
Connected cards	`CARD_ALLOWED_MERCHANT_DOMAINS`, `CARD_BLOCKED_MERCHANT_DOMAINS`

The policy endpoints reject unsupported rule types with a 400. A stored rule whose type the engine does not recognize denies every payment the policy covers.

Rule patterns

Agent identity enforcement

Identity rules limit which agents can pay by environment, risk tier, owner role, required identity tag, and attestation mode. An identity ALLOW rule denies the payment when the agent has no value for the field it checks. DEV and STAGING agents also cannot select mainnet or unclassified wallets, even when one was accidentally assigned. The value is one string or a JSON list. AGENT_ENVIRONMENT accepts DEV, STAGING, and PROD. This rule lets only production agents pay:

{
  "ruleType": "AGENT_ENVIRONMENT",
  "operator": "IN_LIST",
  "value": "[\"PROD\"]",
  "action": "ALLOW"
}

Require review above a threshold

{
  "name": "Approval Over 500",
  "policyType": "APPROVAL_THRESHOLD",
  "rules": [
    {
      "ruleType": "REQUIRE_APPROVAL_ABOVE",
      "operator": "GREATER_THAN",
      "value": "500",
      "action": "REQUIRE_APPROVAL"
    }
  ]
}

A policy decision that requires approval always creates a request in Alerts & Approvals. If no custom workflow matches, one review from an organization Owner, Admin, or Manager is required, and the initiator cannot approve their own held payment. A final approval automatically submits the payment for Conto-managed wallets and links the chain receipt from the approval review. External and smart-contract wallets keep their manual execution requirements. An external wallet payment is reserved against spend limits at the final approval and must be confirmed within 24 hours. A final decision sends an approval.approved or approval.denied event to your organization webhook for your own audit trail. See Webhooks.

Request a scoped policy change

An agent with an admin SDK key can request a specific policy change without editing the policy directly. Use POST /api/sdk/policies/exceptions with the policies:exceptions scope, then use GET /api/sdk/policies/exceptions to track it.

curl -X POST https://conto.finance/api/sdk/policies/exceptions \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "spend_limit",
    "reason": "The annual vendor renewal is due this week.",
    "priority": "high",
    "details": {
      "policyId": "policy_123",
      "requestedLimit": 750,
      "amount": 600
    }
  }'

The response:

{
  "id": "exception_123",
  "exceptionId": "exception_123",
  "type": "INCREASE_SPEND_LIMIT",
  "normalizedType": "spend_limit",
  "title": "Spending limit request",
  "reason": "The annual vendor renewal is due this week.",
  "priority": "high",
  "severity": "HIGH",
  "status": "PENDING",
  "normalizedStatus": "pending",
  "statusLabel": "Pending review",
  "reviewUrl": "/alerts"
}

normalizedStatus is pending, in_review, resolved, or dismissed. Creating a request does not change a policy. Review it in Alerts & Approvals.

Limit transaction velocity

Set exactly one of maxCount or maxAmount. Supported periods are HOUR, DAY, WEEK, and MONTH. HOUR and DAY use rolling one-hour and 24-hour history. Weekly and monthly counts use UTC calendar periods. Weekly and monthly amount limits use the matching cumulative spend counters.

{
  "name": "Hourly Velocity Limit",
  "policyType": "VELOCITY",
  "rules": [
    {
      "ruleType": "VELOCITY_LIMIT",
      "operator": "LTE",
      "value": "{\"maxCount\": 10, \"period\": \"HOUR\"}",
      "action": "ALLOW"
    }
  ]
}

For an amount-based rate limit, use the same rule with maxAmount:

{
  "ruleType": "VELOCITY_LIMIT",
  "operator": "LTE",
  "value": "{\"maxAmount\": 300, \"period\": \"HOUR\"}",
  "action": "ALLOW"
}

Count-based velocity accepts an optional scope. The default WALLET counts every transaction in the window. RECIPIENT counts only transactions to the current recipient address, which limits rapid repeated payments to one counterparty without counting unrelated activity. RECIPIENT works with maxCount only. A maxAmount rule with RECIPIENT denies every payment.

{
  "ruleType": "VELOCITY_LIMIT",
  "operator": "LTE",
  "value": "{\"maxCount\": 5, \"period\": \"HOUR\", \"scope\": \"RECIPIENT\"}",
  "action": "ALLOW"
}

Wallet velocity includes pending, confirming, and confirmed transactions, plus managed payments being executed and external-wallet approvals that are not confirmed and not expired. A policy assigned to the agent or the organization counts the agent’s activity across all of its wallets. A policy assigned only to a wallet counts the agent’s activity through that wallet. Card velocity includes recorded card transactions plus approved, executing, and confirming reservations. An issued connected-card credential counts until its outcome is known. Once a person confirms it was not used, it stops counting, and a smaller confirmed charge counts at that amount. An agent’s own report changes neither. A test card’s credential that expires unused keeps counting. A policy assigned to the agent or the organization counts the agent’s activity across all of its cards, and a policy linked to a card counts every agent’s activity on that card. Missing history, unsupported periods, and malformed velocity configuration deny the payment rather than defaulting the prior count or spend to zero. Velocity also counts checkout checkpoint purchases while their spend is held and after they are paid. Cancelled, rejected, expired, and not-paid purchases stop counting. A policy assigned to the agent or the organization counts the agent’s checkout purchases. With RECIPIENT scope, a checkout’s recipient is the registrable domain of its checkout URL, so the rule limits purchases at one store. See checkout purchases.

Restrict by category

Category rules read the category the agent sends. Both ALLOWED_CATEGORIES and BLOCKED_CATEGORIES deny a payment with no category, so always send category when you use them. The value is a JSON list of categories. {"categories": [...]} is also accepted. The API rejects any other shape and an empty list. On a card payment the category is the merchant category code (MCC), such as 5411. A category rule can list the code or one of the categories the dashboard offers, such as Retail or Entertainment. Conto files each MCC under one of those categories by the standard MCC ranges, and a code outside them is Other. A card payment with no MCC is denied while a category rule applies to it.

{
  "name": "Approved Categories",
  "policyType": "CATEGORY",
  "rules": [
    {
      "ruleType": "ALLOWED_CATEGORIES",
      "operator": "IN_LIST",
      "value": "[\"INFRASTRUCTURE\", \"API_PROVIDER\", \"MARKETING\"]",
      "action": "ALLOW"
    }
  ]
}

Relationship-scoped payee controls

Use relationship controls when two agents need different limits for the same counterparty. Set them on the counterparty detail page:

Control	Behavior
Per-payment limit	Denies a payment above the relationship limit
Daily/monthly limits	Denies aggregate spend above the configured period limit
Require approval	Routes every matching payment to review
Allowed categories	Denies missing or non-allowed payment categories
Expiry	Returns the relationship to review after the configured timestamp

These controls add to global counterparty lifecycle gating, organization baselines, and assigned wallet or agent policies. Moving a counterparty to APPROVED or TRUSTED does not weaken a relationship-level approval requirement. For production agents, the first payment attempt to an unknown address creates a DISCOVERED counterparty and relationship before evaluation. This applies to managed payments (/api/sdk/payments/request) and self-custody approvals (/api/sdk/payments/approve). The payment is routed to review until an operator advances the counterparty lifecycle. The agent sees the reason This payee needs review before payments to it can proceed automatically., and /api/sdk/payments/approve returns the reason code PAYEE_REVIEW_REQUIRED. If Conto cannot persist that review record, the request fails closed with COUNTERPARTY_REVIEW_UNAVAILABLE. Development and staging agents are not held for payee discovery. A payee they pay still appears as DISCOVERED in the dashboard for review, and moving it to PENDING_REVIEW, MONITORED, QUARANTINED, or BLOCKED applies to every agent. Review routing never overrides a hard denial. Spend limits, allowlists, sanctions rules, and other deny controls must leave an eligible wallet before counterparty or relationship approval can apply.

Geographic restrictions (OFAC)

The rule reads context.recipientCountry from the payment request. A DENY list is skipped when the agent leaves it out. Conto already blocks OFAC-sanctioned countries, including CU, IR, KP, SY, and RU, whenever the country is sent. On a card payment Conto checks the merchant’s country the same way. For a closed list, use ALLOW with the countries you permit, which also denies payments that carry no country. Address sanctions screening applies to every payment, with or without a geographic rule.

{
  "ruleType": "GEOGRAPHIC_RESTRICTION",
  "operator": "IN_LIST",
  "value": "[\"US\", \"CA\", \"GB\"]",
  "action": "ALLOW"
}

Contract allowlist

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

Include targetContractAddress in the payment request. An ALLOW contract rule denies any payment without it, including plain transfers and external-wallet approvals, so assign it only to agents that call contracts. A DENY or REQUIRE_APPROVAL contract rule applies only to payments that include targetContractAddress. If a rule uses protocol names or categories, register the organization’s known contract classifications through the authenticated contract registry:

GET /api/contract-registry lists entries and supports category, limit, and offset
POST /api/contract-registry saves an address with optional chainId, label, protocolName, and protocolCategory
GET, PATCH, or DELETE /api/contract-registry/{address} reads, updates, or removes one entry

The address is the stable entry identifier. Registry responses return the customer-managed classification fields for that address. Registry changes require policy write permission and are recorded in the organization’s audit history.

x402 protocol rules

The dashboard exposes guided X402_SPEND_LIMIT, X402_SERVICE_CONTROL, and X402_ENDPOINT_CONTROL policy types. The API also accepts those policy types directly. Use COMPOSITE only when one policy deliberately mixes categories.

Rule type	Value
`X402_MAX_PER_REQUEST`, `X402_PRICE_CEILING`, `X402_SESSION_BUDGET`	An amount string, such as `"0.10"`
`X402_ALLOWED_SERVICES`, `X402_BLOCKED_SERVICES`	A JSON array of domains, such as `["api.example.com"]`
`X402_ALLOWED_FACILITATORS`	A JSON array of facilitators
`X402_MAX_PER_ENDPOINT`, `X402_MAX_PER_SERVICE`	`{"maxAmount": 5}`, `{"maxCalls": 100}`, or both, counted over a rolling 24 hours
`X402_VELOCITY_PER_ENDPOINT`	`{"maxCalls": 10, "period": "MINUTE"}`, with `MINUTE`, `HOUR`, or `DAY`

The MPP rules use the same shapes. MPP_MAX_SESSION_DEPOSIT, MPP_MAX_CONCURRENT_SESSIONS, and MPP_MAX_SESSION_DURATION (in hours) take a number. MPP_MAX_CONCURRENT_SESSIONS counts a session from its approved pre-authorize until it is closed or its lifetime passes.

Protocol rules apply to every wallet, x402, and MPP payment made by the agents a policy covers, not only x402 or MPP payments. X402_MAX_PER_REQUEST caps each of those payment amounts, and allowlist rules such as X402_ALLOWED_SERVICES deny payments that carry no x402 service context. They do not apply to card payments. Assign protocol policies to a dedicated API-spend agent with "scope": "assigned" and agentIds. A policy created without scope or agentIds applies to the whole organization.

{
  "name": "x402 API Guardrails",
  "policyType": "COMPOSITE",
  "scope": "assigned",
  "agentIds": ["cmm59z8k40001abcd1234efgh"],
  "rules": [
    {
      "ruleType": "X402_MAX_PER_REQUEST",
      "operator": "LTE",
      "value": "0.10",
      "action": "ALLOW"
    },
    {
      "ruleType": "X402_ALLOWED_SERVICES",
      "operator": "IN_LIST",
      "value": "[\"api.example.com\", \"data.provider.io\"]",
      "action": "ALLOW"
    }
  ]
}

MPP protocol rules

The dashboard exposes guided MPP_SPEND_LIMIT, MPP_SERVICE_CONTROL, MPP_ENDPOINT_CONTROL, and MPP_SESSION_LIFECYCLE policy types. Session-lifecycle rules are evaluated only for session intent, and expired sessions do not count toward concurrency.

{
  "name": "MPP Session Guardrails",
  "policyType": "COMPOSITE",
  "scope": "assigned",
  "agentIds": ["cmm59z8k40001abcd1234efgh"],
  "rules": [
    {
      "ruleType": "MPP_MAX_SESSION_DEPOSIT",
      "operator": "LTE",
      "value": "25",
      "action": "ALLOW"
    },
    {
      "ruleType": "MPP_MAX_CONCURRENT_SESSIONS",
      "operator": "LTE",
      "value": "3",
      "action": "ALLOW"
    }
  ]
}

Connected-card store rules

Store rules name a store by the domain its checkout runs on. They apply when an agent requests a connected-card credential and to checkout purchases. For a card, Conto reads the domain from the checkout origin on the authorization the cardholder verified, so the agent cannot change it. For a checkout, Conto reads it from the checkout URL, not from the merchant id the agent sends.

{
  "name": "Approved stores",
  "policyType": "MERCHANT",
  "rules": [
    {
      "ruleType": "CARD_ALLOWED_MERCHANT_DOMAINS",
      "operator": "IN_LIST",
      "value": "[\"example.com\", \"shop.example.org\"]",
      "action": "ALLOW"
    }
  ]
}

Goal	Rule type	Operator	Action
Allow only the listed stores	`CARD_ALLOWED_MERCHANT_DOMAINS`	`IN_LIST`	`ALLOW`
Send every other store to review	`CARD_ALLOWED_MERCHANT_DOMAINS`	`NOT_IN_LIST`	`REQUIRE_APPROVAL`
Deny every other store	`CARD_ALLOWED_MERCHANT_DOMAINS`	`NOT_IN_LIST`	`DENY`
Block the listed stores	`CARD_BLOCKED_MERCHANT_DOMAINS`	`IN_LIST`	`DENY`
Send the listed stores to review	`CARD_BLOCKED_MERCHANT_DOMAINS`	`IN_LIST`	`REQUIRE_APPROVAL`

An entry covers its own domain and every subdomain. example.com covers checkout.example.com. A leading www. is ignored.
A list holds 1 to 100 domains. The policy endpoints reject any other operator and action pairing.
A card payment or checkout with no checkout domain is denied while a store rule applies to it.
An ALLOW store rule also denies that agent’s wallet, x402, and MPP payments, because they carry no store domain. For an agent that pays on more than one rail, use NOT_IN_LIST with DENY. That form leaves other rails alone.

Store rules match a checkout by the host of its checkout URL, the same way they match a card payment. Under the approved stores policy above, a checkout at shop.example.com is allowed, and a checkout at a store the list does not name is denied. See checkout purchases.

Budget allocations

Use BUDGET_CAP when a wallet or agent needs a bounded allowance for a period, project, or category. Supported periods are DAILY, WEEKLY, MONTHLY, QUARTERLY, and YEARLY. Period boundaries are calculated in UTC.

{
  "ruleType": "BUDGET_CAP",
  "operator": "LTE",
  "value": "{\"amount\": 2500, \"period\": \"MONTHLY\", \"category\": \"INFRASTRUCTURE\"}",
  "action": "ALLOW"
}

Add department, project, or category to the rule value to scope the cap. Conto compares only transactions recorded with the same dimensions and includes pending, confirming, and confirmed spend. The request must pass the matching scope through context.department and context.project. category must match the payment’s category exactly, including case. A payment with a different or missing category is neither counted nor capped by that budget. A budget without a department or project also counts managed payments being executed, external-wallet approvals that are not confirmed and not expired, and checkout checkpoint purchases while their spend is held and after they are paid, matched by category. A budget on a policy assigned to the agent or the organization counts the agent’s spend across all of its wallets. A policy assigned only to a wallet counts the agent’s spend through that wallet. On cards, the same budget counts the agent’s spend across all of its cards, and a budget on a policy linked to a card counts that card’s spend. On cards, a QUARTERLY or YEARLY budget counts the card purchases made in the period, including issued credentials and purchases that are approved but not yet charged. These budget histories remain separate for wallet and card payments. To set a daily, weekly, or monthly cap across an agent’s wallets and live cards together, use DAILY_LIMIT, WEEKLY_LIMIT, or MONTHLY_LIMIT at agent or organization scope. Those rules use combined period counters. Scoped BUDGET_CAP and velocity rules keep their own transaction histories. See Spend limits.

Expiration policies

Use DATE_RANGE for temporary permissions and BLACKOUT_PERIOD for known no-spend windows. An ALLOW date range denies every payment outside the range. It does not switch the policy off when the range ends. BLACKOUT_PERIOD values list their windows under windows. The policy endpoints return 400 for time, date, blackout, and geographic values in a shape the engine cannot read.

{
  "ruleType": "DATE_RANGE",
  "operator": "BETWEEN",
  "value": "{\"start\": \"2026-10-01T00:00:00Z\", \"end\": \"2026-12-31T23:59:59Z\"}",
  "action": "ALLOW"
}

Time rules accept an IANA timezone. See Time Windows.

Trust scoring

How payee trust scores are calculated, plus sanctions screening and wallet reputation

Recipes

Copy-paste policy setup snippets

API

SDK and tools

Policy rules

Policy rule reference

Rule shape

Operators

Supported rule types

Rule patterns

Agent identity enforcement

Require review above a threshold

Request a scoped policy change

Limit transaction velocity

Restrict by category

Relationship-scoped payee controls

Geographic restrictions (OFAC)

Contract allowlist

x402 protocol rules

MPP protocol rules

Connected-card store rules

Budget allocations

Expiration policies

Trust scoring

Recipes

​Rule shape

​Operators

​Supported rule types

​Rule patterns

​Agent identity enforcement

​Require review above a threshold

​Request a scoped policy change

​Limit transaction velocity

​Restrict by category

​Relationship-scoped payee controls

​Geographic restrictions (OFAC)

​Contract allowlist

​x402 protocol rules

​MPP protocol rules

​Connected-card store rules

​Budget allocations

​Expiration policies

​Related

Trust scoring

Recipes

Rule shape

Operators

Supported rule types

Rule patterns

Agent identity enforcement

Require review above a threshold

Request a scoped policy change

Limit transaction velocity

Restrict by category

Relationship-scoped payee controls

Geographic restrictions (OFAC)

Contract allowlist

x402 protocol rules

MPP protocol rules

Connected-card store rules

Budget allocations

Expiration policies

Related