Policies API

Manage spending policies and rules.

List Policies

curl https://www.conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_API_KEY"

Response

{
  "policies": [
    {
      "id": "cmm...",
      "name": "Standard Spend Limits",
      "description": "Default spend limits for agents",
      "policyType": "SPEND_LIMIT",
      "priority": 50,
      "isActive": true,
      "rules": [
        {
          "id": "cmm...",
          "ruleType": "MAX_AMOUNT",
          "operator": "LTE",
          "value": "500",
          "action": "ALLOW"
        }
      ],
      "agentPolicies": [
        {
          "id": "...",
          "agent": { "id": "...", "name": "Operations Agent" }
        }
      ]
    }
  ]
}

Get Policy

curl https://www.conto.finance/api/policies/{policyId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Create Policy

curl -X POST https://www.conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Policy",
    "description": "Policy for high-value transactions",
    "policyType": "SPEND_LIMIT",
    "priority": 50,
    "isActive": true
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Policy name
`description`	string	No	Policy description
`policyType`	enum	Yes	Policy type (see below)
`priority`	number	No	Evaluation priority (0-100, higher = first)
`isActive`	boolean	No	Active state (default: true)

Policy Types

Type	Description
`SPEND_LIMIT`	Amount-based restrictions
`TIME_WINDOW`	Hour/day restrictions
`MERCHANT`	Merchant allowlist/blocklist
`CATEGORY`	Category restrictions
`VELOCITY`	Transaction frequency limits
`GEOGRAPHIC`	Region/country restrictions
`APPROVAL_THRESHOLD`	Require human approval above amount
`COUNTERPARTY`	Approved vendor lists
`BUDGET_ALLOCATION`	Department/project budgets
`WHITELIST`	Approved address lists
`EXPIRATION`	Time-limited permissions
`COMPOSITE`	Multiple rules combined
`CONTRACT_ALLOWLIST`	Allowed smart contracts
`BLACKOUT_PERIOD`	Block during maintenance windows

Add Rules to Policy

Rules define the specific conditions for a policy. Each rule has a ruleType, operator, value, and action.

curl -X POST https://www.conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "ruleType": "MAX_AMOUNT",
        "operator": "LTE",
        "value": "500",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAILY_LIMIT",
        "operator": "LTE",
        "value": "2000",
        "action": "ALLOW"
      }
    ]
  }'

Rule Types

Rule Type	Description	Example Value
`MAX_AMOUNT`	Per-transaction amount limit	`"500"`
`DAILY_LIMIT`	Daily cumulative spend	`"2000"`
`WEEKLY_LIMIT`	Weekly cumulative spend	`"10000"`
`MONTHLY_LIMIT`	Monthly cumulative spend	`"50000"`
`BUDGET_CAP`	Budget with period	`"{\"amount\": 10000, \"period\": \"MONTHLY\"}"`
`TIME_WINDOW`	Allowed hours (HH:MM)	`"{\"start\": \"09:00\", \"end\": \"17:00\"}"`
`DAY_OF_WEEK`	Allowed days	`"[\"Mon\",\"Tue\",\"Wed\",\"Thu\",\"Fri\"]"`
`DATE_RANGE`	Valid date range	`"{\"start\": \"2024-01-01\", \"end\": \"2024-12-31\"}"`
`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	`"[\"0x1234...\", \"0x5678...\"]"`
`BLOCKED_COUNTERPARTIES`	Blocked addresses	`"[\"0xdead...\"]"`
`VELOCITY_LIMIT`	Transaction frequency	`"{\"maxCount\": 10, \"period\": \"HOUR\"}"`
`REQUIRE_APPROVAL_ABOVE`	Approval threshold	`"2500"`
`GEOGRAPHIC_RESTRICTION`	Blocked countries	`"[\"IR\", \"KP\", \"RU\"]"`
`TRUST_SCORE`	Min trust score	`"70"`
`CONTRACT_ALLOWLIST`	Allowed contracts	`"{\"contracts\": [\"0x...\"]}"`

Operators

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

Actions

Action	Description
`ALLOW`	Allow if condition passes, deny if it fails
`DENY`	Deny if condition matches
`REQUIRE_APPROVAL`	Require human approval if condition matches

Assign Policy to Agent

curl -X POST https://www.conto.finance/api/agents/{agentId}/policies \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policyId": "cmm..."}'

Multi-policy AND logic: When multiple policies are assigned to an agent, ALL must pass for a payment to be approved. The first DENY stops evaluation immediately.

Remove Policy from Agent

curl -X DELETE "https://www.conto.finance/api/agents/{agentId}/policies?policyId=cmm..." \
  -H "Authorization: Bearer $CONTO_API_KEY"

The policyId is passed as a query parameter, not a path parameter.

Update Policy

curl -X PATCH https://www.conto.finance/api/policies/{policyId} \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Policy Name",
    "priority": 75,
    "isActive": false
  }'

Update Rule

curl -X PATCH https://www.conto.finance/api/policies/{policyId}/rules/{ruleId} \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "7500",
    "action": "REQUIRE_APPROVAL"
  }'

Delete Rule

curl -X DELETE https://www.conto.finance/api/policies/{policyId}/rules/{ruleId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Delete Policy

Deleting a policy removes it from all agents. Consider deactivating instead.

curl -X DELETE https://www.conto.finance/api/policies/{policyId} \
  -H "Authorization: Bearer $CONTO_API_KEY"

Violation Types

When a payment is denied, the response includes violation details:

{
  "status": "DENIED",
  "violations": [
    {
      "type": "DAILY_LIMIT",
      "limit": 1000,
      "current": 1150,
      "message": "Would exceed daily limit: $-150.00 remaining of $1000 daily limit"
    }
  ]
}

Violation Type	Description
`INSUFFICIENT_BALANCE`	Wallet balance too low
`PER_TX_LIMIT`	Per-transaction limit exceeded
`DAILY_LIMIT`	Daily spending limit exceeded
`WEEKLY_LIMIT`	Weekly spending limit exceeded
`MONTHLY_LIMIT`	Monthly spending limit exceeded
`TIME_WINDOW`	Outside allowed hours/days
`BLOCKED_COUNTERPARTY`	Recipient is blocked
`WHITELIST_VIOLATION`	Recipient not in allowed list
`CATEGORY_RESTRICTION`	Category blocked or not allowed
`VELOCITY_LIMIT`	Transaction frequency exceeded
`GEOGRAPHIC_RESTRICTION`	Restricted country
`BUDGET_EXCEEDED`	Budget cap exceeded
`EXPIRED_PERMISSION`	Date range expired
`CONTRACT_NOT_ALLOWED`	Contract not in allowlist
`BLACKOUT_PERIOD`	Blackout/maintenance window

API Reference

​Policies API

​List Policies

​Response

​Get Policy

​Create Policy

​Request Body

​Policy Types

​Add Rules to Policy

​Rule Types

​Operators

​Actions

​Assign Policy to Agent

​Remove Policy from Agent

​Update Policy

​Update Rule

​Delete Rule

​Delete Policy

​Violation Types

Policies API

List Policies

Response

Get Policy

Create Policy

Request Body

Policy Types

Add Rules to Policy

Rule Types

Operators

Actions

Assign Policy to Agent

Remove Policy from Agent

Update Policy

Update Rule

Delete Rule

Delete Policy

Violation Types