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

Liquidity-Seeking Execution

Install and import#

bash
npm install fintech-algorithms
ts
import { liquiditySeekingExecution } from "fintech-algorithms/execution-and-transaction-cost-analysis/cost-risk-optimization/liquidity-seeking-execution";

Signature#

liquiditySeekingExecution(input)

Trades opportunistically when liquidity appears rather than on a schedule. Completion time is uncertain by construction — the strategy trades schedule certainty for better prices.

Parameters#

NameTypeNotes
inputLiquiditySeekingInputQuantity, the liquidity signals to react to, minimum acceptable size, and the price limit beyond which liquidity is declined.

Returns#

{ opportunities, executed, remaining, completion_estimate, … }

Opportunities taken and passed, with the completion estimate that remains genuinely an estimate.

Errors#

  • When the minimum size exceeds the total quantity — throws

Complexity: time O(signals), 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": 4000,
  "side": "buy",
  "limit_price_atoms": 1000200,
  "minimum_confidence_bps": 7500,
  "maximum_age_ms": 50,
  "max_take_per_event": 700,
  "lot_size": 100,
  "liquidity_events": [
    {
      "event_id": "LQ-01",
      "price_atoms": 1000000,
      "available_quantity": 500,
      "age_ms": 12,
      "confidence_bps": 8500
    },
    {
      "event_id": "LQ-02",
      "price_atoms": 1000100,
      "available_quantity": 900,
      "age_ms": 18,
      "confidence_bps": 7800
    },
    {
      "event_id": "LQ-03",
      "price_atoms": 1000300,
      "available_quantity": 700,
      "age_ms": 8,
      "confidence_bps": 9200
    }
  ]
}

Call#

liquiditySeekingExecution(input)

Returns#

object with 9 fields: side, limit_price_atoms, total_quantity, accepted_quantity, remaining_quantity, accepted_event_count, rejected_event_count, events, …

{
  "side": "buy",
  "limit_price_atoms": 1000200,
  "total_quantity": 4000,
  "accepted_quantity": 4000,
  "remaining_quantity": 0,
  "accepted_event_count": 7,
  "rejected_event_count": 5,
  "events": [
    {
      "event_id": "LQ-01",
      "price_atoms": 1000000,
      "available_quantity": 500,
      "age_ms": 12,
      "confidence_bps": 8500,
      "planned_take_quantity": 500,
      "reason": "accepted",
      "remaining_quantity": 3500
    },
    {
      "event_id": "LQ-02",
      "price_atoms": 1000100,
      "available_quantity": 900,
      "age_ms": 18,
      "confidence_bps": 7800,
      "planned_take_quantity": 700,
      "reason": "accepted",
      "remaining_quantity": 2800
    },
    {
      "event_id": "LQ-03",
      "price_atoms": 1000300,
      "available_quantity": 700,
      "age_ms": 8,
      "confidence_bps": 9200,
      "planned_take_quantity": 0,
      "reason": "outside-limit",
      "remaining_quantity": 2800
    }
  ],
  "state": "parent-complete"
}

Other exports#

This module also exports almgrenChrissOptimalExecution, implementationShortfallExecution, arrivalPriceExecution, opportunisticDarkPoolExecution, 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#

Liquidity-Seeking Execution — system map

Calculation flow#

Liquidity-Seeking Execution calculation flow 
flowchart LR
    S1["Validate parent policy and event schema"]
    S2["Read events in callersupplied decision order"]
    S3["Reject stale lowconfidence outsidelimit or sublot even"]
    S4["Release capped quantity and update the residual parent"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> D{"confidence exactly equal to the minimum and age exactly eq"}
    D --> O["accepted_quantity + diagnostics"]
    O --> A["Audit: Accepted quantity plus remaining quantity equals the paren"]

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#