Nexus/API Reference/Spreads

Price a spread ticket

POSThttps://app.skylit.ai/api/nexus/v1/spreads/orders/preview

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.

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"}'

Authorization

Authorization: Bearer <your API key>

Required. A missing header returns 401; an invalid, revoked or expired key returns 403.

Request body

  • accountstring

    main or left out. Any other account answers 422 port_unsupported.

    main
  • portstring

    Leave it out. Spreads trade on your main account only, so any port answers 422 port_unsupported.

  • strategystringrequired

    What the legs form: VERTICAL, STRADDLE, STRANGLE, BUTTERFLY, CONDOR, IRON_BUTTERFLY, IRON_CONDOR, CALENDAR, DIAGONAL, COVERED_STOCK or COLLAR_WITH_STOCK. capabilities.spreads.strategies lists what you may open right now. Legs that form something else answer 400 bad_request.

  • positionEffectstring

    OPEN when left out. A close sends the legs you hold with their sides flipped.

    OPENCLOSE
  • netEffectstringrequired

    Whether this order pays (DEBIT) or takes in (CREDIT).

    DEBITCREDIT
  • orderTypestringrequired

    MARKET takes the natural price now, is good for the day only, and takes no limitPrice.

    LIMITMARKET
  • timeInForcestringrequired

    Good for the day, or until cancelled. A market order is DAY only.

    DAYGTC
  • quantityintegerrequired

    Spreads, 1 to 100.

  • limitPricenumber

    Limit orders: the net price per spread, always positive (netEffect says which way). Leave it out on a market order.

  • legsobject[]required
    • assetClassstring

      options when left out. stocks is the shares leg of a covered stock or a collar.

      optionsstocks
    • tickerstringrequired

      The underlying. Every leg trades the same one.

    • expirationstring | nulldate

      Options legs: the contract's expiration. null on shares.

    • strikenumber | null

      Options legs: the strike. null on shares.

    • directionstring | null

      Options legs: call or put. null on shares.

      callputnull
    • sidestringrequired

      This leg's side on this order. To close, send the legs you hold with their sides flipped.

      BUYSELL
    • ratiointegerrequired

      Contracts (or lots of shares) per spread.

Responses

  • 200

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

  • 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).

  • 401

    No key, or a key that isn't valid. Codes: missing_api_key, invalid_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.

  • 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).

  • 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.

  • 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).

  • 500

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

  • 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).

Response fields

  • dataobjectrequired

    What the ticket would cost, and the two values a place needs. A figure that couldn't be read is null, never 0.

    • estimatedCostnumber | null

      Dollars for the whole order, signed: what a debit pays is positive, what a credit takes in is negative. A resting order is estimated at its limit, one that would fill now at the natural.

    • estimatedTransactionFeenumber | null

      Dollars the fill pays in fees.

    • buyingPowerAfternumber | null

      Your simulated buying power after the fill, collateral included.

    • quotePricenumber | null

      The natural price per spread right now. null when a leg has no live quote (warnings says why).

    • quoteTimestring | nulldate-time

      When the newest leg quote was taken. null with quotePrice.

    • warningsstring[]

      Anything to know before you place. [] when there's nothing.

    • confirmationTokenstring

      Send it back with the place (or the modify). It only fits this exact ticket.

    • clientOrderIdstringuuid

      Send it back with the place.

  • metaobjectrequired
    • accountstring
      main

Last updated

Was this page helpful?