Place a spread order
https://app.skylit.ai/api/nexus/v1/spreads/ordersPlaces 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
accountstringmainor left out. Any other account answers422 port_unsupported.mainportstringLeave it out. Spreads trade on your main account only, so any port answers
422 port_unsupported.strategystringrequiredWhat the legs form:
VERTICAL,STRADDLE,STRANGLE,BUTTERFLY,CONDOR,IRON_BUTTERFLY,IRON_CONDOR,CALENDAR,DIAGONAL,COVERED_STOCKorCOLLAR_WITH_STOCK.capabilities.spreads.strategieslists what you may open right now. Legs that form something else answer400 bad_request.positionEffectstringOPENwhen left out. A close sends the legs you hold with their sides flipped.OPENCLOSEnetEffectstringrequiredWhether this order pays (
DEBIT) or takes in (CREDIT).DEBITCREDITorderTypestringrequiredMARKETtakes the natural price now, is good for the day only, and takes nolimitPrice.LIMITMARKETtimeInForcestringrequiredGood for the day, or until cancelled. A market order is
DAYonly.DAYGTCquantityintegerrequiredSpreads, 1 to 100.
limitPricenumberLimit orders: the net price per spread, always positive (
netEffectsays which way). Leave it out on a market order.legsobject[]requiredassetClassstringoptionswhen left out.stocksis the shares leg of a covered stock or a collar.optionsstockstickerstringrequiredThe underlying. Every leg trades the same one.
expirationstring | nulldateOptions legs: the contract's expiration.
nullon shares.strikenumber | nullOptions legs: the strike.
nullon shares.directionstring | nullOptions legs:
callorput.nullon shares.callputnullsidestringrequiredThis leg's side on this order. To close, send the legs you hold with their sides flipped.
BUYSELLratiointegerrequiredContracts (or lots of shares) per spread.
confirmationTokenstringrequiredFrom the preview of this exact ticket.
clientOrderIdstringrequiredFrom 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'toptionsorstocks, legs that don't form thestrategy, a missinglimitPriceon a limit, a market order with one, a quantity over 100, a modify with neitherquantitynorlimitPrice, adatethat isn'tYYYY-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 sharedaccount_suspendedandnexus_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 butmain, or any port),insufficient_buying_power(withorderIdwhen the order was recorded as rejected),order_rejected(recorded as rejected as it was placed;orderIdpoints to it),contract_expired. - 429
Over a rate limit. Wait
Retry-Afterseconds, then retry. Codes:rate_limited, andstream_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
dataobjectrequiredOne spread order, as every spread order route and the live stream return it. A figure that hasn't happened yet is
null, never0.orderIdstringuuidclientOrderIdstringaccountstringmainstrategystringunderlyingstringpositionEffectstringOPENCLOSEnetEffectstringDEBITCREDITorderTypestringLIMITMARKETtimeInForcestringDAYGTCquantityintegerfilledQuantityintegerlimitPricenumber | nullPer spread.
nullon a market order.averageFillPricenumber | nullThe net per spread it filled at.
nulluntil it fills.realizedPnlnumber | nullDollars a filled close made or lost.
nullon an open, and until a close fills.feesnumber | nullDollars the fill paid.
nullbefore it fills.statusstringUpper case, as on the Spreads ticket in Nexus.
WORKINGFILLEDCANCELLEDREJECTEDEXPIREDcancellablebooleantruewhile it rests.receivedAtstring | nulldate-timemessagestring | nullWhy it was rejected or ended, when there's a reason.
legsobject[]
metaobjectrequiredaccountstringmain
Last updated