====== Trading Halt Windows ======

A trading halt window halts trading for a firm at a set time and resumes it at a later time. Windows can run once or repeat on a schedule, and can optionally liquidate the firm when the halt starts.


| **Method** | **Path** | **Description** |
| GET | ''/admin/v1/firms/{firmID}/trading-halt-windows'' | List the firm's halt windows. |
| GET | ''/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}'' | Get one halt window. |
| POST | ''/admin/v1/firms/{firmID}/trading-halt-windows'' | Create a halt window. |
| PUT | ''/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}'' | Update a halt window (including enable/disable). |
| DELETE | ''/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}'' | Delete a halt window. |
| GET | ''/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}/executions'' | List the halt and open actions taken for a window. |


[[https://api-sim.t4login.com/admin/swagger/index.html|Admin API Swagger Documentation]]

===== Halt Window Fields =====

| **Field** | **Description** |
| description | Optional. Free text, up to 500 characters. |
| enabled | Optional. Defaults to ''true''. A disabled window keeps its settings but does not run. |
| haltTime | Required. Local time the halt starts, e.g. ''2026-10-05T15:55:00''. No offset or ''Z''. |
| openTime | Required. Local time trading resumes. Must be later than ''haltTime''. |
| liquidateOnHalt | Optional. Defaults to ''false''. When ''true'', all working orders are cancelled and all positions flattened when the halt starts. |
| repeat | Optional. Days to repeat on, as the three cron day fields: ''day-of-month month day-of-week''. Omit for a one-time window. |
| timeZone | Required. IANA time zone that ''haltTime'', ''openTime'' and ''repeat'' are evaluated in, e.g. ''America/Chicago''. |
| notificationUrl | Optional. Your HTTPS webhook, called after each halt and open runs. See [[#notifications|Notifications]]. |


==== One-Time vs Repeating ====

  * **One-time** (no ''repeat''): ''haltTime'' must be in the future.
  * **Repeating**: only the time of day of ''haltTime'' and ''openTime'' is used; the date is the first occurrence. The halt and open must fall on the same calendar day (a repeating window cannot cross midnight).

Common ''repeat'' values:

| **repeat** | **Runs** |
| ''* * *'' | Every day |
| ''* * 1-5'' | Monday to Friday |
| ''* * 0,6'' | Saturday and Sunday |
| ''1 * *'' | The 1st of every month |


===== Create a Halt Window =====

<code>
POST https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows

{
  "description": "Daily close flatten",
  "enabled": true,
  "haltTime": "2026-10-12T15:55:00",
  "openTime": "2026-10-12T17:00:00",
  "liquidateOnHalt": true,
  "repeat": "* * 1-5",
  "timeZone": "America/Chicago",
  "notificationUrl": "https://hooks.example.com/t4/trading-halt"
}
</code>

Returns ''201 Created'' with the new window:

<code>
{
  "data": {
    "tradingHaltTimeWindowId": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a31",
    "firmId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "description": "Daily close flatten",
    "enabled": true,
    "haltTime": "2026-10-12T15:55:00",
    "openTime": "2026-10-12T17:00:00",
    "liquidateOnHalt": true,
    "repeat": "* * 1-5",
    "timeZone": "America/Chicago",
    "notificationUrl": "https://hooks.example.com/t4/trading-halt",
    "nextExecutionTime": "2026-10-12T15:55:00-05:00"
  },
  "metadata": { "timestamp": "2026-10-09T14:00:00Z", "requestId": "..." }
}
</code>

''nextExecutionTime'' is the next scheduled halt or open, in the window's time zone. During an active halt it is the pending open. It is omitted when the window is disabled or a one-time window has already run.

===== List and Get Halt Windows =====

<code>
GET https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows
GET https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}
</code>

The list returns an array of windows in ''data''; get returns a single window. Both use the same format as the create response.

===== Update a Halt Window =====

<code>
PUT https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}
</code>

The body is the same as create and **replaces** the whole window, so send every field. Returns ''200 OK'' with the updated window.

To pause a window, PUT it with ''"enabled": false''. To resume, PUT it with ''"enabled": true''.

<bootnote>
Omitting ''enabled'' on a PUT enables the window, and omitting ''liquidateOnHalt'' turns liquidation off. Always send both to avoid confusion.
</bootnote>

===== Delete a Halt Window =====

<code>
DELETE https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}
</code>

Returns ''204 No Content''. Any future halt and open actions are cancelled.


===== List Executions =====

Returns the halt and open actions taken for a window, newest first.

<code>
GET https://api.t4login.com/admin/v1/firms/{firmID}/trading-halt-windows/{windowID}/executions?sinceDate=2026-10-01&pageSize=100&pageNumber=1
</code>

| **Parameter** | **Description** |
| sinceDate | Optional. Only return actions scheduled on or after this date/time (UTC). |
| pageSize | Optional. 1 to 1000. Defaults to 100. |
| pageNumber | Optional. Starts at 1. Defaults to 1. |

<code>
{
  "data": {
    "items": [
      {
        "tradingHaltTimeWindowId": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a31",
        "description": "Daily close flatten",
        "action": "Open",
        "scheduledTimeUtc": "2026-10-08T22:00:00Z",
        "completedTimeUtc": "2026-10-08T22:00:01Z",
        "status": "Completed"
      },
      {
        "tradingHaltTimeWindowId": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a31",
        "description": "Daily close flatten",
        "action": "Halt",
        "scheduledTimeUtc": "2026-10-08T20:55:00Z",
        "completedTimeUtc": "2026-10-08T20:55:02Z",
        "status": "Completed"
      }
    ],
    "totalCount": 2,
    "pageSize": 100,
    "pageNumber": 1,
    "totalPages": 1
  },
  "metadata": { "timestamp": "2026-10-09T14:00:00Z", "requestId": "..." }
}
</code>

| **Field** | **Description** |
| action | ''Halt'' or ''Open''. |
| scheduledTimeUtc | When the action was scheduled to run (UTC). |
| completedTimeUtc | When the action finished (UTC). Omitted while still executing. |
| status | ''Completed'', ''Failed'', ''Skipped'' (missed and too late to run), or ''Executing''. |
| message | Error or skip reason, when there is one. |


===== Notifications =====

When ''notificationUrl'' is set, T4 sends a ''POST'' with a JSON body to it after every halt and open, whether it succeeded or not. Respond with any ''2xx'' status. Non-''2xx'' responses and timeouts (10 seconds) are retried up to 4 more times with increasing delays.

''jobId'' is the ''tradingHaltTimeWindowId'' of the window that ran. ''taskName'' is ''Halt <firm>'' or ''Open <firm>''.

Success:

<code>
{
  "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "jobId": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a31",
  "taskName": "Halt Acme Trading",
  "executionId": "0b5d3a2e-91f4-4c8a-b6e7-2d4f8a1c9e30",
  "status": "Completed",
  "scheduledTimeUtc": "2026-10-12T20:55:00Z",
  "startedUtc": "2026-10-12T20:55:00.120Z",
  "completedUtc": "2026-10-12T20:55:01.480Z",
  "durationMs": 1360,
  "attempts": 1,
  "httpStatus": 200
}
</code>

Failure:

<code>
{
  "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "jobId": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a31",
  "taskName": "Halt Acme Trading",
  "executionId": "5f1c8e7a-2b3d-4e6f-9a0b-c4d5e6f7a8b9",
  "status": "Failed",
  "scheduledTimeUtc": "2026-10-13T20:55:00Z",
  "startedUtc": "2026-10-13T20:55:00.095Z",
  "completedUtc": "2026-10-13T20:55:42.310Z",
  "durationMs": 42215,
  "attempts": 4,
  "httpStatus": 503,
  "error": "Service Unavailable"
}
</code>

| **Field** | **Description** |
| jobId | The ''tradingHaltTimeWindowId'' of the window that ran. |
| status | ''Completed'', ''Failed'', or ''Skipped'' (missed and too late to run). |
| attempts | Number of times T4 tried the halt or open. |
| httpStatus | Status of the last attempt to change the firm's trading state. Omitted if no response was received. |
| error | Why the last attempt failed. |
| reason | Why the action was skipped, e.g. ''GraceExpired''. |

===== Errors =====

Validation and other errors return the matching HTTP status with an ''errors'' array. Each error has a ''message'' and the ''target'' field it applies to:

<code>
{
  "errors": [
    { "message": "OpenTime must be later than HaltTime.", "target": "openTime" }
  ],
  "metadata": { "timestamp": "2026-10-09T14:00:00Z", "requestId": "..." }
}
</code>

| **Status** | **Meaning** |
| 400 | Invalid ID or request body. |
| 401 | Not authenticated or not an admin. |
| 404 | Firm or window not found. |
| 503 | The scheduler is temporarily unavailable. Retry later. |