2.1 SmartRouter

1. Bot Identity

Operational profile

2. Purpose

SmartRouter translates an approved strategy intent into a concrete executable order by selecting the appropriate order type (FOK, GTC, or GTD), price, and timing. It may split a large order into iceberg child orders to reduce market impact. SmartRouter cannot change the direction of the trade, the target market, or the strategy intent — it is not permitted to flip the side (buy/sell), alter the outcome leg, or override any constraint set by the Risk guardrail pipeline. The only transformations it may make are to price, size scheduling, order type, and submission timing.

3. Why This Bot Matters

• Wrong order type applied

  A Fill-or-Kill order on a thin book will be rejected by the exchange and the strategy misses the opportunity entirely; a GTC order on a fast-moving market may fill at an outdated price.

• Large order submitted without iceberg splitting

  A single large visible order signals intent to other market participants and may be front-run or cause the book to refresh at a worse price before the order fills.

• Order submitted after signal TTL expires

  Executing a GTC or GTD order on a signal that has aged past its validity window means acting on market intelligence that may no longer be accurate.

• Tick size not respected

  An order with a price that does not align to the market's tick size will be rejected by the CLOB, resulting in a failed submission.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "default_order_type": "GTC" }

const type = intent.order_type || p.default_order_type; if (type === 'GTD') plan.expiry = now + p.gtd_signal_ttl_s;

{ "iceberg_threshold_usd": 500 }

if (order.size_usd > p.iceberg_threshold_usd) return splitIceberg(order, p.iceberg_child_count);

{ "iceberg_child_count": 3 }

if (p.iceberg_child_count > p.hard) throw new ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "gtd_signal_ttl_s": 120 }

if (Date.now() - intent.generated_at > p.gtd_signal_ttl_s * 1000) return discard('STALE_MARKET_DATA');

8. Default Configuration

{
  "bot_id": "exec.smart_router",
  "version": "1.0.0",
  "mode": "general_live",
  "defaults": {
    "default_order_type": "GTC",
    "iceberg_threshold_usd": 500,
    "iceberg_child_count": 3,
    "gtd_signal_ttl_s": 120
  },
  "locked": {
    "iceberg_child_count": {
      "max": 8
    },
    "gtd_signal_ttl_s": {
      "max": 300
    }
  }
}

9. Implementation Flow

1. Receive the approved OrderIntent from the Risk guardrail pipeline, including applied constraints (max_size_usd, passive_only, close_only) from PortfolioGuard.
2. Check KillSwitch active flag; if active, discard the order and emit no ExecutionPlan.
3. Fetch the market's tick size and neg-risk flag from Gamma API; round order.price to the nearest valid tick.
4. Determine the order type: use intent.order_type if specified; otherwise apply default_order_type logic based on book depth and signal age.
5. If order type is GTD, check signal age against gtd_signal_ttl_s; if expired, discard with STALE_MARKET_DATA.
6. Check order.size_usd against iceberg_threshold_usd; if above threshold, compute child_size = size / iceberg_child_count and build an iceberg plan.
7. Pull top 50 book levels from the CLOB to confirm there is sufficient depth for FOK orders; if depth is insufficient for FOK, downgrade to GTC automatically.
8. Assemble the ExecutionPlan with: order_type, price (tick-aligned), size or iceberg children array, side (unchanged from intent), market_id (unchanged), and submission_timestamp.
9. Validate that the ExecutionPlan does not alter side, market_id, or outcome leg from the original intent — these are invariants.
10. Emit the ExecutionPlan to the order signing step.

10. Reference Implementation

Receives an approved OrderIntent from the Risk pipeline, selects order type, tick-aligns the price using buildOrderTypedData, optionally splits into iceberg children, and emits an ExecutionPlan. Owns the signing flow by calling the wallet adapter — never holds keys.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

FUNCTION routeOrder(intent, riskConstraints):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    DISCARD intent
    RETURN

  // --- 1. Fetch market tick size and neg-risk flag ---
  market = fetchClobPublic('/markets/' + intent.market_id)
  IF market IS NULL OR isStale(market, 60):
    DISCARD intent; reason=STALE_MARKET_DATA
    RETURN

  tickSize = market.minimum_tick_size  // e.g. 0.01
  negRisk = market.neg_risk

  // --- 2. GTD TTL check ---
  signalAgeMs = now_ms() - intent.generated_at_ms
  IF intent.order_type == 'GTD' AND signalAgeMs > params.gtd_signal_ttl_s * 1000:
    DISCARD intent; reason=STALE_MARKET_DATA
    RETURN

  // --- 3. Tick-align price ---
  alignedPrice = floor(intent.price / tickSize) * tickSize

  // --- 4. Order type selection ---
  book = fetchClobPublic('/book?market=' + intent.market_id)
  bookDepth = SUM(level.size FOR level IN book.asks[:50])
  IF intent.order_type == 'FOK' AND bookDepth < intent.size_usd:
    orderType = 'GTC'  // downgrade FOK → GTC on thin book
  ELSE:
    orderType = intent.order_type OR params.default_order_type

  // --- 5. NegRisk convert-arb routing ---
  IF negRisk AND intent.negrisk_convert_requested:
    EMIT NegRiskConvertRoute(market_id=intent.market_id, size=intent.size_usd)
    RETURN  // NegRiskAdapter path; not a CLOB order

  // --- 6. Iceberg split ---
  finalSize = min(intent.size_usd, riskConstraints.max_size_usd)
  IF finalSize > params.iceberg_threshold_usd:
    childSize = toUsdcUnits(finalSize / params.iceberg_child_count)
    children = [childSize] * params.iceberg_child_count
  ELSE:
    children = [toUsdcUnits(finalSize)]

  // --- 7. Build V2 typed order data ---
  // V2 order fields: timestamp(ms) + metadata(bytes32) + builder(bytes32)
  // Fees are operator-set at match time; NOT in the signed order
  FOR child IN children:
    typedData = buildOrderTypedData({
      market_id: intent.market_id,
      side: intent.side,  // NEVER flipped
      outcome: intent.outcome,
      price: alignedPrice,
      size: child,
      order_type: orderType,
      timestamp: now_ms(),
      metadata: ZERO_BYTES32,
      builder: config.builder_code_bytes32
    }, domain={ version: '2', chainId: 137, verifyingContract: CTFExchangeV2 })
    // wallet adapter signs typedData — never holds keys
    signedOrder = wallet.sign(typedData)
    VALIDATE ExecutionPlan invariants:
      assert signedOrder.side == intent.side
      assert signedOrder.market_id == intent.market_id
      assert signedOrder.size <= riskConstraints.max_size_usd

  // --- 8. Emit ExecutionPlan ---
  EMIT ExecutionPlan(
    router_id='exec.smart_router',
    market_id=intent.market_id,
    side=intent.side,
    order_type=orderType,
    tick_aligned_price=alignedPrice,
    iceberg=(len(children) > 1),
    children=children,
    submission_timestamp=now_iso()
  )

Helpers used

SDK calls used

• fetchClobPublic('/markets/' + intent.market_id)
• fetchClobPublic('/book?market=' + intent.market_id + '&depth=50')
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• wallet.sign(typedData)
• clob_auth.POST('/order', signedOrder)
• ws_user.subscribe('fills', intent.market_id)

Complexity: O(C) where C = iceberg_child_count

11. Wire Examples

Input — what arrives on the wire

Approved OrderIntent from Risk pipeline — internal

{
  "intent_id": "int_6f7a8b9c0d1e2f3a",
  "market_id": "0x6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
  "side": "BUY",
  "outcome": "YES",
  "price": 0.623,
  "size_usd": 500,
  "order_type": "GTC",
  "neg_risk": false,
  "generated_at_ms": 1746768658000,
  "risk_constraints": {
    "max_size_usd": 450,
    "passive_only": false,
    "close_only": false
  }
}

Output — what the bot emits

ExecutionPlan — single GTC order, tick-aligned

{
  "router_id": "exec.smart_router",
  "market_id": "0x6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
  "side": "BUY",
  "outcome": "YES",
  "order_type": "GTC",
  "price": 0.623,
  "tick_aligned_price": 0.62,
  "size_usd": 450,
  "iceberg": false,
  "children": [],
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "eip712_domain_version": "2",
  "submission_timestamp": "2026-05-09T11:00:00Z",
  "signal_age_s": 14,
  "inputs_used": [
    "clob_public.book.top50",
    "gamma_api.market.tick_size",
    "portfolio_guard.approved_intent"
  ]
}

ExecutionPlan — iceberg split (3 children)

{
  "router_id": "exec.smart_router",
  "market_id": "0x6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f",
  "side": "BUY",
  "outcome": "YES",
  "order_type": "GTC",
  "tick_aligned_price": 0.62,
  "size_usd": 600,
  "iceberg": true,
  "children": [
    200,
    200,
    200
  ],
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "eip712_domain_version": "2",
  "submission_timestamp": "2026-05-09T11:01:00Z",
  "signal_age_s": 8,
  "inputs_used": [
    "clob_public.book.top50",
    "gamma_api.market.tick_size"
  ]
}

Reproduce locally

curl -H 'Authorization: Bearer <token>' -X POST 'https://clob.polymarket.com/order' -d '{...signed_order...}'

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionPlan object. See ExecutionPlan schema.

{
  "router_id": "exec.smart_router",
  "market_id": "CLOB:0xabc123",
  "side": "BUY",
  "outcome": "YES",
  "order_type": "GTC",
  "price": 0.62,
  "tick_aligned_price": 0.62,
  "size_usd": 450,
  "iceberg": false,
  "children": [],
  "submission_timestamp": "2026-05-09T11:00:00Z",
  "signal_age_s": 14,
  "inputs_used": [
    "clob.book.top50",
    "gamma_api.market.tick_size",
    "portfolio_guard.approved_intent"
  ]
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Execution / SmartRouter
• Grafana — Order quality / tick rounding and iceberg split distribution

Log levels

16. Developer Reporting

{
  "router_id": "exec.smart_router",
  "market_id": "CLOB:0xabc123",
  "order_type_selected": "GTC",
  "original_price": 0.623,
  "tick_aligned_price": 0.62,
  "original_size_usd": 500,
  "final_size_usd": 450,
  "iceberg_applied": false,
  "signal_age_s": 14,
  "gtd_signal_ttl_s": 120,
  "tick_size": 0.01,
  "inputs_used": [
    "clob.book.top50",
    "gamma_api.market.tick_size"
  ],
  "submission_timestamp": "2026-05-09T11:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Stateless per evaluation; holds a short-lived in-memory cache of tick sizes and market metadata.

State stores

Cold-start recovery

On cold start, the cache is empty. First evaluation per market triggers a Gamma API fetch.

On restart

Tick sizes are re-fetched on first evaluation. If Gamma API is unavailable on startup, the first intent for each market is discarded with STALE_MARKET_DATA.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.12 2.13 2.2 2.3 2.4 2.6 6.1

External services

23. Security Surfaces

SmartRouter triggers signed orders via the wallet adapter. It never holds private keys. The builder code is injected as a bytes32 field on every order.

Signing surface

This bot triggers signed orders via the wallet adapter — never holds keys. buildOrderTypedData produces the EIP-712 payload; the wallet adapter performs the signing.

On-chain contract calls

Abuse vectors considered

• Injecting a modified intent to flip the side (BUY→SELL) between guardrail approval and ExecutionPlan emit
• Replaying a stale signed order after the GTD TTL has expired
• Clock skew causing gtd_signal_ttl_s check to pass on an aged signal

Mitigations

• ExecutionPlan invariant check asserts side == intent.side before emitting
• per-intent_id deduplication prevents replay within 24h
• Clock synchronisation via NTP; TTL check uses server-side wall clock
• buildOrderTypedData includes current timestamp(ms) in V2 order fields, making replayed signatures invalid once the timestamp window passes

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

SmartRouter incidents are typically stale tick-size data or elevated discard rates. Signing failures are escalated immediately.

On-call actions

Manual overrides

• polytraders bot pause exec.smart_router — Stops emitting ExecutionPlans. No orders will be signed or submitted.
• polytraders bot flush-cache exec.smart_router --market <market_id> — Evicts the tick-size cache for a specific market, forcing a fresh Gamma API fetch.

Healthcheck

GET /health → 200 if Gamma API tick sizes are fresh (< 60s) for all active markets and wallet adapter is responsive.

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%