> ## Documentation Index
> Fetch the complete documentation index at: https://finance.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Limit Order
> Buy or sell an equity only at your specified price or better. Includes the complete round-trip: place over REST, then track fills over the Account WebSocket.
A **limit order** executes only at your `price` **or better** — never worse. A buy limit fills at your limit price or lower; a sell limit fills at your limit price or higher. You trade **certainty of execution** for **control over price**: you're guaranteed the price, but not that the order fills at all.
This page walks the **full lifecycle** end-to-end — place the order over REST, then follow it to a fill over the WebSocket — so you can use it as the template for every other order type.
New to the module? Start with [Order Flow](/api-reference/orders/order-flow). The subscribe handshake shown here is the same for **all** order types.
***
## When to use it
* You have a target entry or exit price and are willing to wait.
* The spread is wide or the name is volatile, and a [market order](/api-reference/orders/market-order) could fill at a bad price.
* You want to rest an order on the book (often with `GTC`) and let the market come to you.
***
## How it works
1. You `POST /v1/orders` with `type: "LIMIT"` and a `price`.
2. The order rests on the book as `NEW` until the market reaches your price.
3. When it trades through your price it fills — fully (`FILLED`) or in pieces (`PARTIALLY_FILLED`).
4. If it never reaches your price, a `DAY` order ends the session `EXPIRED`; a `GTC` order keeps resting until filled or cancelled.
***
## Request
| Field | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `type` | string | yes | Must be `"LIMIT"`. |
| `price` | string | yes | Your limit price as a decimal string. The order fills at this price or better. |
| `side` | string | yes | `BUY`, `SELL`, `SELL_SHORT`, or `BUY_TO_COVER`. |
| `qty` | string | yes | Number of shares as a decimal string. |
| `timeInForce` | string | yes | `DAY`, `GTC`, `IOC`, or `FOK`. Use `DAY` to expire at the close, `GTC` to rest until cancelled. |
| `stopPrice` | string | — | **Do not send** for a plain limit order. (That would make it a [stop-limit](/api-reference/orders/stop-limit-order).) |
### Step 1 — Place the order
```bash cURL theme={null}
curl -X POST https://api.aries.com/v1/orders \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "100",
"price": "150.50",
"timeInForce": "DAY"
}'
```
```json Request body theme={null}
{
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "100",
"price": "150.50",
"timeInForce": "DAY"
}
```
`price` is **required** for limit orders. Omitting it is rejected. Send it as a string (`"150.50"`), not a number.
### Response
```json theme={null}
{
"success": true,
"clOrdId": "CLIENT-001",
"status": "NEW",
"symbol": "AAPL",
"side": "BUY",
"qty": "100",
"cumQty": "0",
"leavesQty": "100",
"avgPrice": "0",
"transactTime": "2024-01-15T10:30:00Z"
}
```
The order is now **working** on the book. It has not filled yet — `cumQty` is `0` and `leavesQty` is the full quantity. Fills arrive over the WebSocket.
***
## Listen for updates
This is the WebSocket half of the round-trip. The handshake below is identical for every order type — only the `account.order` payload differs.
### Step 2 — Connect & authenticate
Open the connection and authenticate **within 5 seconds**:
```javascript theme={null}
const ws = new WebSocket("wss://api.aries.com/v1/accounts/ws");
ws.onopen = () => {
ws.send(JSON.stringify({
type: "request",
id: "auth-001",
payload: {
method: "post",
path: "/auth",
body: { token: "YOUR_ACCESS_TOKEN" }
}
}));
};
```
The server replies with an `authSuccess` event:
```json theme={null}
{
"type": "event",
"payload": {
"action": "authSuccess",
"data": { "expiresIn": 3900000 },
"id": "auth-001",
"timestamp": 1703001234567
}
}
```
### Step 3 — Subscribe to the account topic
```json Subscribe request theme={null}
{
"type": "subscribe",
"id": "req-002",
"payload": {
"topic": "account",
"params": { "accountId": "ACC123456" }
}
}
```
You immediately receive a **snapshot** of current orders, positions, and balance, then a live stream of events. (Subscribe *before* placing so you never miss an update.)
### Step 4 — Receive order events
As the limit order works and fills, you get `account.order` events. Watch `ordStatus`, `cumQty`, and `leavesQty`:
```json theme={null}
{
"type": "event",
"timestamp": "2024-01-15T10:30:00Z",
"payload": {
"topic": "account",
"name": "account.order",
"target": "account:ACC123456",
"data": {
"ordId": "ORD-12345",
"clOrdId": "CLIENT-001",
"accountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"timeInForce": "DAY",
"qty": "100",
"price": "150.50",
"ordStatus": "NEW",
"cumQty": "0",
"leavesQty": "100",
"avgPrice": "0",
"securityType": "EQUITY",
"category": "EQUITY",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}
}
```
```json theme={null}
{
"type": "event",
"timestamp": "2024-01-15T10:31:12Z",
"payload": {
"topic": "account",
"name": "account.order",
"target": "account:ACC123456",
"data": {
"ordId": "ORD-12345",
"clOrdId": "CLIENT-001",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "100",
"price": "150.50",
"ordStatus": "PARTIALLY_FILLED",
"cumQty": "40",
"leavesQty": "60",
"avgPrice": "150.48",
"updatedAt": "2024-01-15T10:31:12Z"
}
}
}
```
```json theme={null}
{
"type": "event",
"timestamp": "2024-01-15T10:31:40Z",
"payload": {
"topic": "account",
"name": "account.order",
"target": "account:ACC123456",
"data": {
"ordId": "ORD-12345",
"clOrdId": "CLIENT-001",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "100",
"price": "150.50",
"ordStatus": "FILLED",
"cumQty": "100",
"leavesQty": "0",
"avgPrice": "150.49",
"updatedAt": "2024-01-15T10:31:40Z"
}
}
}
```
Match events to your order by `clOrdId`. Drive your UI off `ordStatus` and the `cumQty`/`leavesQty` pair: `cumQty` is what's filled, `leavesQty` is what's still working. After the first snapshot, later updates may include only the fields that changed.
For the full WebSocket reference — every topic, reconnection strategy, session expiry, and the complete field/enum tables — see [Account Updates WebSocket](/websockets/account-updates).
***
## Modify or cancel a resting limit order
Because a limit order can rest for a while, you'll often want to re-price or cancel it.
```json Replace — move the limit to 150.25 theme={null}
{
"origClOrdId": "CLIENT-001",
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY",
"type": "LIMIT",
"qty": "100",
"price": "150.25",
"timeInForce": "DAY"
}
```
A successful replace returns a **new** `clOrdId`. To replace again, send that new ID as `origClOrdId` — the old one is invalidated. See [Replace Order](/api-reference/orders/update-order).
```json Cancel theme={null}
{
"origClOrdId": "CLIENT-001",
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "BUY"
}
```
***
## Next steps
Trigger a market order when a price level is breached.
Combine a trigger with a price cap.
Apply a limit price to a single call or put.
The full streaming reference for order, position, and balance events.