Time Window Policies

Time window policies restrict when transactions can occur based on hours and days. Policy rules can set an IANA timezone in their values; rules without one retain the legacy server-local behavior. Wallet-level time windows are evaluated in the agent-wallet link’s configurable IANA timezone, which defaults to UTC.

Configuration (API)

Create a complete TIME_WINDOW policy with its rules in one request:

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours",
    "policyType": "TIME_WINDOW",
    "priority": 50,
    "isActive": true,
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"17:00\", \"timezone\": \"America/New_York\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN_LIST",
        "value": "{\"days\": [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"], \"timezone\": \"America/New_York\"}",
        "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", "timezone": "Area/Location"}`
`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 `days` and optional `timezone`; a plain day array remains supported for legacy server-local rules
`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 \
  -H "Authorization: Bearer $CONTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maintenance Windows",
    "policyType": "BLACKOUT_PERIOD",
    "priority": 50,
    "isActive": true,
    "rules": [{
      "ruleType": "BLACKOUT_PERIOD",
      "operator": "BETWEEN",
      "value": "{\"timezone\": \"America/New_York\", \"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. Hours are whole numbers on a 24-hour clock, with allowedHoursStart inclusive and allowedHoursEnd exclusive: 9–18 allows 09:00 through 17:59 and blocks 18:00 onward. Midnight is hour 0, so 0–24 covers the full day.

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": ["This payment is outside the permitted schedule."]
}

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. Keep the configured timezone visible in your own operational settings so reviewers can interpret schedule-based denials consistently.

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