Machine View
Time Windows
Source: https://conto.finance/docs/policies/time-windows
# Time Windows
> Restrict agent transactions to business hours, specific days, or block during maintenance windows with blackout periods
- Human URL: https://conto.finance/docs/policies/time-windows
- Raw Markdown: https://conto.finance/docs/policies/time-windows.md
- Terminal view: https://conto.finance/ai/docs/policies/time-windows
Documentation group: Products
# 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:
```bash
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:
```bash
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}`):
```json
{
"walletId": "cmm5b2wal002n49h7ckrtb33r",
"allowedHoursStart": 9,
"allowedHoursEnd": 17,
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"timezone": "America/New_York"
}
```
Info:
`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
```json
{
"allowedHoursStart": 9,
"allowedHoursEnd": 18,
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"]
}
```
### Extended Hours
Allow transactions in extended support hours
```json
{
"allowedHoursStart": 7,
"allowedHoursEnd": 22,
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
}
```
### Weekends Only
For agents that operate on weekends
```json
{
"allowedHoursStart": 0,
"allowedHoursEnd": 24,
"allowedDays": ["Sat", "Sun"]
}
```
### 24/7
No time restrictions (allow always)
```json
{
"allowedHoursStart": 0,
"allowedHoursEnd": 24,
"allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
}
```
## Error Response
When a transaction is blocked by time window:
```json
{
"status": "DENIED",
"reasons": ["This payment is outside the permitted schedule."]
}
```
## 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`. Keep the configured timezone visible in your own operational settings
so reviewers can interpret schedule-based denials consistently.
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.
```json
[
{
"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"
}
]
}
]
```