Docs
Nexus/API Reference/Options and stocks

Open a trade (options, stocks or futures)

POSThttps://app.skylit.ai/api/nexus/v1/trades

One route for every asset class. assetClass picks the book.

  • Options are bought to open, at market. Send contract as shorthand (like SPY 600C 10/16), or ticker, strike, direction and expiration. Not both. 1 to 1,000 contracts.
  • Stocks take ticker, side (buy or sell) and quantity, 1 to 100,000 shares, at market.
  • Futures take ticker (a product like NQ for the front month, or one contract like NQZ26), side, quantity (1 to 100) and optionally account. A market order fills now. orderType: "limit" with limitPrice, or "stop" with stopPrice, rests until the market trades through it. Add stopLoss, takeProfit and trailingStop for a bracket on any order type: each leg is an order of its own, held while the entry rests and working once it fills. A resting order can wait on a quiet market. A market order needs a trade in the last 15 seconds to open or add.
  • reduceOnly stops a sell from opening a short when a stop already took you flat a second earlier. With reduceOnly: true the order goes through only if it shrinks what you hold, checked when it books. Otherwise it answers 422 reduce_only_would_open and nothing is placed. It works on a market order with no bracket.
  • Futures go to your practice account unless account names another: "evaluation" or "funded" when you have exactly one running, or an account id from capabilities. Evaluation and funded accounts keep all their rules (daily loss, max loss, contract cap). Challenge entries can't be traded through the API.
  • Add "test": true to check and price the order without placing it. See Test orders in the intro.

A new options or stock trade answers 201 with the trade. A futures order answers 201 with the order and its bracket. A repeated clientOrderId answers 200 with the first one.

Authorization

Authorization: Bearer <your API key>

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

Headers

  • Idempotency-Keystring

    Your clientOrderId, as a header instead of a body field. If you send both they must match.

Request body

  • assetClassstring

    Which book the order goes to.

    optionsstocksfutures
  • contractstring

    Options shorthand, like SPY 600C 10/16 or SPY 600C 10/16 @ 1.84. Send this, or ticker, strike, direction and expiration.

  • tickerstring

    A symbol like SPY. For futures, a product like NQ (the front month) or one contract like NQZ26.

  • directionstring

    Options only.

    callput
  • strikenumber

    Options only, like 600 or 602.5.

  • expirationstringdate

    Options only, like 2026-10-16.

  • sidestring

    Stocks and futures. Options are always bought to open.

    buysell
  • quantityinteger

    Options 1 to 1,000 contracts, stocks 1 to 100,000 shares, futures 1 to 100 contracts.

  • pricenumber

    Options and stocks: your own fill price, taken only inside the window around the live quote.

  • ifOutsidestring

    What happens when price is outside the window: refuse, or fill at market.

    rejectmarket
  • orderTypestring

    Options and stocks take market only. Futures also take limit (with limitPrice) and stop (with stopPrice).

    marketlimitstop
  • limitPricenumber

    Futures limit orders: the price the order rests at.

  • stopPricenumber

    Futures stop orders: the price that triggers it.

  • stopLossnumber

    Futures: a stop loss placed with the entry.

  • takeProfitnumber

    Futures: a take profit placed with the entry.

  • trailingStopboolean

    Futures: the stop loss trails the price. Needs stopLoss.

  • reduceOnlyboolean

    Futures: only take contracts off a position you hold, never open, add or flip. Market orders with no bracket.

  • accountstring

    Futures: practice (the default), evaluation, funded, or an account id.

  • clientOrderIdstring

    Your own id for safe retries. 1 to 64 letters, digits, or _ . : -.

  • testboolean

    true checks and prices the order, then keeps it in your test log instead of placing it.

Responses

  • 200

    A repeated clientOrderId: the first order, with meta.idempotentReplay: true. Nothing new was placed.

  • 201

    Filled (or, for a futures limit or stop order, resting). Options and stocks answer a Trade, futures a FuturesOrder. A test order is the same shape with "test": true.

  • 400

    The request was refused before anything was traded. Codes: bad_request, bad_contract, invalid_quantity, invalid_price, unsupported_asset_class, unsupported_order_type, only_market_orders, test_orders_unavailable, test_modify_unavailable.

  • 401

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

  • 403

    The key works but the account can't do this. Codes: account_suspended, nexus_access_denied, futures_access_denied.

  • 404

    Not on your account. Codes: trade_not_found, account_not_found, order_not_found.

  • 409

    The order clashes with what you hold or sent before. Codes: duplicate_position (with tradeId), trade_closed, open_position_limit, client_order_id_used, request_in_progress, account_locked, account_busy, account_ended, order_not_working.

  • 422

    Read fine, but the market or the account says no. Codes: market_closed, contract_expired, contract_not_offered, price_outside_market, insufficient_buying_power, account_not_tradable, account_ambiguous, reduce_only_would_open, order_refused.

  • 429

    Over a rate limit. Wait Retry-After seconds, then retry. Code: rate_limited.

  • 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 (honour Retry-After when it's sent). Codes: stale_quote, no_live_price, rules_pending, unavailable, auth_unavailable, access_check_unavailable, api_keys_unavailable, trades_api_disabled.

Response fields

  • dataobject

    An options or stock trade, as Nexus shows it. Stocks use direction call for long and put for short, strike 0 and today's date. Nexus may add other fields it shows on a trade (Greeks, P/L, reactions).

    • idstringuuid
    • userIdstringuuid
    • tickerstring
    • strikenumber
    • expirationstringdate
    • directionstring
      callput
    • assetClassstring
      optionsstocks
    • averageEntryPricenumber
    • currentPricenumber

      The latest mark.

    • totalQuantityinteger
    • remainingQuantityinteger
    • statusstring
      activeclosed
    • entryDatestringdate-time
    • exitDatestringdate-time
    • exitsobject[]
    • sourcestring

      api on a trade a key opened.

    • testboolean

      true on a test order.

  • metaobject

    Extra facts about an order. Each field is there only when it applies.

    • fillobject

      The fill: price, priceSource (market or client), and when you sent a price, the bid and ask it was checked against. On an exit, quantity is how many sold.

    • clientOrderIdstring
    • idempotentReplayboolean

      This answer is a repeat of an earlier order with the same clientOrderId.

    • testboolean

      A test order: nothing was placed.

    • notCheckedstring[]

      Futures test orders: what the preview couldn't check, like account_rules_judgment or bracket_netting.

    • discordRoutingobject

      Where Nexus routed the trade to Discord, when it did.

    • nothingToCloseboolean
    • stillOpenstring[]

      A repeated closeAll: positions still open.

Last updated

Was this page helpful?