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

# Closing a position

> Close one position on a trading account, wholly or in part, or cancel its working orders without closing anything, with your organization API key.

Close a single position on one trading account at market, for example when
your risk team decides a trade must come off. The rest of the account is
untouched: other positions stay open, the account keeps its status and the
trader can keep trading. To close everything on an account at once, use
`POST /organization/trading-accounts/{accountId}/flatten`. To cancel working
orders and leave positions open, see
[Cancel orders without closing](#cancel-orders-without-closing).

Requires **manage** permission on traders.

## Close a position

```bash theme={null}
curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/positions/MNQZ6/close" \
  -H "X-API-Key: hp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: close-7c9e6679-mnqz6-001" \
  -d '{"reason": "Risk review", "quantity": 1}'
```

The contract in the path is the position's contract symbol, as on the
positions read and the real-time stream.

| Field | Required | Description |
| - | - | - |
| `reason` | Yes | 3 to 200 characters. Recorded on the closing order and the account's event log |
| `quantity` | No | How much to close, in the position's units (futures: contracts). Omit it to close the whole position. Must not exceed the open size |

## Whole or partial close

| | Whole position (no `quantity`, or the full size) | Part of it (`quantity` below the open size) |
| - | - | - |
| Closing order | Market order for the open size | Reduce-only market order for `quantity` |
| Working orders on the contract | Cancelled: entries before the close, take-profit and stop-loss after the fill | Kept. Take-profit and stop-loss keep protecting what remains |
| Other contracts | Untouched | Untouched |

A whole-position close does for one contract what flatten does for the
whole account.

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "accountNumber": "ACC-50K-000123",
    "contract": "MNQZ6",
    "side": "long",
    "requestedQuantity": 1,
    "remainingQuantity": 1,
    "closed": false,
    "ordersCancelled": 0,
    "orders": [
      {
        "orderId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "contract": "MNQZ6",
        "side": "sell",
        "type": "market",
        "quantity": 1,
        "filledQuantity": 1,
        "status": "filled",
        "avgFillPrice": 21010.5,
        "filledAt": "2026-10-30T14:41:07.312Z",
        "rejectReason": null,
        "reason": "Admin flatten: API key — Risk review"
      }
    ],
    "reason": "Admin flatten: API key — Risk review"
  }
}
```

`side` is the position's direction before the close. `remainingQuantity` is
what is left open on the contract; `closed` is `true` when nothing is.

## What else happens

The close is an ordinary market order. It fills at the market price with the
usual commissions and updates the balance and rules like any other close.

* **Real-time stream**: the usual `OrderSubmitted`, `OrderFilled`,
  `PositionUpdate` and `AccountUpdate` messages, and `OrderCancelled` for
  each cancelled order.
* **Order history**: the orders carry reason
  `Admin flatten: <who> — <your reason>` and trigger `admin_flatten`, like a
  flatten.
* **Event log and webhooks**: an `ACCOUNT_UPDATED` event with trigger
  `admin_position_close`, who closed it, the contract, the quantity closed,
  what remains and the number of cancelled orders, sent to `account.updated`
  webhook subscribers.

## Market hours

A close is refused with `409 MARKET_CLOSED` while the contract's market is
closed, for example during the daily break, at the weekend or on a
holiday. Nothing is closed; send it again once the market is open.

## Retries

Send an `Idempotency-Key` header. A retry with the same key and body returns
the first response and never closes twice. Without a key, repeating a
whole-position close is safe: once the position is gone it answers
`404 NO_POSITION`. Repeating a partial close without a key closes more.

If the call ends with `504 CLOSE_OUTCOME_UNKNOWN`, the position may or may
not have been closed: read the account's positions
(`GET /organization/trading-accounts/{accountId}/positions`) before you
retry.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Missing or invalid `reason`, `quantity` or path |
| `400` | `QUANTITY_EXCEEDS_POSITION` | `quantity` is larger than the open position |
| `403` | `INSUFFICIENT_PERMISSIONS` | The key's role lacks manage permission on traders |
| `404` | `ACCOUNT_NOT_FOUND` | No account with this ID in your organization |
| `404` | `NO_POSITION` | No open position in this contract |
| `409` | `MARKET_CLOSED` | The contract's market is closed; nothing was closed |
| `409` | `CLOSE_REJECTED` | The closing order was rejected; the position is still open |
| `502` | `ENGINE_UNAVAILABLE` | The close could not be sent; nothing was closed. Retry |
| `504` | `CLOSE_OUTCOME_UNKNOWN` | No answer in time; read the positions before retrying |

## Cancel orders without closing

Cancel an account's working orders and leave every position open, for example
to stop new entries while a trade is reviewed. The account keeps its status
and the trader can keep trading.

```bash theme={null}
curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts/7c9e6679-7425-40de-944b-e07fc1f90ae7/orders/cancel" \
  -H "X-API-Key: hp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Risk review", "contract": "MNQZ6"}'
```

| Field | Required | Description |
| - | - | - |
| `reason` | Yes | 3 to 200 characters. Recorded on each cancelled order and the account's event log |
| `contract` | No | Only cancel orders on this contract. Omit it for every contract |
| `includeExits` | No | `true` also cancels the take-profit and stop-loss orders of open positions. Default `false` |

| | Default | `includeExits: true` |
| - | - | - |
| Entry orders and other working orders | Cancelled | Cancelled |
| Take-profit and stop-loss of an entry that has not filled | Cancelled with the entry | Cancelled |
| Take-profit and stop-loss of an open position | Kept | Cancelled: the position is left without them |
| Positions | Untouched | Untouched |

The default matches a trader's "Cancel all". Requires **manage** permission on
traders. Unlike a close, it also works while the market is closed.

```json theme={null}
{
  "success": true,
  "data": {
    "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "accountNumber": "ACC-50K-000123",
    "contract": "MNQZ6",
    "includeExits": false,
    "ordersCancelled": 1,
    "exitsKept": 2,
    "orders": [
      {
        "orderId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "contract": "MNQZ6",
        "side": "buy",
        "type": "limit",
        "quantity": 1,
        "filledQuantity": 0,
        "limitPrice": 20950.25,
        "stopPrice": null,
        "exit": false,
        "status": "cancelled",
        "reason": "Admin cancel: API key — Risk review"
      }
    ],
    "reason": "Admin cancel: API key — Risk review"
  }
}
```

`ordersCancelled` counts the orders this call cancelled; `exitsKept` the
take-profit and stop-loss orders left working.

* **Real-time stream**: an `OrderCancelled` message for each cancelled order.
* **Order history**: the orders carry reason
  `Admin cancel: <who> — <your reason>` and trigger `admin_flatten`.
* **Event log and webhooks**: when anything was cancelled, an
  `ACCOUNT_UPDATED` event with trigger `admin_orders_cancel`, who cancelled,
  the contract filter, `include_exits` and the counts, sent to
  `account.updated` webhook subscribers.

**Retries** are safe: a repeated call cancels nothing more and answers with
`ordersCancelled: 0`. On `504 CANCEL_OUTCOME_UNKNOWN`, some orders may have
been cancelled; send the call again.

| Status | Code | Meaning |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Missing or invalid `reason`, `contract` or `includeExits` |
| `403` | `INSUFFICIENT_PERMISSIONS` | The key's role lacks manage permission on traders |
| `404` | `ACCOUNT_NOT_FOUND` | No account with this ID in your organization |
| `502` | `ENGINE_UNAVAILABLE` | The cancel could not be sent; nothing was cancelled. Retry |
| `504` | `CANCEL_OUTCOME_UNKNOWN` | No answer in time; send it again |


## Related topics

- [Changelog](https://docs.hyperprop.com/changelog.md)
- [Cancel all pending orders for an account (keeps live position protection)](https://docs.hyperprop.com/trade-api/orders/cancel-all-pending-orders-for-an-account-keeps-live-position-protection.md)
- [Create admin lockout](https://docs.hyperprop.com/platform-api/lockouts/create-admin-lockout.md)
- [Get a close-all run](https://docs.hyperprop.com/platform-api/trading-accounts/get-a-close-all-run.md)
- [Close a specific position by contract](https://docs.hyperprop.com/trade-api/positions/close-a-specific-position-by-contract.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.