> ## Documentation Index > Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get contract recommendation > Recommend optimal options contracts based on entry signal and criteria. ## Algorithm The contract recommender uses a multi-factor scoring algorithm: 1. **Delta proximity (30%)**: Closeness to target delta 2. **Spread quality (25%)**: Tighter bid-ask spreads score higher 3. **Liquidity (20%)**: Volume-based soft scoring (OI gates hard filtering at SQL layer, see #339) 4. **DTE fit (20%)**: Preference for middle of DTE range ## Parameters - **symbol**: Stock ticker (e.g., 'AAPL') - **direction**: Trade direction ('bullish' or 'bearish') - **target_delta**: Target absolute delta (default 0.30) - **dte_min**: Minimum days to expiration (default 7) - **dte_max**: Maximum days to expiration (default 21) - **max_spread_pct**: Maximum bid-ask spread (default 0.10 = 10%) ## Response Returns primary recommendation with alternatives, including: - Contract details (strike, expiration, Greeks) - Pricing (bid, ask, spread) - Liquidity metrics (volume, liquidity score) - Selection rationale and warnings ## Liquidity Scoring (volume + spread based; OI is used at the SQL hard gate, see #339) - **EXCELLENT**: Spread < 3%, Volume > 500 - **GOOD**: Spread < 5%, Volume > 200 - **ACCEPTABLE**: Spread < 10%, Volume > 50 - **POOR**: Below acceptable thresholds ## OpenAPI ````yaml /api/openapi.json get /api/options/v1/contracts/recommend openapi: 3.1.0 info: title: Sequency Graph API description: > # Sequency Graph-Native Trading API Graph-native API for trading intelligence, built on FalkorDB. ## Features - **Screener**: Filter stocks using graph-native queries with relationship expansion - **Stock Detail**: Complete stock context with all relationships - **Confluence Scoring**: Setup quality assessment with weighted components - **Strategy Matching**: Find matching options strategies via graph traversal - **Market Context**: Current market-wide context for trading decisions ## Data Sources All data is sourced from the FalkorDB knowledge graph, populated by: - Pattern detector (Go) - Technical indicators, patterns - Graph sync service - Levels, volume profiles, news, day classification version: 1.0.0 servers: [] security: [] paths: /api/options/v1/contracts/recommend: get: tags: - Options summary: Get contract recommendation description: >- Recommend optimal options contracts based on entry signal and criteria. ## Algorithm The contract recommender uses a multi-factor scoring algorithm: 1. **Delta proximity (30%)**: Closeness to target delta 2. **Spread quality (25%)**: Tighter bid-ask spreads score higher 3. **Liquidity (20%)**: Volume-based soft scoring (OI gates hard filtering at SQL layer, see #339) 4. **DTE fit (20%)**: Preference for middle of DTE range ## Parameters - **symbol**: Stock ticker (e.g., 'AAPL') - **direction**: Trade direction ('bullish' or 'bearish') - **target_delta**: Target absolute delta (default 0.30) - **dte_min**: Minimum days to expiration (default 7) - **dte_max**: Maximum days to expiration (default 21) - **max_spread_pct**: Maximum bid-ask spread (default 0.10 = 10%) ## Response Returns primary recommendation with alternatives, including: - Contract details (strike, expiration, Greeks) - Pricing (bid, ask, spread) - Liquidity metrics (volume, liquidity score) - Selection rationale and warnings ## Liquidity Scoring (volume + spread based; OI is used at the SQL hard gate, see #339) - **EXCELLENT**: Spread < 3%, Volume > 500 - **GOOD**: Spread < 5%, Volume > 200 - **ACCEPTABLE**: Spread < 10%, Volume > 50 - **POOR**: Below acceptable thresholds operationId: recommend_contracts_api_options_v1_contracts_recommend_get parameters: - name: symbol in: query required: true schema: type: string minLength: 1 maxLength: 10 description: Stock ticker symbol (e.g., 'AAPL') title: Symbol description: Stock ticker symbol (e.g., 'AAPL') - name: direction in: query required: true schema: type: string pattern: ^(bullish|bearish)$ description: 'Trade direction: ''bullish'' or ''bearish''' title: Direction description: 'Trade direction: ''bullish'' or ''bearish''' - name: target_delta in: query required: false schema: type: number maximum: 0.9 minimum: 0.1 description: Target absolute delta (0.10 - 0.90) default: 0.3 title: Target Delta description: Target absolute delta (0.10 - 0.90) - name: dte_min in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Minimum days to expiration default: 7 title: Dte Min description: Minimum days to expiration - name: dte_max in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Maximum days to expiration default: 21 title: Dte Max description: Maximum days to expiration - name: max_spread_pct in: query required: false schema: type: number maximum: 0.5 minimum: 0.01 description: Maximum bid-ask spread as decimal (0.10 = 10%) default: 0.1 title: Max Spread Pct description: Maximum bid-ask spread as decimal (0.10 = 10%) - name: min_volume in: query required: false schema: type: integer minimum: 0 description: Minimum daily volume default: 50 title: Min Volume description: Minimum daily volume responses: '200': description: Contract recommendations content: application/json: schema: $ref: >- #/components/schemas/app__services__contract_recommender__ContractRecommendationResponse '422': description: Invalid parameters components: schemas: app__services__contract_recommender__ContractRecommendationResponse: properties: symbol: type: string title: Symbol direction: type: string title: Direction criteria: additionalProperties: true type: object title: Criteria primary_recommendation: anyOf: - $ref: '#/components/schemas/ContractRecommendation' - type: 'null' alternatives: items: $ref: '#/components/schemas/ContractRecommendation' type: array title: Alternatives no_suitable_contracts_reason: anyOf: - type: string - type: 'null' title: No Suitable Contracts Reason type: object required: - symbol - direction - criteria - primary_recommendation title: ContractRecommendationResponse description: Response containing contract recommendations. ContractRecommendation: properties: symbol: type: string title: Symbol contract_symbol: type: string title: Contract Symbol option_type: type: string title: Option Type description: '''call'' or ''put''' strike: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Strike expiration: type: string format: date title: Expiration dte: type: integer title: Dte delta: type: number title: Delta gamma: type: number title: Gamma theta: type: number title: Theta vega: type: number title: Vega rho: anyOf: - type: number - type: 'null' title: Rho iv: type: number title: Iv bid: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Bid ask: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Ask mid: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Mid spread_pct: type: number title: Spread Pct open_interest: anyOf: - type: integer - type: 'null' title: Open Interest volume: type: integer title: Volume liquidity_score: $ref: '#/components/schemas/LiquidityScore' score: type: number maximum: 100 minimum: 0 title: Score description: Overall recommendation score 0-100 selection_rationale: type: string title: Selection Rationale warnings: items: type: string type: array title: Warnings type: object required: - symbol - contract_symbol - option_type - strike - expiration - dte - delta - gamma - theta - vega - iv - bid - ask - mid - spread_pct - volume - liquidity_score - score - selection_rationale title: ContractRecommendation description: Recommended options contract with full details. LiquidityScore: type: string enum: - excellent - good - acceptable - poor title: LiquidityScore description: >- Liquidity quality classification (currently spread + volume based). Note: OI is now available from MSE's Trading API collector but the soft scoring in `_calculate_liquidity_score` has not yet been upgraded to use it. The SQL hard gates DO use OI (see #339). ````