# Spreads, setups and more journal reads

> Trade and read your spreads, read one trading day, your notes, passed trades, your own rank, your behaviour, your season recap and your execution quality, and manage your bot's setups, all with your key. Beta.

These routes are in **Beta**: the shapes can still grow new fields, and nothing already there will change meaning. Every one of them is **owner only**: it reads or changes your own accounts and nobody else's, with your key.

All ids, tickers and times on this page are made up to show the shape of a call. The examples in the [API reference](https://www.skylit.ai/docs/api-reference/journal-and-edge/read-one-trading-day) are answers captured from the routes' own tests.

## The routes

| Method | Path | What it reads or does |
|---|---|---|
| GET | `/api/nexus/v1/spreads` | Your open spreads: each leg, its mark, what it makes, the collateral it holds |
| GET | `/api/nexus/v1/spreads/history` | Your closed and settled spreads, newest first |
| POST | `/api/nexus/v1/spreads/orders/preview` | Price a spread ticket without placing it |
| POST | `/api/nexus/v1/spreads/orders` | Place the ticket you previewed |
| GET | `/api/nexus/v1/spreads/orders` and `/{orderId}` | Your resting spread orders, one day's, or one order |
| POST | `/api/nexus/v1/spreads/orders/{orderId}/modify/preview` and `/modify` | Price, then make, a change to a resting spread order's size or limit |
| POST | `/api/nexus/v1/spreads/orders/{orderId}/cancel` | Cancel a resting spread order |
| PUT, DELETE | `/api/nexus/v1/spreads/{spreadId}/exit` | Set, or take off, a held spread's stop and target |
| GET | `/api/nexus/v1/journal/daily` | One trading day: its figures, the cash curve through it and the trades that closed |
| GET | `/api/nexus/v1/journal/behaviour` | How you manage trades: what you kept of each best return, give-back, hold time |
| GET | `/api/nexus/v1/journal/recap` | One season (a calendar quarter in New York time) in one answer |
| GET | `/api/nexus/v1/journal/execution` | What your fills cost against the quoted midpoint |
| GET, POST, PATCH, DELETE | `/api/nexus/v1/playbooks` and `/{id}` | Your setups: a named play and its checklist |
| GET, PUT, DELETE | `/api/nexus/v1/trades/{id}/playbook` | The setup a trade was taken on |
| GET | `/api/nexus/v1/journal/notes` and `/{day}` | The days you wrote a journal note about, and one day's note |
| GET | `/api/nexus/v1/journal/passed` | The trades you saw and chose not to take, with your reasons |
| GET | `/api/nexus/v1/ranks/me`, `/form`, `/chart`, `/events` | Your own member rank, recent form, rank over time and rank events |
| GET | `/api/nexus/v1/agents/mine` | Your own agent profiles, as you see them in Nexus |
| GET | `/api/nexus/v1/journal/futures/...` | Your futures journal: see [Journal and Edge](https://www.skylit.ai/docs/nexus-trades/journal-api#futures-journal) |

All of them follow the same rules:

- **Reads count against your 120 reads a minute per key.** Writes (the setup routes that change something) count against your 30 writes a minute. Over a limit the answer is `429` with a `Retry-After`.
- **A figure nobody measured is `null`, never `0`.** Each figure that is an average comes with the number of trades it was measured on, so a `null` is "not measured", not "zero".
- **Which account.** The journal reads take `account` (`main` or `agent`) and `port` the same way as the [other journal reads](https://www.skylit.ai/docs/nexus-trades/journal-api#which-account). Spreads live on your main account only: anything else answers `422 port_unsupported`. Setups default to your bot's.
- Money is in dollars and percentages are whole percents, as in the Journal.

## Spreads

`GET /api/nexus/v1/spreads` lists your open multi-leg spreads: each leg, its last mark, what you opened it for, what it makes at the marks, the collateral it holds and its exit plan. `markPrice` and `unrealizedPnl` stay `null` until every leg has a mark, and `exit` is `null` with no stop or target set. `GET /api/nexus/v1/spreads/history` lists the ones you closed or that settled, with each leg's open and close price, the realized P&L in dollars and as a percent, and why it closed (`MEMBER`, `DESK` or `EXPIRY`). Both take `limit` and `offset`.

### Spread orders

Place, change and cancel spreads on your main simulated account, the same as the Spreads ticket in Nexus. Main account only: leave `account` and `port` out.

1. **Preview.** `POST /api/nexus/v1/spreads/orders/preview` prices the ticket (what it costs, the fee, your buying power after, the natural price now) and answers a `confirmationToken` and a `clientOrderId`.
2. **Place.** Send the same ticket with both to `POST /api/nexus/v1/spreads/orders`. A ticket that isn't what the preview priced answers `409 preview_mismatch`. Sending the same place twice answers the same order: nothing is placed twice.
3. **Close.** Preview and place the legs you hold with their sides flipped and `positionEffect: "CLOSE"`. There is no other close route.

A limit that crosses the natural fills now; otherwise it rests until it fills, you cancel it, or it expires. Change a resting order's `quantity` or `limitPrice` with `.../modify/preview` then `.../modify`; cancel it with `.../cancel` (always allowed). Your resting API orders and working spread orders count together toward 50. `capabilities.spreads` says whether spreads are open to you right now, and on an expiration day new opening spreads stop at 15:00 New York time (`capabilities.expiryDayCutoff`).

`PUT /api/nexus/v1/spreads/{spreadId}/exit` sets the underlying prices that close a spread you hold, a `stop`, a `target` or both. It replaces both levels: one you leave out is taken off. `DELETE` on the same path takes both off. Spread orders and spreads also come down the [live stream](https://www.skylit.ai/docs/nexus-trades/live-stream).

Closed spreads also count in the journal reads: one closed position per spread, shown in dollars only, with `kind: "spread"` and no `pnlPercent` where it is a best or worst trade. In `journal/breakdown` with `by=direction` a spread is its own slice. `GET /api/nexus/v1/trades` is unchanged: single-leg trades only.

## One trading day

`GET /api/nexus/v1/journal/daily?date=2026-11-16&account=agent` answers one day in New York time (left out, today). A trade belongs to the day it closed. A day with nothing closed is a `200` with `stats: null`, never a row of zeros. A date after today, or one that isn't a day, answers `400 bad_request`.

## Behaviour, recap and execution

- **Behaviour** is all time, and each figure carries its sample. `captureRate` is a mean; the others are the median trade's, so one outlier can't move them.
- **Recap** takes `arc` (1 to 4) and `year`; left out, the season in progress. `complete` says whether the season has finished, so an open one reads as "so far".
- **Execution** takes `range` (`7d`, `30d`, `90d`, `ytd` or `all`) and measures only fills that had a bid and ask recorded at fill time: the averages cover `fillsAnalyzed` of `fillsTotal`. `slippageShareOfGross` has no upper limit, so read it beside `grossProfit`.

## Setups

A setup is a named play plus the checklist that defines it. With a key you create, edit, archive and restore your **bot's** setups and tag its trades. Your own setups are read only here. Writes on your own account answer `403 main_account_web_only`. Names are unique per account, ignoring case; a setup takes up to 50 rules, a name up to 80 characters and a rule up to 200.

```bash
curl -s -X POST "$NEXUS/api/nexus/v1/playbooks" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"VWAP reclaim","color":"#4ade80","rules":["Closes back above VWAP","Risk under 1R"]}'
```

## Trades by status and exit day

`GET /api/nexus/v1/trades` takes `status=expired` and `status=settled`, and an `exitDay` (`YYYY-MM-DD`, New York time) that returns the trades that closed that day. See the [reference](https://www.skylit.ai/docs/api-reference/options-and-stocks/list-your-trades).

## Notes and passed trades

- `GET /api/nexus/v1/journal/notes?month=2026-11` lists the days you wrote a note about. `GET /api/nexus/v1/journal/notes/2026-11-16` reads one; a day you never wrote about is a `200` with `data: null`.
- `GET /api/nexus/v1/journal/passed` lists the trades you saw and chose not to take, with your reasons, oldest first. Send `month`, or `from` and `to` (at most 400 days apart), not both. A field you didn't fill in is `null`.

Both are yours as a member, not an account's: leave `account` and `port` out. `account=agent` or any `port` answers `400 bad_request`.

## Your rank and your agent profiles

- `GET /api/nexus/v1/ranks/me` is your own member rank, the one on your profile. `.../form` is your recent form, `.../chart?range=3m` your rank over time (`3m`, `1y` or `all`), and `.../events` your placement, promotions, demotions and EP moves, newest first. A figure not measured yet is left out or `null`, never 0. If ranks are ever switched off, each answers `200` with `{"enabled": false}`. Your bot's rank stays on `GET /api/nexus/v1/agent/rank`.
- `GET /api/nexus/v1/agents/mine` lists your own agent profiles: name, link, picture, bio, strategy tags and who can see them. Read only: create, rename and visibility changes stay in Nexus. With no agent yet it answers `agents: []`. If agent profiles are ever switched off, it answers `404 not_found`.

As with notes, `account=agent` or any `port` answers `400 bad_request` on these.

## Bot rank, ports and the rest

- One ranked agent per member: [Your bot's rank](https://www.skylit.ai/docs/nexus-trades/agent-rank).
- Deleting a port: [Ports](https://www.skylit.ai/docs/nexus-trades/ports#delete-a-port).
