Skip to main content

​
Time Window Policies

Time window policies restrict when transactions can occur based on hours and days. Policy-rule time windows use the server’s local time. Wallet-level time windows are evaluated in the agent-wallet link’s configurable IANA timezone, which defaults to UTC.

​
Configuration (API)

Create rules via the Policy Rules API: 
curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"17:00\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN_LIST",
        "value": "[\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"]",
        "action": "ALLOW"
      }
    ]
  }'

​
Rule Types

​
TIME_WINDOW (Hours)

Restrict transactions to specific hours of the day:
PropertyDescription
ruleTypeTIME_WINDOW
operatorBETWEEN (allow within window) or NOT_BETWEEN (block within window)
valueJSON string: {"start": "HH:MM", "end": "HH:MM"}
actionALLOW or DENY

​
DAY_OF_WEEK (Days)

Restrict transactions to specific days of the week:
PropertyDescription
ruleTypeDAY_OF_WEEK
operatorIN_LIST (allow these days) or NOT_IN_LIST (block these days)
valueJSON string containing an array: ["Mon", "Tue", "Wed", "Thu", "Fri"]
actionALLOW or DENY
Valid day values: Mon, Tue, Wed, Thu, Fri, Sat, Sun

​
BLACKOUT_PERIOD

Block transactions during maintenance windows or holidays: 
curl -X POST https://conto.finance/api/policies/{policyId}/rules \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -d '{
    "rules": [{
      "ruleType": "BLACKOUT_PERIOD",
      "operator": "BETWEEN",
      "value": "{\"windows\": [{\"start\": \"02:00\", \"end\": \"06:00\", \"reason\": \"Maintenance\", \"recurring\": true}]}",
      "action": "DENY"
    }]
  }'

​
Wallet-Level Time Windows

Time windows can also be set on the agent-wallet link (POST /api/agents/{id}/wallets or PATCH /api/agents/{id}/wallets/{walletId}): 
{
  "walletId": "cmm5b2wal002n49h7ckrtb33r",
  "allowedHoursStart": 9,
  "allowedHoursEnd": 17,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "timezone": "America/New_York"
}
allowedHoursStart/allowedHoursEnd and allowedDays are evaluated in the link’s IANA timezone, which defaults to UTC. The timezone field can be set when linking the wallet (POST /api/agents/{id}/wallets) and changed later on the update endpoint (PATCH /api/agents/{id}/wallets/{walletId}); invalid IANA names are rejected with a 400.

​
Use Cases

Business Hours

Only allow transactions during working hours
{
  "allowedHoursStart": 9,
  "allowedHoursEnd": 18,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"]
}

Extended Hours

Allow transactions in extended support hours
{
  "allowedHoursStart": 7,
  "allowedHoursEnd": 22,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
}

Weekends Only

For agents that operate on weekends
{
  "allowedHoursStart": 0,
  "allowedHoursEnd": 24,
  "allowedDays": ["Sat", "Sun"]
}

24/7

No time restrictions (allow always)
{
  "allowedHoursStart": 0,
  "allowedHoursEnd": 24,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
}

​
Error Response

When a transaction is blocked by time window: 
{
  "status": "DENIED",
  "reasons": ["Transaction outside allowed hours"],
  "violations": [
    {
      "type": "TIME_WINDOW",
      "limit": 0,
      "current": 0,
      "message": "Transactions not allowed at 22:00 (America/New_York). Allowed hours: 9:00 - 17:00",
      "source": "wallet_limit"
    }
  ]
}

​
Best Practices

Set the link’s timezone to your organization’s operating timezone (for example, America/New_York) instead of converting hours to UTC by hand. With the timezone set, allowedHoursStart/allowedHoursEnd read as local business hours, daylight saving time is handled for you, and allowedDays matches the local calendar day. If you leave it unset, the link defaults to UTC. Time window violations include the evaluated timezone in the error message.
Align time windows with when humans are available to monitor:
  • During work hours: Standard limits
  • After hours: Stricter limits or blocked
Allow small transactions any time, but require approval after hours by assigning two policies to the agent. Conto evaluates them with AND logic.
[
  {
    "name": "Business hours",
    "policyType": "TIME_WINDOW",
    "priority": 50,
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"17:00\"}",
        "action": "ALLOW"
      }
    ]
  },
  {
    "name": "After-hours approval",
    "policyType": "APPROVAL_THRESHOLD",
    "priority": 40,
    "rules": [
      {
        "ruleType": "REQUIRE_APPROVAL_ABOVE",
        "operator": "GREATER_THAN",
        "value": "50",
        "action": "REQUIRE_APPROVAL"
      }
    ]
  }
]