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:

Property	Description
`ruleType`	`TIME_WINDOW`
`operator`	`BETWEEN` (allow within window) or `NOT_BETWEEN` (block within window)
`value`	JSON string: `{"start": "HH:MM", "end": "HH:MM"}`
`action`	`ALLOW` or `DENY`

DAY_OF_WEEK (Days)

Restrict transactions to specific days of the week:

Property	Description
`ruleType`	`DAY_OF_WEEK`
`operator`	`IN_LIST` (allow these days) or `NOT_IN_LIST` (block these days)
`value`	JSON string containing an array: `["Mon", "Tue", "Wed", "Thu", "Fri"]`
`action`	`ALLOW` 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 Wallet Timezone

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.

Match Business Operations

Align time windows with when humans are available to monitor:

During work hours: Standard limits
After hours: Stricter limits or blocked

Combine with Approval Thresholds

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"
      }
    ]
  }
]

Start

Products

Build

Guides

Reference

Changelog

Time Windows

Time Window Policies

Configuration (API)

Rule Types

TIME_WINDOW (Hours)

DAY_OF_WEEK (Days)

BLACKOUT_PERIOD

Wallet-Level Time Windows

Use Cases

Business Hours

Extended Hours

Weekends Only

24/7

Error Response

Best Practices

​Time Window Policies

​Configuration (API)

​Rule Types

​TIME_WINDOW (Hours)

​DAY_OF_WEEK (Days)

​BLACKOUT_PERIOD

​Wallet-Level Time Windows

​Use Cases

Business Hours

Extended Hours

Weekends Only

24/7

​Error Response

​Best Practices

Time Window Policies

Configuration (API)

Rule Types

TIME_WINDOW (Hours)

DAY_OF_WEEK (Days)

BLACKOUT_PERIOD

Wallet-Level Time Windows

Use Cases

Error Response

Best Practices