3.15 VolatilityHarvest

1. Bot Identity

2. Purpose

VolatilityHarvest quotes inside the spread on volatile Polymarket event markets with thick books, collecting maker rebates while managing inventory skew. It enters when realised volatility exceeds min_realised_vol, quotes inside the current spread by quote_inside_bps, and limits total position via max_inventory_skew. After a losing quote it cools off for cool_off_after_loss seconds.

3. Why This Bot Matters

• Inventory accumulates in one direction

  Sustained directional order flow leaves the bot long or short at a mispriced level; inventory risk grows until the market moves against the accumulated position.

• Volatility drops after entry

  When realised volatility falls, spread income shrinks but position remains; the strategy is no longer compensated for carrying risk.

• Cool-off period ignored after loss

  Immediately re-quoting after an adverse fill can compound losses if the adverse move is continuing.

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_realised_vol": 0.05 }

if realised_vol < params.hard: return skip('VH_VOL_BELOW_FLOOR')

{ "quote_inside_bps": 50 }

if params.quote_inside_bps < params.hard: return skip('VH_QUOTE_TOO_TIGHT')

{ "max_inventory_skew": 0.3 }

if abs(inventory_skew) > params.hard: return skip('VH_INVENTORY_LIMIT')

{ "cool_off_after_loss": 60 }

if in_cooloff(market_id): return skip('VH_COOLOFF_ACTIVE')

8. Default Configuration

{
  "bot_id": "strat.volatilityharvest",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_realised_vol": 0.05,
    "quote_inside_bps": 50,
    "max_inventory_skew": 0.3,
    "cool_off_after_loss": 60
  },
  "locked": {
    "min_realised_vol": {
      "min": 0.01
    },
    "quote_inside_bps": {
      "min": 5
    },
    "max_inventory_skew": {
      "max": 0.7
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. FETCH realised vol from volatility model; if < hard (0.01), skip VH_VOL_BELOW_FLOOR.
3. Check cool-off state; if in cool-off for market_id, skip VH_COOLOFF_ACTIVE.
4. FETCH ws_market book; check inventory skew.
5. IF abs(inventory_skew) > hard (0.70): skip VH_INVENTORY_LIMIT.
6. Compute inside quote: bid = best_bid + quote_inside_bps/10000; ask = best_ask - quote_inside_bps/10000.
7. Compute quote size = min(max_quote_size_usd, available_capital).
8. Adjust size down 50% if realised_vol < warning (0.03).
9. EMIT GTC post-only OrderIntent for YES (bid side) and/or NO (ask side) depending on skew.
10. EMIT DecisionReport with intent_emitted=true, reason=VH_QUOTE_EMITTED.

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 onVolUpdate(market_id, volSignal):
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // Vol gate
  realisedVol = volSignal.realised_vol
  IF realisedVol < params.min_realised_vol_hard:  // 0.01
    EMIT DecisionReport(intent_emitted=false, reason='VH_VOL_BELOW_FLOOR')
    RETURN

  // Cool-off check
  IF state.inCooloff(market_id):
    EMIT DecisionReport(intent_emitted=false, reason='VH_COOLOFF_ACTIVE')
    RETURN

  // Inventory skew check
  inventory = FETCH state.inventory(market_id)
  skew = computeSkew(inventory.yes_usd, inventory.no_usd)
  IF abs(skew) > params.max_inventory_skew_hard:  // 0.70
    EMIT DecisionReport(intent_emitted=false, reason='VH_INVENTORY_LIMIT')
    RETURN

  book = FETCH ws_market.book(market_id)
  insideBps = params.quote_inside_bps / 10000
  bidPrice = book.best_bid + insideBps
  askPrice = book.best_ask - insideBps

  sizeMultiplier = 0.5 IF realisedVol < params.min_realised_vol_warn ELSE 1.0
  IF sizeMultiplier < 1.0: WARN('VH_LOW_VOL')
  orderSize = toPusdUnits(params.max_quote_size_usd * sizeMultiplier)

  // Quote both sides unless inventory skew exceeds warn threshold
  IF skew < params.max_inventory_skew_warn OR skew >= 0:
    EMIT OrderIntent(market=market_id, outcome='YES', side='buy', price=bidPrice,
                     size_pUSD=orderSize, tif='GTC', post_only=true, builder=code)
  EMIT DecisionReport(intent_emitted=true, realised_vol=realisedVol, reason='VH_QUOTE_EMITTED')

SDK calls used

• ws_market.subscribe('book', [market_id])
• fetchClobPublic('/markets/' + market_id)
• internal.volatilityModel.realisedVol(market_id)
• buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})

Complexity: O(1) per vol update per market; O(open_quotes) for inventory tracking

11. Wire Examples

Input — what arrives on the wire

Vol signal — market at 0.08 realised vol — internal (volatility model)

{
  "market_id": "0xvh000000000000000000000000000000000000000000000000000000000000001",
  "realised_vol": "0.08",
  "best_bid": "0.490",
  "best_ask": "0.510",
  "inventory_skew": "0.10",
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — VH GTC post-only inside bid

{
  "intent_id": "oi_01HVH0000001A",
  "market_id": "0xvh000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.495",
  "size_pUSD": "200.00",
  "tif": "GTC",
  "post_only": true,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 10
  },
  "decision": {
    "realised_vol": 0.08,
    "quote_inside_bps": 50,
    "reasons": [
      "VH_QUOTE_EMITTED"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HVH0000001A",
  "trace_id": "tr_01HVH000TR001",
  "market_id": "0xvh000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.495",
  "size_pUSD": "200.00",
  "tif": "GTC",
  "post_only": true,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 10
  },
  "negrisk_aware": false,
  "decision": {
    "realised_vol": 0.08,
    "quote_inside_bps": 50,
    "inventory_skew": 0.1,
    "reasons": [
      "VH_QUOTE_EMITTED"
    ]
  },
  "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

16. Developer Reporting

{
  "bot_id": "strat.volatilityharvest",
  "market_id": "0xvh000000000000000000000000000000000000000000000000000000000000001",
  "realised_vol": 0.08,
  "quote_inside_bps": 50,
  "inventory_skew": 0.1,
  "intent_emitted": true,
  "reason": "VH_QUOTE_EMITTED",
  "emitted_at_ms": 1746790800000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, inventory rebuilt from exec layer fills; cool-off resets to 0.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Adversary floods one side to push inventory skew to limit, halting the bot
• Spoof high realised-vol signal to induce quoting on illiquid markets

Mitigations

• Inventory skew limit and hard cap prevent runaway one-sided exposure
• Realised vol sourced from authenticated internal model; not user-configurable in real-time

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

VolatilityHarvest incidents are typically inventory skew breaches (auto-halt) or kill-switch activations. Cool-off triggers are expected normal behavior.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/volatilityharvest -> 200 if No market inventory skew > 0.50; vol model active; KillSwitch inactive.. Red: Any market at inventory hard limit or KillSwitch active..

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%