PartialFillHandler

exec.partialfillhandler

Execution planned Spec started frozen

PartialFillHandler decides what to do with the unfilled remainder after a partial fill: hold and wait, cancel the remainder, or chase the market by su

What it does

PartialFillHandler decides what to do with the unfilled remainder after a partial fill: hold and wait, cancel the remainder, or chase the market by submitting a new order. It respects the strategy's declared partial-fill policy and current book state.

Pipeline placement

runs after: OrderLifecycleManager (PARTIAL event received) → PartialFillHandler → runs before: CancelReplaceOptimizer (if remainder requires a new order)

Applies to: Every PARTIAL fill event with a non-zero remainder

Why it matters

If this fails	Consequence
Remainder left resting indefinitely	Capital locked in a GTC order that will never fill at the original price if the market has moved; position budget exhausted.
Remainder always cancelled	Aggressive cancel policy causes the strategy to underfill its intended position size, leading to execution shortfall.
Chase price too aggressive	Chasing too many ticks above the original price to fill the remainder results in a worse blended fill price than if the order had been left resting.

Inputs

Polymarket inputs

Input	Source	Required	Use
CLOB V2 top-of-book snapshot	clob_public	required	Determine current best bid/ask to decide whether book is thin and whether chasing is viable.
Recent fill rate on market	ws_market	optional	Estimate time-to-fill for remainder if left resting.

Internal inputs

Input	Source	Required	Use
PARTIAL ExecutionReport from OrderLifecycleManager	exec.orderlifecyclemanager	required	Get remaining_usd, original price, market_id, and strategy partial-fill policy.
KillSwitch active flag	risk.kill_switch	required	Cancel remainder immediately if KillSwitch active; emit no new order.

Authority

What this bot is permitted to do

Reshape

State

Readiness

Spec started

Status

planned

Class

Execution Utility

Default mode

shadow_only

Developer owner

Polytraders core — Execution pod

Capital impact

Direct

Reason codes emitted

Code	Severity	Meaning	Action
HOLD_REMAINDER	INFO	Remainder left resting on book per hold policy.	No action; emit ExecutionReport.
PARTIAL_FILL_DUST_AUTO_CANCEL	HARD_REJECT	Remainder below min_remainder_size; auto-cancelled.	Cancel order; forward to DustAndRoundingCleaner.
PARTIAL_FILL_BOOK_THIN_CANCEL	WARN	Book depth < remaining_usd and cancel_on_book_thin=true.	Cancel remainder.
PARTIAL_FILL_CHASE_ABORTED	WARN	Chase ticks exceeded chase_max_ticks; remainder cancelled instead.	Cancel remainder; do not chase.
KILL_SWITCH_ACTIVE	HARD_REJECT	KillSwitch active; remainder cancelled immediately.	Cancel remainder; halt.

Related bots in Execution

exec.antitoxicfill exec.cancelreplaceoptimizer exec.dustandroundingcleaner

Used by

Reverse index — strategies that currently reference exec.partialfillhandler. If you change this bot's authority or reason codes, these strategies must re-pass shadow.

Strategy	State	Activity
BTC weekly — close-aware quotes	demo-wired	last triggered 27m ago
Fed Rates — surprise drift	frozen	last triggered 34m ago

Showing 2 of 2 · demo-wired ≠ production-live

Why this matters

Execution bots does NOT propose new positions; only routes and shapes approved intents. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →

Polytraders Operator UX Mock · INTERNAL · demo-wired ≠ production-live · the plan · reason codes · shadow-mode pipeline