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

Historical VWAP Execution

Install and import#

bash
npm install fintech-algorithms
ts
import { historicalVwapExecution } from "fintech-algorithms/execution-and-transaction-cost-analysis/schedule-based-execution/historical-vwap-execution";

Signature#

historicalVwapExecution(total_quantity, historical_bucket_volumes, lot_size, profile_id)

Distributes an order according to a historical intraday volume profile — heavier at the open and close. Assumes today resembles the profile, which is exactly the assumption that fails on event days.

Parameters#

NameTypeNotes
total_quantitynumberTotal quantity.
min: 1 · integer: true
historical_bucket_volumesnumber[]Historical volume per bucket, forming the profile.
lot_sizenumberLot size.
min: 1 · integer: true
profile_idstringIdentifier of the profile used, recorded so an execution can be explained after the fact.

Returns#

{ schedule, profile_weights, profile_id, … }

The schedule with the profile weights that produced it.

Errors#

  • When the historical volumes sum to zero — throws

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

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#

total_quantity
24000
historical_bucket_volumes
[2400, 2000, 1700, 1500, 1300, 1200]

Showing 6 of 24 elements.

lot_size
100
profile_id
"SYN-24B-U-2026-07"

Call#

historicalVwapExecution(total_quantity, historical_bucket_volumes, lot_size, profile_id)

Returns#

object with 9 fields: profile_id, total_quantity, lot_size, bucket_count, historical_volume_total, scheduled_quantity, remaining_quantity, schedule, …

{
  "profile_id": "SYN-24B-U-2026-07",
  "total_quantity": 24000,
  "lot_size": 100,
  "bucket_count": 24,
  "historical_volume_total": 38250,
  "scheduled_quantity": 24000,
  "remaining_quantity": 0,
  "schedule": [
    {
      "bucket": 1,
      "historical_volume": 2400,
      "historical_weight": 0.062745098039,
      "target_quantity": 1500,
      "target_cumulative_quantity": 1500
    },
    {
      "bucket": 2,
      "historical_volume": 2000,
      "historical_weight": 0.052287581699,
      "target_quantity": 1300,
      "target_cumulative_quantity": 2800
    },
    {
      "bucket": 3,
      "historical_volume": 1700,
      "historical_weight": 0.044444444444,
      "target_quantity": 1100,
      "target_cumulative_quantity": 3900
    }
  ],
  "state": "complete-schedule"
}

Other exports#

This module also exports twapExecution, adaptiveVwapExecution, percentageOfVolumeExecution, 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#

Historical VWAP Execution — system map

Calculation flow#

Historical VWAP Execution calculation flow 
flowchart LR
    S1["Validate parent lot profile ID and volume array"]
    S2["Sum historical volume"]
    S3["Compute each buckets ideal lot numerator"]
    S4["Allocate base lots and rank fractional remainders"]
    S5["Emit cumulative targets and profile lineage"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"zeroweight buckets and tied remainder allocation"}
    D --> O["schedule + diagnostics"]
    O --> A["Audit: Weights sum to one within displayed rounding"]

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 Schedule-Based Execution family#