2.8 PartialFillHandler

1. Bot Identity

Operational profile

2. Purpose

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.

3. Why This Bot Matters

• 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.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "default_policy": "hold" }

if params.default_policy == 'chase': submitChaseOrder(remainder, book)

{ "min_remainder_size": 5 }

if remaining_usd < params.min_remainder_size: cancelRemainder(order)

{ "chase_max_ticks": 3 }

if ticksToFill > params.chase_max_ticks: cancelRemainder(order)

{ "cancel_on_book_thin": true }

if bookDepth < remaining_usd and params.cancel_on_book_thin: cancelRemainder(order)

8. Default Configuration

{
  "bot_id": "exec.partialfillhandler",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "default_policy": "hold",
    "min_remainder_size": 5,
    "chase_max_ticks": 3,
    "cancel_on_book_thin": true
  },
  "locked": {
    "min_remainder_size": {
      "min": 1
    },
    "chase_max_ticks": {
      "max": 10
    }
  }
}

9. Implementation Flow

1. Receive PARTIAL ExecutionReport from OrderLifecycleManager with remaining_usd, original_price, market_id.
2. Check KillSwitch; if active, cancel remainder via clob_auth and return.
3. If remaining_usd < min_remainder_size: forward to DustAndRoundingCleaner; cancel remainder.
4. Fetch CLOB V2 top-of-book from clob_public; compute book_depth on order side.
5. If cancel_on_book_thin and book_depth < remaining_usd: cancel remainder; emit PARTIAL_FILL_BOOK_THIN_CANCEL.
6. Apply default_policy: hold → leave remainder; cancel → cancel remainder; chase → compute ticks to fill.
7. If chase: if ticks_to_fill > chase_max_ticks, cancel; else cancel remainder and submit new order at current best price via CancelReplaceOptimizer.
8. Emit ExecutionReport with verdict, policy applied, remaining_usd, and reason_code.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION handlePartial(execReport):
  ks = FETCH internal.killswitch.status
  IF ks.active:
    clob_auth.DELETE('/order/' + execReport.order_id)
    EMIT ExecutionReport(KILL_SWITCH_ACTIVE)
    RETURN

  remaining = execReport.remaining_usd
  IF remaining < params.min_remainder_size:
    clob_auth.DELETE('/order/' + execReport.order_id)
    EMIT ExecutionReport(PARTIAL_FILL_DUST_AUTO_CANCEL)
    RETURN

  book = FETCH clob_public.GET('/book?market=' + execReport.market_id)
  bookDepth = SUM(level.size FOR level IN book.side(execReport.side)[:5])

  IF params.cancel_on_book_thin AND bookDepth < remaining:
    clob_auth.DELETE('/order/' + execReport.order_id)
    EMIT ExecutionReport(PARTIAL_FILL_BOOK_THIN_CANCEL)
    RETURN

  policy = execReport.strategy.partial_fill_policy OR params.default_policy

  IF policy == 'hold':
    EMIT ExecutionReport(HOLD_REMAINDER)
  ELIF policy == 'cancel':
    clob_auth.DELETE('/order/' + execReport.order_id)
    EMIT ExecutionReport(CANCELLED_REMAINDER)
  ELIF policy == 'chase':
    bestPrice = book.best_ask IF execReport.side == 'BUY' ELSE book.best_bid
    ticksAway = abs(bestPrice - execReport.original_price) / market.tick_size
    IF ticksAway > params.chase_max_ticks:
      clob_auth.DELETE('/order/' + execReport.order_id)
      EMIT ExecutionReport(PARTIAL_FILL_CHASE_ABORTED)
    ELSE:
      clob_auth.DELETE('/order/' + execReport.order_id)
      newOrder = buildOrderTypedData({price: bestPrice, size: remaining,
                   builder: execReport.builder_code})
      clob_auth.POST('/order', sign(newOrder))
      EMIT ExecutionReport(CHASE_ORDER_SUBMITTED)

SDK calls used

• clob_public.GET('/book?market=' + market_id)
• clob_auth.DELETE('/order/' + order_id)
• clob_auth.POST('/order', signed_chase_order)
• buildOrderTypedData({price, size, builder_code})

Complexity: O(1) per partial fill event

11. Wire Examples

Input — what arrives on the wire

PARTIAL ExecutionReport from OrderLifecycleManager — exec.orderlifecyclemanager

{
  "order_id": "0xcccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000",
  "status": "PARTIAL",
  "filled_usd": 200,
  "remaining_usd": 250,
  "original_price": 0.62,
  "side": "BUY",
  "collateral": "pUSD",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000"
}

Output — what the bot emits

ExecutionReport — HOLD_REMAINDER

{
  "report_id": "rep_3c4d5e6f7a8b9c0d",
  "bot_id": "exec.partialfillhandler",
  "verdict": "HOLD_REMAINDER",
  "remaining_usd": 250,
  "policy_applied": "hold",
  "collateral": "pUSD",
  "evaluated_at_ms": 1746770100000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "report_id": "rep_3c4d5e6f7a8b9c0d",
  "trace_id": "trc_2b3c4d5e6f7a8b9c",
  "bot_id": "exec.partialfillhandler",
  "order_id": "0xcccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "filled_usd": 200,
  "remaining_usd": 250,
  "policy_applied": "hold",
  "verdict": "HOLD_REMAINDER",
  "collateral": "pUSD",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "evaluated_at_ms": 1746770100000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "order_id": "0xcccc3333dddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000",
  "remaining_usd": 250,
  "book_depth_usd": 800,
  "ticks_to_fill": 1,
  "policy_applied": "hold",
  "cancel_on_book_thin": true,
  "verdict": "HOLD_REMAINDER"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

State rebuilt from OrderLifecycleManager on restart via PARTIAL events.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.13 2.9

External services

23. Security Surfaces

Abuse vectors considered

• Injecting a PARTIAL event with inflated remaining_usd to trigger an oversized chase order
• Forcing book-thin cancel by poisoning the book depth snapshot

Mitigations

• PARTIAL ExecutionReport validated against OrderLifecycleManager HMAC
• Chase order size capped at original remaining_usd; cannot exceed intent size

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

PartialFillHandler incidents are usually high dust-cancel rates (strategy sizing too small) or chase-abort spikes (market moving too fast for chase policy).

On-call actions

Manual overrides

• polytraders bot cancel-remainder exec.partialfillhandler --order <order_id> — Manual remainder cancellation needed when auto-policy is stuck.

Healthcheck

GET /internal/health/partialfillhandler → green if clob_auth reachable, clob_public reachable, dust_cancel_rate < 0.2/min, chase_abort_rate < 0.1/min; red if clob_auth unreachable, dust_cancel_rate > 1/min, chase_abort_rate > 0.5/min

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%