# Price a spread ticket

`POST https://app.skylit.ai/api/nexus/v1/spreads/orders/preview`

API: Nexus.

Prices a multi-leg spread on your main simulated account without placing it, exactly as the Spreads ticket in Nexus does: what it costs, the fee, your buying power after, and the natural price now. It answers a `confirmationToken` and a `clientOrderId`: send both with the same ticket to `POST /api/nexus/v1/spreads/orders` to place it.

- **Main account only.** Leave `account` and `port` out (or send `account: "main"`). Anything else answers `422 port_unsupported`.
- **Open or close.** To close, send the legs you hold with their sides flipped and `positionEffect: "CLOSE"`. There is no other close route.
- **Limit or market.** A market spread takes the natural now, is good for the day only and takes no `limitPrice`. One that can't fill now is refused here.
- **Same checks as Nexus.** Spreads must be open to you (`capabilities.spreads`), opens need "Let my agent trade my main account" while that setting applies, and on a leg's expiration day new opens stop at 3:00 PM ET.

Beta. Spreads trade on your main account only, and nothing here moves real money.

```bash
curl -s -X POST "https://app.skylit.ai/api/nexus/v1/spreads/orders/preview" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legs":[{"assetClass":"options","direction":"call","expiration":"2030-12-31","ratio":1,"side":"BUY","strike":775,"ticker":"SPY"},{"assetClass":"options","direction":"call","expiration":"2030-12-31","ratio":1,"side":"SELL","strike":780,"ticker":"SPY"}],"limitPrice":1.9,"netEffect":"DEBIT","orderType":"LIMIT","positionEffect":"OPEN","quantity":2,"strategy":"VERTICAL","timeInForce":"DAY"}'
```

## Authentication

Send your Skylit API key as a bearer token: `Authorization: Bearer <key>`. No other header is accepted.

## Request body

`application/json`

```json
{
  "account": "main",
  "port": "string",
  "strategy": "VERTICAL",
  "positionEffect": "OPEN",
  "netEffect": "DEBIT",
  "orderType": "LIMIT",
  "timeInForce": "DAY",
  "quantity": 2,
  "limitPrice": 1.9,
  "legs": [
    {
      "assetClass": "options",
      "ticker": "SPY",
      "expiration": "2030-12-31",
      "strike": 775,
      "direction": "call",
      "side": "BUY",
      "ratio": 1
    }
  ]
}
```

## Example request

```bash
curl "https://app.skylit.ai/api/nexus/v1/spreads/orders/preview" \
  -H "Authorization: Bearer $SKYLIT_API_KEY"
```

## Responses

### 200

The price, and the token and id a place needs.

The vertical at its 1.90 natural: $380 for 2 (a local run of the route).:

```json
{
  "data": {
    "buyingPowerAfter": 99620,
    "clientOrderId": "fadb7b8e-4687-4a35-b9d9-5641ec7fb15f",
    "confirmationToken": "b65b341552e0280ad4c2189035c318cc850d164aa2b8aaee301e12840dbd5b09",
    "estimatedCost": 380,
    "estimatedTransactionFee": 0,
    "quotePrice": 1.9,
    "quoteTime": "2026-11-19T07:53:44.468Z",
    "warnings": []
  },
  "meta": {
    "account": "main"
  }
}
```

### 400

Refused before anything was sent. Codes: `bad_request` (an unknown field, a leg that isn't `options` or `stocks`, legs that don't form the `strategy`, a missing `limitPrice` on a limit, a market order with one, a quantity over 100, a modify with neither `quantity` nor `limitPrice`, a `date` that isn't `YYYY-MM-DD`), `expiry_day_cutoff` (on a leg's expiration day, new spread opens stop at 3:00 PM ET; closes are never refused).

An open on its expiration day after 3:00 PM ET.:

```json
{
  "error": {
    "code": "expiry_day_cutoff",
    "message": "On its expiration day, Simulated takes new spread orders until 3:00 PM ET. You can still close."
  }
}
```

A modify with nothing to change.:

```json
{
  "error": {
    "code": "bad_request",
    "message": "Send a new quantity, a new limitPrice or both. To change anything else, cancel the order and place a new one."
  }
}
```

### 401

No key, or a key that isn't valid. Codes: `missing_api_key`, `invalid_api_key`.

No key sent.:

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "Send your Skylit API key in the Authorization header: Authorization: Bearer YOUR_SKYLIT_API_KEY."
  }
}
```

### 403

The key works but this can't happen right now. Codes: `feature_disabled` (spreads aren't open to you, opening spreads is switched off while you can still close and cancel, or a broken wing butterfly), `main_not_enabled` (an open while "Let my agent trade my main account" is off; closes, cancels and exits never need it), `paper_desk_paused` (Simulated is paused for members: you can still preview and place a close, cancel, and take an exit off), `read_only`, plus the shared `account_suspended` and `nexus_access_denied`.

Spreads aren't open to this account yet.:

```json
{
  "error": {
    "code": "feature_disabled",
    "message": "Spreads are admins only for now"
  }
}
```

An open while your agent may not trade your main account.:

```json
{
  "error": {
    "code": "main_not_enabled",
    "message": "Your agent isn't allowed to trade your main account, and spreads are on your main account only, so nothing was placed. To allow it, turn on \"Let my agent trade my main account\" on your Agent page in Nexus."
  }
}
```

### 409

It clashes with what you hold or sent before. Codes: `preview_mismatch` (the ticket isn't what the preview priced: preview again), `spread_conflict` (closing a spread you don't hold, closing more than you hold or than your resting closes leave, or opening one you hold the other way round: close it instead), `working_order_limit` (your resting API orders, stops included, and every working spread order count together toward 50, spread orders placed on the Spreads ticket in Nexus included), `client_order_id_used`, `order_not_working` (it already filled, expired, or was cancelled or rejected), `exit_triggered` (the stop or target was reached and the spread is closing, so its exit can't change).

The place doesn't match its preview.:

```json
{
  "error": {
    "code": "preview_mismatch",
    "message": "This isn't what the preview priced, so nothing was placed. Preview it again and send that preview's confirmationToken and clientOrderId."
  }
}
```

50 resting orders already.:

```json
{
  "error": {
    "code": "working_order_limit",
    "message": "You have 46 orders resting through the API and 4 spread orders working (the limit is 50 together). Cancel some before placing more."
  }
}
```

### 422

Read fine, but the account says no. Codes: `port_unsupported` (any account but `main`, or any port), `insufficient_buying_power` (with `orderId` when the order was recorded as rejected), `order_rejected` (recorded as rejected as it was placed; `orderId` points to it), `contract_expired`.

Spreads on a port or the agent account.:

```json
{
  "error": {
    "code": "port_unsupported",
    "message": "Spreads are on your main account only. Send account \"main\" or leave account and port out."
  }
}
```

### 429

Over a rate limit. Wait `Retry-After` seconds, then retry. Codes: `rate_limited`, and `stream_limit_reached` (too many live streams open: 3 per key, 6 per account).

Headers: `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`.

Too many writes from this key.:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests (limit 30). Slow down and retry in 12 seconds."
  }
}
```

### 500

Something went wrong on our side. If you sent a `clientOrderId`, retry with the same one. Code: `internal_error`.

Retry with the same clientOrderId.:

```json
{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side. If you sent a clientOrderId, retry with the same one (it can't fill twice). Otherwise check your account before retrying."
  }
}
```

### 503

Try again in a moment. Codes: `no_live_quote` (a leg, or the underlying, has no live quote; quotes older than 15 s never fill), `unavailable` (spreads aren't on this server, or a check couldn't be read).

A leg has no live quote.:

```json
{
  "error": {
    "code": "no_live_quote",
    "message": "No live quote for a leg right now (quotes older than 15 s never fill), so nothing was placed. Try again."
  }
}
```
