Nexus/API Reference/Spreads

Place a spread order

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

Places the ticket you previewed. Send it unchanged, with the preview's confirmationToken and clientOrderId. A ticket that isn't what the preview priced answers 409 preview_mismatch: preview it again. Sending the same place twice answers the same order: nothing is placed twice.

A limit that crosses the natural fills now; otherwise it rests until it fills, you cancel it, or it expires (DAY at the close, GTC stays). The answer is the order: status is FILLED or WORKING. One recorded as rejected as it was placed answers 422 with its orderId.

Resting cap. Your resting API orders (stops included) and every working spread order count together toward 50, spread orders you placed on the Spreads ticket in Nexus included. Past it: 409 working_order_limit. Open spreads don't count toward the 50 open positions cap.

To close, place a CLOSE ticket: the legs you hold with their sides flipped.

curl -s -X POST "https://app.skylit.ai/api/nexus/v1/spreads/orders" \
  -H "Authorization: Bearer $SKYLIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientOrderId":"da4f696b-acbc-47a8-a906-43bec1db4915","confirmationToken":"335d58b5d86d9c2922d56922534bab419724c7bfa7ac5ed8ea0db6171b9d8be9","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.

  • confirmationTokenstringrequired

    From the preview of this exact ticket.

  • clientOrderIdstringrequired

    From the same preview. Sending the same place again answers that same order: nothing is placed twice.

Responses

  • 200

    The order.

  • 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

    One spread order, as every spread order route and the live stream return it. A figure that hasn't happened yet is null, never 0.

    • orderIdstringuuid
    • clientOrderIdstring
    • accountstring
      main
    • strategystring
    • underlyingstring
    • positionEffectstring
      OPENCLOSE
    • netEffectstring
      DEBITCREDIT
    • orderTypestring
      LIMITMARKET
    • timeInForcestring
      DAYGTC
    • quantityinteger
    • filledQuantityinteger
    • limitPricenumber | null

      Per spread. null on a market order.

    • averageFillPricenumber | null

      The net per spread it filled at. null until it fills.

    • realizedPnlnumber | null

      Dollars a filled close made or lost. null on an open, and until a close fills.

    • feesnumber | null

      Dollars the fill paid. null before it fills.

    • statusstring

      Upper case, as on the Spreads ticket in Nexus.

      WORKINGFILLEDCANCELLEDREJECTEDEXPIRED
    • cancellableboolean

      true while it rests.

    • receivedAtstring | nulldate-time
    • messagestring | null

      Why it was rejected or ended, when there's a reason.

    • legsobject[]
  • metaobjectrequired
    • accountstring
      main

Last updated

Was this page helpful?