> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Time Windows

> Restrict agent transactions to business hours, specific days, or block during maintenance windows with blackout periods

# 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:

```bash theme={null}
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:

```bash theme={null}
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}`):

```json theme={null}
{
  "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.
</Info>

## Use Cases

<CardGroup cols={2}>
  <Card title="Business Hours">
    Only allow transactions during working hours

    ```json theme={null}
    {
      "allowedHoursStart": 9,
      "allowedHoursEnd": 18,
      "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"]
    }
    ```
  </Card>

  <Card title="Extended Hours">
    Allow transactions in extended support hours

    ```json theme={null}
    {
      "allowedHoursStart": 7,
      "allowedHoursEnd": 22,
      "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
    }
    ```
  </Card>

  <Card title="Weekends Only">
    For agents that operate on weekends

    ```json theme={null}
    {
      "allowedHoursStart": 0,
      "allowedHoursEnd": 24,
      "allowedDays": ["Sat", "Sun"]
    }
    ```
  </Card>

  <Card title="24/7">
    No time restrictions (allow always)

    ```json theme={null}
    {
      "allowedHoursStart": 0,
      "allowedHoursEnd": 24,
      "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
    }
    ```
  </Card>
</CardGroup>

## Error Response

When a transaction is blocked by time window:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Match Business Operations">
    Align time windows with when humans are available to monitor:

    * During work hours: Standard limits
    * After hours: Stricter limits or blocked
  </Accordion>

  <Accordion title="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.

    ```json theme={null}
    [
      {
        "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"
          }
        ]
      }
    ]
    ```
  </Accordion>
</AccordionGroup>