# Kill switch Source: https://docs.pipsocket.com/api/kill-switch Block new exposure and flatten the account. All calls: `https://api.pipsocket.com`, with `Authorization: Bearer `. ## Get the kill switch `GET /v1/accounts/{account}/kill-switch` Whether the account's kill switch is engaged. ### Path - `account` (string, required): The account's id, `acc_` and 26 characters, as the dashboard shows it. ### Response - `engaged` (boolean): - `since` (integer, or null): When it was engaged: seconds since 1970 (UTC). Null when it is not engaged. - `deviation` (integer, or null): The deviation, in points, its closing deals carry. Null when it is not engaged. ### Answers - 200: The kill switch. - 401: - `missing_api_key`: No API key: send it as `Authorization: Bearer `.; `invalid_api_key`: The key is not a workspace's current key (a rolled key stops working within about a minute). - 404: - `no_such_account`: No such account, or one the key's workspace doesn't have: the two look the same. - 503: - `engine_busy`: The account's engine host has too many calls in flight (256). Nothing was done; try again.; `engine_unavailable`: The account's engine host is not connected to Pipsocket, or disconnected while the call waited. A trade it already had is still settled: look it up. - 504: - `engine_timeout`: The account's engine did not answer within 30 seconds. ### Example ```bash curl "https://api.pipsocket.com/v1/accounts/acc_01m6tx3k9f2qw8r7bznd5yvh4c/kill-switch" \ -H "Authorization: Bearer $PIPSOCKET_KEY" ``` 200 engaged: ```json { "deviation": 20, "engaged": true, "since": 1794064225 } ``` 200 lifted: ```json { "deviation": null, "engaged": false, "since": null } ``` ## Engage the kill switch `POST /v1/accounts/{account}/kill-switch` Blocks new exposure first (new orders and changes to pending orders are refused with 423 until it is lifted; the block survives restarts), then deletes every pending order and closes every position, each as one request sent once. It first waits up to 6 seconds for trades still being sent. Engaging it again retries whatever is left. Closing, close by, cancelling and setting stops still work while it is engaged. ### Path - `account` (string, required): The account's id, `acc_` and 26 characters, as the dashboard shows it. ### Body Engaging the kill switch may carry the deviation (in points) for its closing deals, which brokers with instant or request execution need; MT5's empty value, 0, otherwise. - `deviation` (integer, optional, MT5 `deviation`): The largest difference from the current price the closing deals accept, in points, for instant or request execution. 0 if left out. ### Response - `flat` (boolean): No positions or pending orders in a fresh read of the account, and no trade that could add exposure without a known outcome (`unknown` included). - `cancelled` (object[]): Each pending order and the removal sent for it (or the one already waiting for its answer). - `closed` (object[]): Each position and the close sent for it (or the one already waiting for its answer). - `remaining` (object, or null): What a fresh read found afterwards; null if the terminal did not answer it. - `positions` (integer): - `orders` (integer): - `unanswered` (string[]): Ids of requests sent before the switch engaged that could add exposure and have no known outcome. If one fills and the terminal reports it, the switch closes what it opened. - `kill_switch` (object): Whether the account's kill switch is engaged. - `engaged` (boolean): - `since` (integer, or null): When it was engaged: seconds since 1970 (UTC). Null when it is not engaged. - `deviation` (integer, or null): The deviation, in points, its closing deals carry. Null when it is not engaged. - `message` (string): What the outcome means, in a sentence. ### Answers - 200: The switch is engaged; each request it sent, with MT5's answer, and whether the account is now flat. - 401: - `missing_api_key`: No API key: send it as `Authorization: Bearer `.; `invalid_api_key`: The key is not a workspace's current key (a rolled key stops working within about a minute). - 404: - `no_such_account`: No such account, or one the key's workspace doesn't have: the two look the same. - 422: - `invalid_request`: A field, query parameter or header is missing, malformed or not allowed, or the body is not JSON. Nothing was sent. - 503: - `account_not_connected`, with `kill_switch`: the switch is engaged (and stays engaged), but the terminal stopped answering: no position was closed, though pending orders may already have been deleted. Engage it again once the terminal is connected; a sweep also runs when it reconnects.; `engine_busy`: The account's engine host has too many calls in flight (256). Nothing was done; try again.; `engine_unavailable`: The account's engine host is not connected to Pipsocket, or disconnected while the call waited. A trade it already had is still settled: look it up. - 504: - `engine_timeout`: The account's engine did not answer within 30 seconds. ### Example ```bash curl -X POST "https://api.pipsocket.com/v1/accounts/acc_01m6tx3k9f2qw8r7bznd5yvh4c/kill-switch" \ -H "Authorization: Bearer $PIPSOCKET_KEY" \ -H "Content-Type: application/json" \ -d '{ "deviation": 20 }' ``` 200 flat: ```json { "cancelled": [], "closed": [ { "position": 881402311, "request": { "message": "The request was completed.", "request": "req_9b1e4d7c2a5f8e0b3d6a9c12", "result": { "ask": 1.08412, "bid": 1.0841, "comment": "Request executed", "deal": 771203498, "order": 881402390, "position": 0, "price": 1.0841, "retcode": 10009, "retcode_external": 0, "retcode_name": "TRADE_RETCODE_DONE", "volume": 0.1 }, "sent": { "action": "deal", "comment": "kill switch", "deviation": 20, "expiration": 0, "magic": 0, "order": 0, "position": 881402311, "position_by": 0, "price": 1.0841, "sl": 0, "stoplimit": 0, "symbol": "EURUSD", "tp": 0, "type": "sell", "type_filling": "ioc", "type_time": "gtc", "volume": 0.1 }, "state": "done" } } ], "flat": true, "kill_switch": { "deviation": 20, "engaged": true, "since": 1794064225 }, "message": "The kill switch is engaged and the account has no positions or pending orders.", "remaining": { "orders": 0, "positions": 0 }, "unanswered": [] } ``` ## Lift the kill switch `DELETE /v1/accounts/{account}/kill-switch` Lifts the account's kill switch: new orders and changes to pending orders are accepted again. Lifting a switch that is not engaged changes nothing. ### Path - `account` (string, required): The account's id, `acc_` and 26 characters, as the dashboard shows it. ### Response - `engaged` (boolean): - `since` (integer, or null): When it was engaged: seconds since 1970 (UTC). Null when it is not engaged. - `deviation` (integer, or null): The deviation, in points, its closing deals carry. Null when it is not engaged. ### Answers - 200: The kill switch, lifted. - 401: - `missing_api_key`: No API key: send it as `Authorization: Bearer `.; `invalid_api_key`: The key is not a workspace's current key (a rolled key stops working within about a minute). - 404: - `no_such_account`: No such account, or one the key's workspace doesn't have: the two look the same. - 422: - `invalid_request`: A field, query parameter or header is missing, malformed or not allowed, or the body is not JSON. Nothing was sent. - 503: - `engine_busy`: The account's engine host has too many calls in flight (256). Nothing was done; try again.; `engine_unavailable`: The account's engine host is not connected to Pipsocket, or disconnected while the call waited. A trade it already had is still settled: look it up. - 504: - `engine_timeout`: The account's engine did not answer within 30 seconds. ### Example ```bash curl -X DELETE "https://api.pipsocket.com/v1/accounts/acc_01m6tx3k9f2qw8r7bznd5yvh4c/kill-switch" \ -H "Authorization: Bearer $PIPSOCKET_KEY" ``` 200 lifted: ```json { "deviation": null, "engaged": false, "since": null } ```