3.3 Sum-to-One Arb

1. Bot Identity

2. Purpose

Sum-to-One Arb detects when the combined cost of buying both YES and NO tokens on a standard binary market falls below $1.00 pUSD, net of platform fees and a configurable fee buffer. When edge (in basis points) exceeds min_edge_bps, the bot emits a pair of OrderIntents — one for YES and one for NO — sized to the smaller of the two books up to max_leg_size_usd. Both legs fill to produce a guaranteed $1.00 settlement regardless of outcome. This is a user-controlled execution tool that exploits CLOB pricing dislocations in standard 2-outcome markets. It does not touch negative-risk or multi-outcome events; those are handled by neg-risk-sum-arb.

3. Why This Bot Matters

• Edge is measured incorrectly (ignores fees)

  Platform fee C×feeRate×p×(1-p) peaks at p=0.5. Entering without fee buffer eats the edge entirely and turns a positive-expectation trade into a loss.

• Slippage consumes one leg between intent generation and fill

  If the YES leg fills but the NO leg moves before submission, the combined cost may exceed $1.00 and the guaranteed profit becomes a guaranteed loss.

• Market closes or resolves between the two legs

  Submitting a GTC order for the second leg on a market that has resolved or halted leaves an open order with no offsetting settlement path.

• feeRateBps hardcoded on signed order (V1 pattern)

  CLOB V2 rejects orders with feeRateBps present. Fees are operator-set at match time. The signed order must not 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

{ "min_edge_bps": 15 }

if edge_bps < params.hard: return skip('SUM_TO_ONE_ARB_NO_EDGE')

{ "fee_buffer_bps": 30 }

netEdge = rawEdge - params.fee_buffer_bps - params.slippage_buffer_bps

{ "slippage_buffer_bps": 10 }

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

{ "max_leg_size_usd": 500 }

legSize = min(depthAvailable, params.max_leg_size_usd, riskConstraints.max_size_usd)

8. Default Configuration

{
  "bot_id": "strat.sum_to_one_arb",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "min_edge_bps": 15,
    "fee_buffer_bps": 30,
    "slippage_buffer_bps": 10,
    "max_leg_size_usd": 500
  },
  "locked": {
    "min_edge_bps": {
      "min": 5
    },
    "max_leg_size_usd": {
      "max": 1000
    },
    "slippage_buffer_bps": {
      "max": 50
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, skip and emit no OrderIntent.
2. Subscribe to ws_market book updates for all active binary markets (negRisk=false).
3. On each book tick: compute sum_of_asks = best_ask_YES + best_ask_NO.
4. Estimate platform fee drag: fee_drag = C * feeRate * p_yes * (1 - p_yes) + C * feeRate * p_no * (1 - p_no) where p = best_ask.
5. Compute raw_edge_bps = (1.00 - sum_of_asks) * 10000.
6. Compute net_edge_bps = raw_edge_bps - fee_buffer_bps - slippage_buffer_bps.
7. If net_edge_bps < min_edge_bps hard floor (5), emit DecisionReport with intent_emitted=false reason SUM_TO_ONE_ARB_NO_EDGE; skip.
8. If net_edge_bps < min_edge_bps warning threshold (15), emit WARN SUM_TO_ONE_ARB_EDGE_MARGINAL and reduce leg size by 50%.
9. Fetch top-of-book depth for YES and NO legs from clob_public; set legSize = min(depth_yes, depth_no, max_leg_size_usd).
10. Confirm market status is open and not resolved (clob_public market endpoint).
11. Emit OrderIntent YES: market_id, outcome=YES, side=buy, price=best_ask_YES, size_pUSD=legSize, tif=FOK, builder={code: builderCode, fee_bps: 25}.
12. Emit OrderIntent NO: market_id, outcome=NO, side=buy, price=best_ask_NO, size_pUSD=legSize, tif=FOK, builder={code: builderCode, fee_bps: 25}.
13. Note: fees are operator-set at match time in V2 — feeRateBps is NOT present on the signed order.
14. Emit DecisionReport with intent_emitted=true, edge_bps=net_edge_bps, reason SUM_TO_ONE_ARB_EDGE_PRESENT.
15. Sampled 1/100 skipped opportunities also emit a DecisionReport with intent_emitted=false for observability.

10. Reference Implementation

Subscribes to CLOB WebSocket book updates for binary markets, computes net edge in bps after fee and slippage buffers, and emits a YES+NO OrderIntent pair when edge exceeds the configured minimum.

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

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

  // --- 1. Validate book freshness ---
  IF isStale(bookTick, maxAgeS=5):
    EMIT DecisionReport(intent_emitted=false, reason='STALE_MARKET_DATA')
    RETURN

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

  // --- 3. Compute edge ---
  best_ask_YES = bookTick.yes.asks[0].price
  best_ask_NO  = bookTick.no.asks[0].price
  sum_of_asks  = best_ask_YES + best_ask_NO
  raw_edge_bps = (1.00 - sum_of_asks) * 10000

  // --- 4. Deduct fee drag ---
  feeRate = FETCH onchain.feeConfig(market_id)  // e.g. 0.018 for crypto
  fee_drag_bps = feeRate * best_ask_YES * (1 - best_ask_YES) * 10000
               + feeRate * best_ask_NO  * (1 - best_ask_NO)  * 10000
  net_edge_bps = raw_edge_bps - params.fee_buffer_bps - params.slippage_buffer_bps

  // --- 5. Hard floor check ---
  IF net_edge_bps < params.min_edge_bps_hard:  // 5 bps absolute floor
    // sample 1/100 skips for observability
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='SUM_TO_ONE_ARB_NO_EDGE', edge_bps=net_edge_bps)
    RETURN

  // --- 6. Warning threshold ---
  legSizeMultiplier = 1.0
  IF net_edge_bps < params.min_edge_bps:  // 15 bps default
    WARN('SUM_TO_ONE_ARB_EDGE_MARGINAL')
    legSizeMultiplier = 0.5

  // --- 7. Size legs ---
  depth_YES = bookTick.yes.asks[0].size_pusd
  depth_NO  = bookTick.no.asks[0].size_pusd
  legSize   = toPusdUnits(min(depth_YES, depth_NO, params.max_leg_size_usd) * legSizeMultiplier)

  // --- 8. Build OrderIntents (V2: no feeRateBps; builder field carries code) ---
  intentYES = OrderIntent(
    market_id   = market_id,
    outcome     = 'YES',
    side        = 'buy',
    price       = best_ask_YES,
    size_pUSD   = legSize,
    tif         = 'FOK',
    post_only   = false,
    builder     = { code: config.builder_code, fee_bps: 25 },
    negrisk_aware = false
  )
  intentNO = OrderIntent(
    market_id   = market_id,
    outcome     = 'NO',
    side        = 'buy',
    price       = best_ask_NO,
    size_pUSD   = legSize,
    tif         = 'FOK',
    post_only   = false,
    builder     = { code: config.builder_code, fee_bps: 25 },
    negrisk_aware = false
  )

  EMIT intentYES
  EMIT intentNO
  EMIT DecisionReport(
    intent_emitted = true,
    edge_bps       = net_edge_bps,
    reasons        = ['SUM_TO_ONE_ARB_EDGE_PRESENT']
  )

SDK calls used

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

Complexity: O(1) per market book tick

11. Wire Examples

Input — what arrives on the wire

WebSocket book tick — binary market with edge — ws_market

{
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "yes_token_id": "0xabc001",
  "no_token_id": "0xabc002",
  "yes_best_ask": "0.488",
  "no_best_ask": "0.510",
  "sum_of_asks": "0.998",
  "depth_YES_pusd": "620.00",
  "depth_NO_pusd": "540.00",
  "received_at_ms": 1746789600000
}

Output — what the bot emits

OrderIntent — YES leg (FOK, builder-attributed)

{
  "intent_id": "oi_01HX9KZQ7F2A1B",
  "trace_id": "tr_01HX9KZQ7E8VR5",
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "outcome": "YES",
  "side": "buy",
  "price": "0.488",
  "size_pUSD": "500.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 18.4,
    "reasons": [
      "SUM_TO_ONE_ARB_EDGE_PRESENT"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

OrderIntent — NO leg (FOK, builder-attributed)

{
  "intent_id": "oi_01HX9KZQ7F2B2C",
  "trace_id": "tr_01HX9KZQ7E8VR5",
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "outcome": "NO",
  "side": "buy",
  "price": "0.510",
  "size_pUSD": "500.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 18.4,
    "reasons": [
      "SUM_TO_ONE_ARB_EDGE_PRESENT"
    ]
  },
  "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_01HX9KZQ7F9ZZZ",
  "bot_id": "strat.sum_to_one_arb",
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "intent_emitted": false,
  "edge_bps": 1.2,
  "reasons": [
    "SUM_TO_ONE_ARB_NO_EDGE"
  ],
  "sampled": true,
  "evaluated_at_ms": 1746789601000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HX9KZQ7F2A1B",
  "trace_id": "tr_01HX9KZQ7E8VR5",
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "outcome": "YES",
  "side": "buy",
  "price": "0.488",
  "size_pUSD": "500.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "edge_bps": 18.4,
    "reasons": [
      "SUM_TO_ONE_ARB_EDGE_PRESENT"
    ]
  },
  "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 / SumToOneArb edge distribution
• Grafana — Strategy / SumToOneArb intent throughput and leg sizing

16. Developer Reporting

{
  "bot_id": "strat.sum_to_one_arb",
  "market_id": "0xabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
  "sum_of_asks": 0.9982,
  "raw_edge_bps": 18.0,
  "fee_drag_bps": 12.3,
  "net_edge_bps": 18.4,
  "leg_size_pusd": 500.0,
  "yes_ask": 0.488,
  "no_ask": 0.51,
  "intent_emitted": true,
  "reason": "SUM_TO_ONE_ARB_EDGE_PRESENT",
  "emitted_at_ms": 1746789600000
}

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 tick per market triggers fresh evaluation without any 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

• Front-running: emitting YES leg publicly before NO leg allows adversaries to move the NO book
• Replaying a signed OrderIntent after the market's arb window has closed
• Injecting a modified builder.code to redirect attribution fees

Mitigations

• Both legs use FOK (Fill-or-Kill); a partial fill on one leg is rejected rather than leaving a naked position
• V2 order timestamp(ms) field invalidates replays outside the exchange's acceptance window
• Builder code is read from immutable internal config; not user-supplied
• per-intent_id deduplication within 24h prevents replay

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

SumToOneArb incidents are usually stale WebSocket feed, no-edge market conditions, or one-sided FOK fills. The last is the most operationally significant and requires manual risk review.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/sum-to-one-arb -> 200 if ws_market feed last_seen < 5s, Redis reachable, KillSwitch inactive, and 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%