fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Opportunistic Dark-Pool Execution

Install and import#

bash
npm install fintech-algorithms
ts
import { opportunisticDarkPoolExecution } from "fintech-algorithms/execution-and-transaction-cost-analysis/cost-risk-optimization/opportunistic-dark-pool-execution";

Signature#

opportunisticDarkPoolExecution(input)

Walks a list of dark opportunities in order and, for each one, either plans a lot-aligned exposure or records the first gate that refused it: the fallback window has arrived, firm probability is below the threshold, price improvement is below the threshold, the indicated size is under the minimum, or the dark cap is exhausted. Everything left over is reported as lit fallback quantity. The gating is deterministic arithmetic; no fill rate, adverse-selection cost or reversion is estimated, and no venue is chosen.

Parameters#

NameTypeNotes
input{ total_quantity, lot_size, maximum_dark_fraction_bps, minimum_firm_probability_bps, minimum_price_improvement_atoms, minimum_execution_quantity, max_exposure_per_window, fallback_window, dark_opportunities }All scalars are integers. maximum_dark_fraction_bps and minimum_firm_probability_bps are basis points capped at 10000; minimum_execution_quantity and max_exposure_per_window must be multiples of lot_size. dark_opportunities is a nonempty array of { opportunity_id, window, indicated_quantity, firm_probability_bps, price_improvement_atoms }. There is no venue list and no reference price.

Returns#

{ total_quantity, maximum_dark_fraction_bps, dark_quantity_cap, planned_dark_exposure_quantity, lit_fallback_quantity, dark_opportunity_count, accepted_dark_window_count, opportunities, state }

The lot-floored dark cap, the total planned dark exposure, the residual routed to lit fallback, and a per-opportunity audit carrying the planned exposure, the expose-dark / fallback-active / firm-probability-below-threshold / price-improvement-below-threshold / minimum-size-not-met / dark-cap-reached reason and the remaining dark cap. state is dark-plan-complete when nothing falls back to lit, and lit-fallback-required otherwise.

Errors#

  • When inputs is not an object — throws
  • When total_quantity or lot_size is invalid, or total_quantity is not lot-aligned — throws
  • When a required scalar is missing, non-integer, or outside its positive/nonnegative range — throws
  • When maximum_dark_fraction_bps or minimum_firm_probability_bps exceeds 10000 — throws
  • When minimum_execution_quantity or max_exposure_per_window is not lot-aligned — throws
  • When dark_opportunities is missing or empty — throws
  • When an opportunity is not an object, lacks a nonempty opportunity_id, or holds an invalid window, quantity, probability or improvement — throws

Complexity: time O(opportunities), space O(opportunities).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

input
{
  "total_quantity": 6000,
  "lot_size": 100,
  "maximum_dark_fraction_bps": 6000,
  "minimum_firm_probability_bps": 7500,
  "minimum_price_improvement_atoms": 30,
  "minimum_execution_quantity": 300,
  "max_exposure_per_window": 1000,
  "fallback_window": 8,
  "dark_opportunities": [
    {
      "opportunity_id": "DK-01",
      "window": 1,
      "indicated_quantity": 500,
      "firm_probability_bps": 8200,
      "price_improvement_atoms": 50
    },
    {
      "opportunity_id": "DK-02",
      "window": 2,
      "indicated_quantity": 900,
      "firm_probability_bps": 7600,
      "price_improvement_atoms": 40
    },
    {
      "opportunity_id": "DK-03",
      "window": 3,
      "indicated_quantity": 300,
      "firm_probability_bps": 9100,
      "price_improvement_atoms": 60
    }
  ]
}

Call#

opportunisticDarkPoolExecution(input)

Returns#

object with 9 fields: total_quantity, maximum_dark_fraction_bps, dark_quantity_cap, planned_dark_exposure_quantity, lit_fallback_quantity, dark_opportunity_count, accepted_dark_window_count, opportunities, …

{
  "total_quantity": 6000,
  "maximum_dark_fraction_bps": 6000,
  "dark_quantity_cap": 3600,
  "planned_dark_exposure_quantity": 3300,
  "lit_fallback_quantity": 2700,
  "dark_opportunity_count": 10,
  "accepted_dark_window_count": 5,
  "opportunities": [
    {
      "opportunity_id": "DK-01",
      "window": 1,
      "indicated_quantity": 500,
      "firm_probability_bps": 8200,
      "price_improvement_atoms": 50,
      "planned_dark_exposure_quantity": 500,
      "reason": "expose-dark",
      "dark_cap_remaining_quantity": 3100
    },
    {
      "opportunity_id": "DK-02",
      "window": 2,
      "indicated_quantity": 900,
      "firm_probability_bps": 7600,
      "price_improvement_atoms": 40,
      "planned_dark_exposure_quantity": 900,
      "reason": "expose-dark",
      "dark_cap_remaining_quantity": 2200
    },
    {
      "opportunity_id": "DK-03",
      "window": 3,
      "indicated_quantity": 300,
      "firm_probability_bps": 9100,
      "price_improvement_atoms": 60,
      "planned_dark_exposure_quantity": 300,
      "reason": "expose-dark",
      "dark_cap_remaining_quantity": 1900
    }
  ],
  "state": "lit-fallback-required"
}

Other exports#

This module also exports almgrenChrissOptimalExecution, implementationShortfallExecution, arrivalPriceExecution, liquiditySeekingExecution, calculate. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Opportunistic Dark-Pool Execution — system map

Calculation flow#

Opportunistic Dark-Pool Execution calculation flow 
flowchart LR
    S1["Validate parent dark fraction thresholds lots fallback"]
    S2["Compute the total lotfloored dark cap"]
    S3["Before fallback accept only opportunities that pass pr"]
    S4["Cap each exposure and send the unexposed residual to t"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> D{"opportunity window exactly equal to the fallback window"}
    D --> O["planned_dark_exposure_quantity + diagnostics"]
    O --> A["Audit: Planned dark exposure never exceeds its cap"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Cost/Risk Optimization family#