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

TWAP Execution

Install and import#

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

Signature#

twapExecution(total_quantity, start_time_ms, end_time_ms, bucket_count, lot_size)

Splits an order into equal slices across equal time buckets. The simplest schedule and the most predictable — predictable enough that it can be detected and traded against, which is the argument for the volume-based alternatives.

Parameters#

NameTypeNotes
total_quantitynumberTotal quantity to execute.
min: 1 · integer: true
start_time_msnumberSchedule start, epoch milliseconds.
end_time_msnumberSchedule end, epoch milliseconds.
bucket_countnumberNumber of time buckets.
min: 1 · integer: true
lot_sizenumberLot size; slices round to it and the remainder must be placed somewhere explicit.
min: 1 · integer: true

Returns#

{ schedule, bucket_quantity, remainder_placement, … }

The child-order schedule with how the lot-rounding remainder was distributed.

Errors#

  • When end_time_ms is not after start_time_ms, or bucket_count is not positive — 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
12000
start_time_ms
0
end_time_ms
1440000
bucket_count
24
lot_size
100

Call#

twapExecution(total_quantity, start_time_ms, end_time_ms, bucket_count, lot_size)

Returns#

object with 7 fields: total_quantity, lot_size, bucket_count, scheduled_quantity, remaining_quantity, schedule, state

{
  "total_quantity": 12000,
  "lot_size": 100,
  "bucket_count": 24,
  "scheduled_quantity": 12000,
  "remaining_quantity": 0,
  "schedule": [
    {
      "bucket": 1,
      "start_time_ms": 0,
      "end_time_ms": 60000,
      "target_quantity": 500,
      "target_cumulative_quantity": 500
    },
    {
      "bucket": 2,
      "start_time_ms": 60000,
      "end_time_ms": 120000,
      "target_quantity": 500,
      "target_cumulative_quantity": 1000
    },
    {
      "bucket": 3,
      "start_time_ms": 120000,
      "end_time_ms": 180000,
      "target_quantity": 500,
      "target_cumulative_quantity": 1500
    }
  ],
  "state": "complete-schedule"
}

Other exports#

This module also exports historicalVwapExecution, 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#

TWAP Execution — system map

Calculation flow#

TWAP Execution calculation flow 
flowchart LR
    S1["Validate parent lot horizon and bucket count"]
    S2["Convert parent to lots"]
    S3["Assign equal base lots"]
    S4["Distribute residual lots by stable bucket order"]
    S5["Build exact time boundaries and cumulative targets"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"available lots versus bucket count"}
    D --> O["schedule + diagnostics"]
    O --> A["Audit: Every target is lotaligned"]

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#