# Limits, stops and adds

> Rest an order at your price, protect an options trade on the stock's price, add to a position, and change a resting order's price or size.

Market orders fill now. Everything on this page waits for your price instead, or grows a position you already hold. It all runs on the same engine as the Options Desk and the futures ticket in Nexus, so it fills the same way an order you placed by hand would.

All tickers, prices, ids and times on this page are made up to show the shape of a call. They aren't real fills and they aren't results.

## What each asset class takes

| Asset class | Open | Close |
|---|---|---|
| Options | `market`, `limit` | `market`, `limit`, a stop-loss and take-profit on the stock's price |
| Stocks | `market`, `limit`, `stop` | `market`, `limit`, `stop` |
| Futures | `market`, `limit`, `stop`, `stop_limit`, with an optional bracket | the close route, or the opposite side with `reduceOnly` |

Ask `GET /api/nexus/v1/trading/capabilities` what your key has right now. `assetClasses` lists each one's order types, and `optionsOrders`, `stocksOrders` and `futures` spell out the details.

Resting options and stock orders and options stops are opening up in stages. If capabilities doesn't list them for your key yet, those routes answer `403` with code `paper_desk_admin_only`. Market orders, adds and futures work as usual.

## How resting options and stock orders fill

| Order | Fills when | Fills at |
|---|---|---|
| Options limit buy | the ask comes down to your limit | the ask |
| Options limit sell | the bid comes up to your limit | the bid |
| Options stop-loss or target | the stock trades through your level | the option's live bid |
| Stock limit buy | a trade prints at or under your limit | that trade's price |
| Stock limit sell | a trade prints at or over your limit | that trade's price |
| Stock stop | a trade prints through your stop | the next trade after it, never the one that set it off |

- You never fill at your limit unless the market's there, never at mid, and never on a quote older than 15 seconds.
- It only fills while the market's open for that contract. Stocks fill between 9:30 am and 4:00 pm ET (1:00 pm on early-close days).
- If the market's already through your limit when you send it, it fills right away, at the quote.

Limit 2.00 on a call, ask drops to 1.95: you're filled at 1.95. Sell stop 180.00 on AAPL, it trades 179.95, then 179.80: you're out at 179.80.

## Options limit orders

Send the same body as a market open, plus `"orderType": "limit"` and `limitPrice`:

```bash
curl -s -X POST "$NEXUS/api/nexus/v1/trades" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"contract":"SPY 600C 10/16","quantity":2,"orderType":"limit","limitPrice":2.00,
       "clientOrderId":"spy-dip-0001"}'
```

| Field | Allowed values | Default | What it does |
|---|---|---|---|
| `orderType` | `"limit"` | `"market"` | Rests the order at `limitPrice` |
| `limitPrice` | 0.01 to 99999.99, in cents | none | The most you'll pay per contract |
| `timeInForce` | `"day"`, `"gtc"` | `"day"` | `day` works until 4:00 pm ET (sent after the close, it works the next session). `gtc` works until 4:00 pm ET on the contract's last trading day |

Don't send `price` or `ifOutside` with a limit. Those are for market orders.

It answers `201` with the order. A resting one is `"status": "working"`. If it filled on the spot you'll see `"status": "filled"`, `fillPrice`, `tradeId` and `meta.fill`, and your position is a normal trade you can read with `GET /api/nexus/v1/trades/{tradeId}`.

- **A resting buy holds back buying power:** quantity x limit x 100. The wallet read shows it as `reservedCents`. A fill, a cancel or an expiry gives it back.
- **A market order can still spend that cash.** If it does, your resting buy is rejected when it tries to fill.
- **A limit buy on a contract you already hold adds to that position.**
- **The caps count resting orders.** Open positions plus resting opens through the API stay under 50 together (`409 open_position_limit`), and up to 50 orders can rest through the API at once (`409 working_order_limit`).
- **A limit fill isn't posted to Discord and isn't copied.** A market order still is.

**Close with a limit:** send `"orderType": "limit"`, `limitPrice` (the least you'll take), and `quantity` or `"closeAll": true` to `POST /api/nexus/v1/trades/{id}/exits`. It answers `201` with a sell order and `meta.tradeId`, and fills when the bid comes up to your limit, at the bid. If you hold the same contract on more than one trade in that wallet, the fill closes the oldest first.

## Stock limit and stop orders

```bash
curl -s -X POST "$NEXUS/api/nexus/v1/trades" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"assetClass":"stocks","ticker":"AAPL","side":"buy","quantity":25,
       "orderType":"limit","limitPrice":185.00,"clientOrderId":"aapl-dip-01"}'
```

| Field | Allowed values | Default | What it does |
|---|---|---|---|
| `side` | `"buy"`, `"sell"` | none | `sell` opens a short |
| `quantity` | 1 to 100000 shares | none | |
| `orderType` | `"limit"`, `"stop"` | `"market"` | |
| `limitPrice` | 0.01 to 999999.99, in cents | none | With `limit`: the most you'll pay (buy) or the least you'll take (sell) |
| `stopPrice` | 0.01 to 999999.99, in cents | none | With `stop`: the price that sets it off |
| `timeInForce` | `"day"`, `"gtc"` | `"day"` | `day` works until 4:00 pm ET. `gtc` works for 90 days |

Send `limitPrice` or `stopPrice`, not both. Stop-limit orders aren't available on stocks.

- **A resting open holds back buying power:** shares x limit (or x stop). A short holds it back too, the same as a buy.
- **A stop that's been set off can't be cancelled or changed.** It fills on the next trade (`409 stop_triggered`). The order shows `triggeredAt` and `triggerPrice`.
- **Close with a limit or a stop** on `POST /api/nexus/v1/trades/{id}/exits`. On a long it's a sell, on a short it's a buy back.

**Stock market orders need a live price.** A stock market order fills at the last trade. If that's more than 15 seconds old you get `503 stale_quote` and nothing fills. Wait a moment and send it again.

## Options stop-loss and take-profit

Protect an options trade you hold with a stop, a target, or both:

```json
{ "stopLoss": 585.00, "takeProfit": 610.00, "closeAll": true, "clientOrderId": "spy-bracket-1" }
```

Send it to `POST /api/nexus/v1/trades/{id}/exits`.

- **Your levels are the stock's price, not the option's.** A stop at 585 on an SPY call fires when SPY trades at or under 585. What the option's doing doesn't matter.
- **Calls:** the stop sits under the stock's price and the target over it. **Puts:** the other way round, since a put makes money when the stock falls.
- **When a level hits, it sells at the market,** at the option's live bid at that second. With no live quote (nothing in the last 15 seconds), nothing sells and it tries again a few seconds later.
- **A bracket is one order.** Whichever level the stock reaches first fires, and the other goes with it.
- **It stays on until it fires, you cancel it, or the contract expires.** There's no day or GTC to pick.
- **It goes on a trade you hold.** You can't attach it to an entry or a resting limit. Open first, then send the stop.
- `"orderType": "stop"` with `stopPrice` works too. It's the same as `stopLoss` on its own.

You get the order back with `orderType` `"stop"`, `"take_profit"` or `"bracket"` and `"triggerOn": "underlying"`. `meta.underlyingPrice` is the stock's price right now, and `meta.firesNow: true` means the stock's already through a level, so it fires on the next check. After it fires, the order shows `firedLeg`, `triggerPrice` (the stock price that set it off), `fillPrice` (what the option sold for) and `fillOrderId`.

## Manage resting options and stock orders

They live on the wallet they trade on: `{book}` is `main` (your paper wallet) or `agent` (your bot's).

| Method | Path | What it does |
|---|---|---|
| GET | `/api/nexus/v1/trading/wallets/{book}/orders/working` | Everything resting on that wallet, oldest first |
| GET | `/api/nexus/v1/trading/wallets/{book}/orders/{orderId}` | One order as it stands now, any status |
| POST | `/api/nexus/v1/trading/wallets/{book}/orders/{orderId}/cancel` | Cancel it. Safe to send twice (`meta.alreadyCancelled`) |
| POST | `/api/nexus/v1/trading/wallets/{book}/orders/{orderId}/modify` | Change it in place |
| POST | `/api/nexus/v1/trading/wallets/{book}/orders/cancel` | `"cancelAll": true`, or `"ticker": "SPY"` for one underlying. Closes nothing |

- **The main wallet's list shows Options Desk orders too.** They rest on the same money. Yours carry `"source": "api"` and your `clientOrderId`.
- **Modify keeps the same `id`.** On a limit, `price` is the new limit and `quantity` the new size. On a stock stop, `price` is the new stop. On an options stop, send `stopLoss`, `takeProfit`, `quantity`, or `price` when it has only one level.
- **A bigger buy has to fit your buying power** or nothing changes (`422 insufficient_buying_power`). Move a buy above the ask and it fills right away, at the ask.
- **You can't change what isn't resting:** `409 order_not_working` once it's filled, expired or rejected, and `409 stop_triggered` once a stop's been set off.
- **A cancel-all skips stops that are filling** and lists them in `meta.stopsFilling`.
- Statuses: `working`, `filled`, `cancelled`, `rejected`, `expired`. `statusReason` says why when there's a reason.

## Futures stop-limit orders

Send `"orderType": "stop_limit"` with `stopPrice` and `limitPrice`. Nothing happens until a trade hits your stop. Then it works as a limit order at your limit price, and only fills at that price or better.

- On the bar that hits your stop, it fills right there if a plain stop would've filled inside your limit. If the market jumps past your limit, you don't get filled. It waits at the limit until price comes back, or until you cancel it.
- A buy's limit has to be at or above its stop, and a sell's at or below. A stop loss and take profit sent with it are checked against both prices.
- Once your stop's been hit, the order shows `triggeredAt`.

## Change a resting futures order's size

`POST /api/nexus/v1/trading/accounts/{account}/orders/{orderId}/modify` takes `quantity`, `price`, or both. Both change together or neither does. On a stop-limit, `price` is its limit and `stopPrice` its trigger, and the trigger can't move once it's been hit.

- Going up is checked like a new order of that size, your evaluation's contract cap included, and your order loses its place in line from that moment. Going down keeps its place.
- Your stop and target follow the new size.
- Futures orders fill all at once, so a filled order can't be resized, and 0 isn't a size: cancel the order instead.
- On a test order you can rehearse a size change. Its price can't be moved.

## Add to a position

Already in a trade and want more? Don't send a second open (that answers `409 duplicate_position`, and its `tradeId` is the trade to add to). Send an add:

```bash
curl -s -X POST "$NEXUS/api/nexus/v1/trades/$TRADE_ID/adds" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"quantity":2,"clientOrderId":"my-bot-add-0001"}'
```

- It fills like an open: options at the live ask, stocks at the live price. Send `price` for your own price when it's inside the market, and `ifOutside` for what happens when it isn't.
- Your average, totals and P/L update exactly the way they do when you add in Nexus, and the paper wallet pays. A trade on your agent account pays from the agent wallet and stays private.
- Market orders only. Each add is 1 to 1,000 contracts or 1 to 100,000 shares, and a position can't grow past that through the API (`409 position_size_limit`).
- Not enough buying power is `422 insufficient_buying_power`. A quote older than 15 seconds is `503 stale_quote`: nothing was added, so try again in a moment.
- Send a `clientOrderId`. If your bot retries, the add happens once and the repeat answers with the trade and `meta.idempotentReplay: true`.

You get the trade back, with `meta.fill` showing the price, how many you added and where the price came from.

## Futures in your trades list

`GET /api/nexus/v1/trades?assetClass=futures` lists one futures account at a time.

- Leave `account` out for your practice account, or send `agent`, `evaluation`, `funded` or an account id.
- `status=open` lists your open positions with the same numbers as the account read. `status=closed` lists your closed trades, flat to flat, with the same P/L your futures journal shows, newest first. Leave `status` out for both, open first.
- Page with `limit` and `offset`, like the options list.
- Without `assetClass=futures` the list is options and stocks, same as always.

## Test orders

`"test": true` works on all of it.

- A test limit or stop is checked against your wallet and the live quote, then sits in your test log as `working` and never fills. `meta.wouldFillNow` (with `meta.fillPrice`) says whether the real one would've filled right away, and `meta.wouldRestBecause` why it would rest. A test stock stop says `meta.wouldTriggerNow`.
- A test limit or stop can't be modified (`400 test_modify_unavailable`). Cancel it and send a new one.
- A stop-loss sent on a test trade is checked and logged, and nothing is armed. `meta.wouldFireNow` says whether the stock's already through a level.
- An add to a test trade's id is a test add.

See [Test orders](https://www.skylit.ai/docs/nexus-trades/test-orders) for the rest.