2.9 CancelReplaceOptimizer

1. Bot Identity

Operational profile

2. Purpose

CancelReplaceOptimizer selects the cheapest path to modify a resting order: amend-in-place if queue priority is preserved, or cancel-then-replace if the delta exceeds the amend threshold. It enforces rate-limit budgets across cancel and amend operations.

3. Why This Bot Matters

• Always using cancel-then-replace

  Loses queue position on every requote, resulting in consistently worse fills on passive strategies where queue position matters.

• Amend threshold set too wide

  Large price changes that would trigger queue-position loss are processed as amends, causing the strategy to hold a stale order at a position that was meant to be cancelled.

• Rate limit not enforced across cancels

  A burst of cancel-replace operations hits the CLOB V2 rate limit, causing 429 errors and leaving orders unmodified at stale prices.

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

{ "amend_threshold_ticks": 2 }

if deltaTicks > params.amend_threshold_ticks: cancelReplace(order)

{ "preserve_queue_when_possible": true }

if not params.preserve_queue_when_possible: cancelReplace(order)

{ "burst_max_per_s": 10 }

if opsThisSecond > params.burst_max_per_s: shedRequest()

{ "fallback_strategy": "cancel_replace" }

if amendFailed: cancelReplace(order) if params.fallback_strategy == 'cancel_replace'

8. Default Configuration

{
  "bot_id": "exec.cancelreplaceoptimizer",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "amend_threshold_ticks": 2,
    "preserve_queue_when_possible": true,
    "burst_max_per_s": 10,
    "fallback_strategy": "cancel_replace"
  },
  "locked": {
    "amend_threshold_ticks": {
      "max": 8
    },
    "burst_max_per_s": {
      "max": 20
    }
  }
}

9. Implementation Flow

1. Receive requote instruction: {order_id, current_price, target_price, target_size, market_id}.
2. Fetch tick size from clob_public; compute delta_ticks = abs(target_price - current_price) / tick_size.
3. Check rate-limit budget; if burst_max_per_s exceeded, shed request and emit CANCEL_REPLACE_RATE_LIMIT_SHED.
4. If preserve_queue_when_possible and delta_ticks <= amend_threshold_ticks: attempt amend via clob_auth PATCH /order/{id}.
5. If amend succeeds: emit ExecutionReport(AMEND_IN_PLACE); done.
6. If amend fails or delta_ticks > amend_threshold_ticks: cancel via clob_auth DELETE /order/{id}; submit new order at target_price/target_size.
7. Emit ExecutionReport with path_taken (amend or cancel_replace), delta_ticks, and rate_limit_budget_remaining.

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 optimizeCancelReplace(instruction):
  // 1. Fetch tick size
  market = FETCH clob_public.GET('/markets/' + instruction.market_id)
  tickSize = market.minimum_tick_size
  deltaTicks = abs(instruction.target_price - instruction.current_price) / tickSize

  // 2. Rate limit check
  IF rateLimiter.opsThisSecond >= params.burst_max_per_s:
    EMIT ExecutionReport(CANCEL_REPLACE_RATE_LIMIT_SHED, WARN)
    RETURN

  // 3. Decide path
  IF params.preserve_queue_when_possible
     AND deltaTicks <= params.amend_threshold_ticks:
    // Attempt amend
    result = clob_auth.PATCH('/order/' + instruction.order_id,
                              {price: instruction.target_price,
                               size: instruction.target_size})
    IF result.ok:
      EMIT ExecutionReport(AMEND_IN_PLACE)
      RETURN
    // Amend failed — fall through to cancel-replace

  // 4. Cancel-then-replace
  clob_auth.DELETE('/order/' + instruction.order_id)
  newOrder = buildOrderTypedData({
    price: instruction.target_price,
    size: instruction.target_size,
    builder: instruction.builder_code,
    timestamp: now_ms()
  })
  clob_auth.POST('/order', sign(newOrder))
  EMIT ExecutionReport(CANCEL_REPLACE_EXECUTED)

SDK calls used

• clob_public.GET('/markets/' + market_id)
• clob_auth.PATCH('/order/' + order_id, {price, size})
• clob_auth.DELETE('/order/' + order_id)
• clob_auth.POST('/order', signed_new_order)
• buildOrderTypedData({price, size, builder_code, timestamp})

Complexity: O(1) per requote instruction

11. Wire Examples

Input — what arrives on the wire

Requote instruction — exec.partialfillhandler

{
  "order_id": "0xdddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000eeee1111",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "current_price": 0.62,
  "target_price": 0.63,
  "target_size_usd": 250,
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "collateral": "pUSD"
}

Output — what the bot emits

ExecutionReport — amend in place

{
  "report_id": "rep_4d5e6f7a8b9c0d1e",
  "bot_id": "exec.cancelreplaceoptimizer",
  "path_taken": "amend_in_place",
  "delta_ticks": 1,
  "original_price": 0.62,
  "target_price": 0.63,
  "collateral": "pUSD",
  "evaluated_at_ms": 1746770200000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "report_id": "rep_4d5e6f7a8b9c0d1e",
  "trace_id": "trc_3c4d5e6f7a8b9c0d",
  "bot_id": "exec.cancelreplaceoptimizer",
  "order_id": "0xdddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000eeee1111",
  "path_taken": "amend_in_place",
  "delta_ticks": 1,
  "original_price": 0.62,
  "target_price": 0.63,
  "collateral": "pUSD",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "evaluated_at_ms": 1746770200000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "order_id": "0xdddd4444eeee5555ffff6666aaaa7777bbbb8888cccc9999dddd0000eeee1111",
  "delta_ticks": 1,
  "amend_threshold_ticks": 2,
  "path_taken": "amend_in_place",
  "rate_limit_budget_remaining": 8,
  "amend_success": true
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Rate counter resets on restart; conservative: assume full burst budget used until first tick completes.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Flooding with rapid requote instructions to exhaust rate limit budget and suppress legitimate order modifications
• Injecting a requote with a target_price far from market to trigger a forced cancel-replace that loses queue priority

Mitigations

• burst_max_per_s enforced atomically; excess requests shed with WARN before hitting CLOB rate limit
• target_price validated against PriceBandValidator before requote is accepted

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

CancelReplaceOptimizer incidents are typically rate-limit sheds (strategy generating too many requotes) or amend-endpoint failures causing unexpected cancel-replaces.

On-call actions

Manual overrides

• polytraders bot force-cancel-replace exec.cancelreplaceoptimizer --order <order_id> --price <price> — Manual cancel-replace needed when amend endpoint is persistently unavailable.

Healthcheck

GET /internal/health/cancelreplaceoptimizer → green if clob_auth reachable, rate_limit_shed_rate < 0.1/min, amend success rate > 80%; red if clob_auth unreachable, rate_limit_shed_rate > 1/min, amend success rate < 50%

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%