3.5 Bregman-Projection Arb

1. Bot Identity

2. Purpose

Bregman-Projection Arb detects when the joint probability distribution implied by a neg-risk multi-outcome market's order book diverges from the closest valid (simplex-constrained) distribution by more than kl_divergence_threshold nats. It uses a Frank-Wolfe iterative projection to find the nearest valid distribution, measures the KL-divergence of the observed book from that projection, and emits a set of up to max_legs_per_trade OrderIntents to exploit the divergence. This is a user-controlled execution tool for multi-outcome neg-risk markets. It never trades standard 2-outcome binary markets (those are handled by Sum-to-One Arb). No performance claims are made; the tool automates the mechanical detection and sizing of Bregman-projection violations.

3. Why This Bot Matters

• KL-divergence computed on stale snapshots

  The divergence measurement reflects an order book that no longer exists. Emitting OrderIntents based on stale data incurs slippage on all legs and may produce a net loss.

• Frank-Wolfe projection does not converge within frank_wolfe_iters

  The nearest valid distribution is not found; the measured divergence is an upper bound, not the true value. The bot may under-size or skip genuinely profitable trades.

• Leg count exceeds max_legs_per_trade while liquidity is thin

  In a 10-outcome market, all legs may be needed to fully capture the divergence. Capping legs leaves residual exposure that does not hedge cleanly.

• NegRisk market settled via DVM while legs are open

  If a disputed NegRisk outcome enters a 24-48h UMA DVM vote, open positions cannot be settled immediately. The bot must detect the dispute flag and halt new legs on affected markets.

• feeRateBps present on signed order (V1 pattern)

  CTFExchangeV2 rejects orders with feeRateBps. Fees are operator-set at match time. No leg intent may contain this field.

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

{ "kl_divergence_threshold": 0.015 }

if kl_div < params.hard: return skip('BREGMAN_ARB_NO_EDGE')

{ "frank_wolfe_iters": 200 }

assert params.frank_wolfe_iters >= params.hard

{ "max_legs_per_trade": 6 }

if params.max_legs_per_trade > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "liquidity_cap_usd": 400 }

legSize = min(depthAvail, liquidity_cap_usd / n_legs)

8. Default Configuration

{
  "bot_id": "strat.bregman_projection_arb",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "kl_divergence_threshold": 0.015,
    "frank_wolfe_iters": 200,
    "max_legs_per_trade": 6,
    "liquidity_cap_usd": 400
  },
  "locked": {
    "kl_divergence_threshold": {
      "min": 0.003
    },
    "frank_wolfe_iters": {
      "min": 30
    },
    "max_legs_per_trade": {
      "max": 12
    },
    "liquidity_cap_usd": {
      "max": 800
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents.
2. Subscribe to ws_market book updates for all active neg-risk multi-outcome markets.
3. On each book snapshot: validate freshness (last_seen < 3s); else emit STALE_MARKET_DATA and skip.
4. Confirm market negRisk=true and not closed/resolved/in-dispute via clob_public.
5. Build observed probability vector p_obs from best-ask prices across all outcome token IDs (normalise to sum-to-one).
6. Run Frank-Wolfe projection: initialise q = uniform; iterate up to frank_wolfe_iters; converge to nearest simplex distribution q*.
7. Compute KL(p_obs || q*). If < kl_divergence_threshold hard floor (0.003), emit DecisionReport intent_emitted=false BREGMAN_ARB_NO_EDGE (sampled 1/100); RETURN.
8. If kl_div < warning threshold (0.015), WARN BREGMAN_ARB_DIVERGENCE_MARGINAL; reduce all leg sizes by 50%.
9. Sort outcome legs by |p_obs_i - q*_i| descending; select top min(max_legs_per_trade, n_outcomes) legs.
10. Fetch top-of-book depth for each selected leg from clob_public; set legSize = min(depth, liquidity_cap_usd / n_legs).
11. Emit OrderIntent for each selected leg: market_id, outcome_token_id, side=buy (if p_obs_i > q*_i: NO/short; else YES/long), price=best_ask, size_pUSD=legSize, tif=FOK, builder={code, fee_bps:25}.
12. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on any signed order.
13. Emit DecisionReport with intent_emitted=true, kl_divergence, n_legs, reason BREGMAN_ARB_EDGE_DETECTED.

10. Reference Implementation

Subscribes to CLOB WebSocket book snapshots for neg-risk markets, runs Frank-Wolfe simplex projection to find the nearest valid distribution, measures KL-divergence, and emits per-leg FOK OrderIntents when divergence exceeds threshold.

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

FUNCTION evaluateNegRiskMarket(market_id, bookSnapshot):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // --- 1. Staleness check ---
  IF isStale(bookSnapshot, maxAgeS=3):
    EMIT DecisionReport(intent_emitted=false, reason='STALE_MARKET_DATA')
    RETURN

  // --- 2. NegRisk market validation ---
  market = FETCH clob_public.GET('/markets/' + market_id)
  IF NOT market.neg_risk OR market.closed OR market.resolved OR market.dispute_active:
    EMIT DecisionReport(intent_emitted=false, reason='MARKET_CLOSED')
    RETURN

  // --- 3. Build observed probability vector ---
  outcomes = bookSnapshot.outcomes  // list of {token_id, best_ask, depth_pusd}
  p_obs = [o.best_ask for o in outcomes]
  p_obs = normalise(p_obs)  // sum-to-one on simplex

  // --- 4. Frank-Wolfe projection to nearest valid distribution ---
  q = uniform(len(outcomes))  // init
  FOR iter IN range(params.frank_wolfe_iters):
    grad = KL_gradient(p_obs, q)  // ∇KL(p||q) = -p/q
    s = argmin_simplex(grad)      // Frank-Wolfe linear minimisation step
    gamma = 2.0 / (iter + 2)     // step size
    q_new = (1 - gamma) * q + gamma * s
    IF norm(q_new - q) < 1e-8: BREAK
    q = q_new
  q_star = q

  // --- 5. KL-divergence check ---
  kl_div = KL(p_obs, q_star)
  IF kl_div < params.kl_divergence_threshold_hard:  // 0.003
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='BREGMAN_ARB_NO_EDGE', kl_div=kl_div)
    RETURN

  // --- 6. Warning threshold ---
  sizeMultiplier = 1.0
  IF kl_div < params.kl_divergence_threshold:  // 0.015
    WARN('BREGMAN_ARB_DIVERGENCE_MARGINAL')
    sizeMultiplier = 0.5

  // --- 7. Select legs by divergence magnitude ---
  divergences = [(i, abs(p_obs[i] - q_star[i])) for i in range(len(outcomes))]
  divergences.sort(by=magnitude, descending=true)
  selected = divergences[:params.max_legs_per_trade]

  // --- 8. Size and emit legs ---
  legBudget = params.liquidity_cap_usd / len(selected)
  FOR (i, _) IN selected:
    legSize = toPusdUnits(min(outcomes[i].depth_pusd, legBudget) * sizeMultiplier)
    side = 'buy' IF p_obs[i] < q_star[i] ELSE 'sell'
    EMIT OrderIntent(
      market_id        = market_id,
      outcome_token_id = outcomes[i].token_id,
      side             = side,
      price            = outcomes[i].best_ask,
      size_pUSD        = legSize,
      tif              = 'FOK',
      post_only        = false,
      negrisk_aware    = true,
      builder          = {code: internal.builder_code, fee_bps: 25}
      // V2: no feeRateBps on signed order
    )

  EMIT DecisionReport(intent_emitted=true, kl_divergence=kl_div,
                      n_legs=len(selected), reason='BREGMAN_ARB_EDGE_DETECTED')

SDK calls used

• fetchClobPublic('/markets/' + market_id)
• ws_market.subscribe('book', outcome_token_ids)
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.killswitch.status()
• internal.builder_code

Complexity: O(k * frank_wolfe_iters) per book snapshot, where k = number of outcomes

11. Wire Examples

Input — what arrives on the wire

NegRisk market book snapshot — 8 outcomes, divergence detected — ws_market

{
  "market_id": "0xbregman0000000000000000000000000000000000000000000000000000000001",
  "neg_risk": true,
  "outcomes": [
    {
      "token_id": "0xbrg_tk_0",
      "best_ask": "0.310",
      "depth_pusd": "180.00"
    },
    {
      "token_id": "0xbrg_tk_1",
      "best_ask": "0.185",
      "depth_pusd": "220.00"
    },
    {
      "token_id": "0xbrg_tk_2",
      "best_ask": "0.112",
      "depth_pusd": "90.00"
    },
    {
      "token_id": "0xbrg_tk_3",
      "best_ask": "0.098",
      "depth_pusd": "75.00"
    },
    {
      "token_id": "0xbrg_tk_4",
      "best_ask": "0.095",
      "depth_pusd": "60.00"
    },
    {
      "token_id": "0xbrg_tk_5",
      "best_ask": "0.074",
      "depth_pusd": "50.00"
    },
    {
      "token_id": "0xbrg_tk_6",
      "best_ask": "0.068",
      "depth_pusd": "45.00"
    },
    {
      "token_id": "0xbrg_tk_7",
      "best_ask": "0.058",
      "depth_pusd": "40.00"
    }
  ],
  "received_at_ms": 1746790000000
}

Output — what the bot emits

OrderIntent — leg 2 (buy outcome 2, FOK, builder-attributed)

{
  "intent_id": "oi_01HXB9PARZ0001A",
  "trace_id": "tr_01HXB9PARZ000TR",
  "market_id": "0xbregman0000000000000000000000000000000000000000000000000000000001",
  "outcome_token_id": "0xbrg_tk_2",
  "side": "buy",
  "price": "0.112",
  "size_pUSD": "66.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": true,
  "decision": {
    "kl_divergence": 0.022,
    "n_legs": 6,
    "leg_index": 2,
    "reasons": [
      "BREGMAN_ARB_EDGE_DETECTED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

DecisionReport — skipped (no edge), sampled 1/100

{
  "report_id": "dr_01HXB9PARZ999Z",
  "bot_id": "strat.bregman_projection_arb",
  "market_id": "0xbregman0000000000000000000000000000000000000000000000000000000001",
  "intent_emitted": false,
  "kl_divergence": 0.001,
  "reasons": [
    "BREGMAN_ARB_NO_EDGE"
  ],
  "sampled": true,
  "evaluated_at_ms": 1746790001000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HXB9PARZ0001A",
  "trace_id": "tr_01HXB9PARZ000TR",
  "market_id": "0xbregman0000000000000000000000000000000000000000000000000000000001",
  "outcome_token_id": "0xbregman_tk_outcome_3",
  "side": "buy",
  "price": "0.112",
  "size_pUSD": "66.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": true,
  "decision": {
    "kl_divergence": 0.022,
    "n_legs": 6,
    "leg_index": 2,
    "reasons": [
      "BREGMAN_ARB_EDGE_DETECTED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Strategy / BregmanArb KL-divergence distribution
• Grafana — Strategy / BregmanArb leg throughput and projection convergence

16. Developer Reporting

{
  "bot_id": "strat.bregman_projection_arb",
  "market_id": "0xbregman0000000000000000000000000000000000000000000000000000000001",
  "n_outcomes": 8,
  "kl_divergence": 0.022,
  "frank_wolfe_iters_used": 147,
  "n_legs_selected": 6,
  "liquidity_cap_usd": 400,
  "per_leg_size_pusd": 66.0,
  "intent_emitted": true,
  "reason": "BREGMAN_ARB_EDGE_DETECTED",
  "emitted_at_ms": 1746790000000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, state is empty; first book snapshot triggers fresh Frank-Wolfe projection without stale-state comparison.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Adversary spams thin neg-risk legs to force spurious KL-divergence signals
• Replaying a signed OrderIntent after the projected divergence closes
• Injecting a modified builder.code to redirect attribution fees

Mitigations

• All legs use FOK; partial fills are rejected rather than leaving naked positions
• V2 order timestamp(ms) invalidates replays outside the exchange acceptance window
• Builder code is read from immutable internal config; not user-supplied
• Book snapshot staleness check (3s) prevents acting on stale divergence signals

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

Bregman-Projection Arb incidents are usually stale feed, Frank-Wolfe non-convergence on high-outcome markets, or UMA DVM dispute halts. Non-convergence requires a config fix; dispute halts resolve automatically.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/bregman-projection-arb -> 200 if ws_market feed last_seen < 3s, Redis reachable, KillSwitch inactive, at least one market evaluated in last 60s.

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%