DocsAPI ReferenceWheelOptimal Roll

Optimal Roll

Ranked roll candidates for an option position, credit spread or LEAP, and the best roll for each of your open positions, scored by the same engine as the Wheel Roll tab.

Rolls for your positions

GET/positions/rolls

The Wheel Roll tab as data. Every rollable position you hold (cash-secured puts, covered calls, collars, PMCCs, short and long puts and calls, bull put and bear call spreads) comes back with its roll leg, days to expiry, how far in the money it is, and bestRoll. That is the highest-rated roll to a better strike for a net credit, narrowed by your roll suggestion preferences, or null when none qualifies. Pass findRollsArgs as query parameters to /optimal-roll for the full table. The MCP tool get_roll_suggestions returns the same payload.

Parameters

symbolstring

Only this ticker.

accountIdstring

Only this account (from /positions).

curl -H "Authorization: Bearer qw_live_YOUR_KEY" \
  "https://quantwheel.com/api/v1/positions/rolls"

200 OK (abridged)

{
  "asOf": "2026-10-22T14:59:12.000Z",
  "positions": [
    {
      "ticker": "SPY",
      "strategy": "Cash Secured Put",
      "accountId": "acc_1",
      "accountName": "Schwab",
      "rollLeg": {
        "strike": 550, "expiration": "2026-10-24", "optionType": "PUT", "side": "short",
        "contracts": 1, "daysToExpiry": 2, "underlyingPrice": 546.1, "itmPercent": 0.71
      },
      "supported": true,
      "bestRoll": {
        "newStrike": 545, "netPremium": 0.42, "daysExtension": 7,
        "yearlyYield": 18.4, "equityReleasedPercent": 0.91, "alternativesCount": 6
      },
      "findRollsArgs": {
        "kind": "single", "ticker": "SPY", "expiration": "2026-10-24",
        "strike": 550, "optionType": "put", "side": "short"
      }
    }
  ]
}

Suggestions, not orders

Rolls never trade. To roll, close the current leg and open the new one with a previewed order. Canadian-listed contracts come back with supported: false: US options data cannot price their rolls.

Get roll candidates

GET/optimal-roll

Parameters

symbolstringrequired

Underlying ticker.

strikenumberrequired

Current strike.

expirationdaterequired

Current expiration (YYYY-MM-DD).

optionTypestringrequired

put or call.

positionSidestring

short (default) or long.

strikeExtensionnumber

Short positions: widen the strike search by this percent past the current strike (0 to 40).

ticker and side work as aliases of symbol and positionSide, so findRollsArgs passes straight through. The MCP tool find_rolls takes the same fields.

curl -H "Authorization: Bearer qw_live_YOUR_KEY" \
  "https://quantwheel.com/api/v1/optimal-roll?symbol=NVDA&strike=120&expiration=2026-08-15&optionType=put"

Response

Candidates come from live options chains and are ranked best-first. Fields vary slightly between short and long positions.

200 OK (abridged)

{
  "ticker": "NVDA",
  "currentExpiration": "2026-08-15",
  "currentStrike": 120,
  "optionType": "put",
  "positionSide": "short",
  "stockPrice": 124.9,
  "currentBid": 1.85,
  "currentAsk": 1.95,
  "currentMid": 1.9,
  "opportunities": [
    {
      "newExpiration": "2026-09-19",
      "newStrike": 115,
      "netPremium": 1.45,
      "yield": 0.42,
      "yearlyYield": 15.3,
      "rating": 91,
      "riskOfAssignment": 0.12,
      "equityReleased": 500,
      "pnlImprovement": 145.0
    }
    // ranked candidates; rows also carry indicative bid/ask, IV and greeks
    // for the specific contracts being evaluated
  ]
}

Spreads and LEAPs

Add kind to roll a credit spread as a unit or a long call LEAP to another LEAP, the same tables the Wheel Roll tab shows for those positions. Both need a Pro plan. Results are the best 20 by rating; pass limit for fewer.

Parameters

kindstring

single (default), spread or leap.

spreadKindstring

spread: PUT_CREDIT (bull put) or CALL_CREDIT (bear call).

shortStrike / longStrikenumber

spread: current strikes. The long leg is further out of the money.

strikenumber

leap: current strike.

quantitynumber

Contracts, for dollar totals (default 1).

allowWidthChange / minWidth / maxWidthboolean / number

spread: allow a different width, within these bounds.

strikeExtensionnumber

spread: widen the strike search (0 to 40 percent).

allowShorterDteboolean

leap: allow a nearer expiration that is still a LEAP.

limitnumber

Candidates returned, 1 to 20 (default 20).

curl -H "Authorization: Bearer qw_live_YOUR_KEY" \
  "https://quantwheel.com/api/v1/optimal-roll?kind=spread&symbol=QQQ&expiration=2026-10-24&spreadKind=PUT_CREDIT&shortStrike=480&longStrike=470&quantity=2"

Spread candidates carry closeCost, newCredit and netCredit per share (natural and Mid), netCreditDollars, the new strikes and width, and daysExtension. LEAP candidates carry the new strike, expiration and DTE, netCredit (positive means cash out), the delta and breakeven change, and a rating.

What the score weighs

Input	Why it matters
netPremium	Rolls should pay you, not the market maker.
yearlyYield	Time added vs. credit received, annualized.
riskOfAssignment	Derived assignment probability at the new strike.
equityReleased / pnlImprovement	Collateral freed and P&L improvement vs. holding.

Screener

Playground Trading