1.6 InventoryUnwinder

1. Bot Identity

Operational profile

2. Purpose

InventoryUnwinder detects when a position has breached its concentration or capital limit — either because an OrderIntent would push it over, or because an existing position is already over the limit (e.g. after a parameter change or strategy crash). When a breach is detected it generates unwind OrderIntents targeting the source bot, using the NegRiskAdapter on Polygon for negRisk markets, and routes them back into the execution pipeline. It can also hard-reject incoming intents that would worsen an already-breached position. Builder codes from the original strategy are preserved on unwind intents for attribution. Fail-closed: if position data is unavailable, all new intents for the affected market are rejected.

3. Why This Bot Matters

• Concentration limit breach not unwound

  A position that exceeds the declared inventory band creates directional exposure larger than the strategy risk envelope can justify, leading to losses that compound if the market moves against the position.

• Capital limit not enforced on position growth

  Without an active unwind, capital can become trapped in a single position, reducing the portfolio's ability to respond to other opportunities or drawdowns.

• NegRisk market unwind without NegRiskAdapter

  For multi-outcome negRisk markets, naively selling YES tokens may not fully close the position or may leave residual NO exposure. The NegRiskAdapter burn-and-redeem path must be used to correctly exit.

• Strategy crash leaves open inventory

  If a strategy halts mid-session with open inventory, the position will remain on the book indefinitely unless InventoryUnwinder detects and liquidates it.

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

{ "max_inventory_band": 1000 }

if (position > p.hard) generateUnwindIntents(market_id, position - p.warning); else if (position > p.warning) warn('INVENTORY_UNWINDER_BAND_WARN');

{ "unwind_aggression": 50 }

const orderType = aggression == 100 ? 'IOC' : aggression >= 75 ? 'LIMIT_CROSS' : 'LIMIT_PASSIVE'; buildUnwindOrder(market_id, size, orderType);

{ "passive_only": true }

if (params.passive_only) intent.order_type = 'POST_ONLY';

{ "handback_threshold_pct": 80 }

if (position <= max_inventory_band * p.handback_threshold_pct / 100) emitDecisionReport('UNWIND_COMPLETE', source_bot_id);

8. Default Configuration

{
  "bot_id": "risk.inventory_unwinder",
  "version": "2.0.0",
  "mode": "hard_guard",
  "defaults": {
    "max_inventory_band": 1000,
    "unwind_aggression": 50,
    "passive_only": true,
    "handback_threshold_pct": 80
  },
  "locked": {
    "max_inventory_band": {
      "min": 100
    },
    "handback_threshold_pct": {
      "max": 95
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer or trigger from periodic position-scan cycle.
2. Check KillSwitch active flag; if active, reject the incoming intent and begin emergency unwind of all open inventory above zero.
3. Fetch current open positions for the target market from clob_auth. If position data is unavailable, reject the incoming intent with STALE_MARKET_DATA (fail-closed).
4. Compare current position size against max_inventory_band. If already at or above the hard limit, hard-reject the incoming intent with INVENTORY_UNWINDER_BAND_BREACH.
5. Fetch market metadata from Gamma to check negRisk and enableNegRisk flags. For negRisk markets, determine whether the NegRiskAdapter unwind path is required (burn NO tokens → pUSD via NegRiskAdapter on Polygon).
6. Compute unwind_size = current_position - (max_inventory_band × handback_threshold_pct / 100). If unwind_size > 0, generate one or more unwind OrderIntents sized to bring the position back to the handback threshold.
7. Attach the source bot's builder code (bytes32) to each unwind OrderIntent for attribution tracking. This ensures unwind fills are credited to the original strategy.
8. Set order type on unwind intents based on passive_only flag and unwind_aggression: POST_ONLY if passive_only=true, otherwise LIMIT or IOC based on aggression level.
9. Emit unwind OrderIntents back into the execution pipeline. Emit a RiskVote (HARD_REJECT or RESHAPE) for the incoming intent if it would worsen the breach.
10. Emit a DecisionReport with UNWIND_COMPLETE when position falls to or below the handback threshold.

10. Reference Implementation

Evaluates incoming OrderIntent against the current position size. If a breach is detected (or is already present), generates unwind OrderIntents with the source bot's builder code, using the NegRiskAdapter path for negRisk markets. Emits RiskVote (REJECT/RESHAPE) for the incoming intent and DecisionReport when unwind completes.

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

FUNCTION evaluateInventory(intent):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT RiskVote(decision=HARD_REJECT, reason=KILL_SWITCH_ACTIVE)
    startEmergencyUnwindAll()
    RETURN

  // --- 1. Fetch current position ---
  position = FETCH clob_auth.GET('/positions?market=' + intent.market_id)
  IF position IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN
  currentSize = position.net_size_pusd

  // --- 2. Fetch market metadata ---
  market = FETCH gamma.getMarketByConditionId(intent.market_id)
  IF market IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN

  // --- 3. Check if existing position already breaches band ---
  IF currentSize >= params.max_inventory_band.hard:
    // Reject intent that would worsen the breach
    IF intent.side == position.side:
      EMIT RiskVote(decision=HARD_REJECT, reason=INVENTORY_UNWINDER_BAND_BREACH)
    // Generate unwind intents
    unwindSize = currentSize - (params.max_inventory_band.hard * params.handback_threshold_pct / 100)
    builderCode = FETCH internal.strategy_registry.builder_code(position.source_bot_id)
    IF market.negRisk:
      unwindIntents = buildNegRiskUnwindIntents(market, unwindSize, builderCode)
    ELSE:
      unwindIntents = buildStandardUnwindIntents(market, unwindSize, builderCode)
    FOR ui IN unwindIntents:
      EMIT OrderIntent(ui)  // back into execution pipeline
    RETURN

  // --- 4. Check if incoming intent would cause breach ---
  projectedSize = currentSize + (intent.size_usd IF intent.side == position.side ELSE 0)
  IF projectedSize > params.max_inventory_band.hard:
    allowedSize = params.max_inventory_band.hard - currentSize
    IF allowedSize <= 0:
      EMIT RiskVote(decision=HARD_REJECT, reason=INVENTORY_UNWINDER_BAND_BREACH)
    ELSE:
      EMIT RiskVote(decision=RESHAPE_REQUIRED,
                    reason=INVENTORY_UNWINDER_BAND_BREACH,
                    constraints={max_size_usd: allowedSize})
    RETURN

  // --- 5. Warn if approaching band ---
  IF projectedSize > params.max_inventory_band.warning:
    EMIT RiskVote(decision=APPROVE,
                  annotations=[{code: INVENTORY_UNWINDER_BAND_WARN}])
    RETURN

  // --- 6. Approve ---
  EMIT RiskVote(decision=APPROVE, checked_at=now_iso())

FUNCTION buildNegRiskUnwindIntents(market, size, builderCode):
  // Use NegRiskAdapter: burn NO tokens across outcome set → pUSD
  onchainBalance = FETCH onchain.tokenBalance(market.condition_id, 'NO')
  burnAmount = min(size, toPusdUnits(onchainBalance))
  // If sum(YES prices) < $1, convert-arb: also re-mint YES
  yesSum = SUM(FETCH clob_public.price(o) FOR o IN market.outcomes)
  IF yesSum < 1.0:
    RETURN [NegRiskAdapterBurnOrder(burnAmount, builderCode),
            NegRiskAdapterMintYesOrder(burnAmount, builderCode)]
  RETURN [NegRiskAdapterBurnOrder(burnAmount, builderCode)]

SDK calls used

• clob_auth.GET('/positions?market=0xabc...')
• gamma.getMarketByConditionId(market_id)
• clob_public.GET('/book?market=0xabc...&depth=1')
• onchain.tokenBalance(condition_id, outcome='NO')
• toPusdUnits(rawBalance)
• internal.strategy_registry.builder_code(bot_id)
• internal.killswitch.status()
• buildOrderTypedData(unwindIntent)

Complexity: O(N) where N = number of open positions in breach; typically O(1) per single-market evaluation

11. Wire Examples

Input — what arrives on the wire

OrderIntent — BUY into already-breached position — internal

{
  "intent_id": "int_a1b2c3d4e5f60718",
  "market_id": "0x5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "side": "BUY",
  "outcome": "YES",
  "size_usd": 300,
  "price": 0.71,
  "neg_risk": true,
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "generated_at_ms": 1746784200000
}

Current position snapshot (clob_auth) — clob_auth

{
  "market_id": "0x5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "side": "BUY",
  "net_size_pusd": 1250,
  "cost_basis_pusd": 887,
  "source_bot_id": "strat.mm_v2",
  "fetched_at_ms": 1746784195000
}

Output — what the bot emits

RiskVote — HARD_REJECT (band already breached, intent would worsen)

{
  "guard_id": "risk.inventory_unwinder",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "INVENTORY_UNWINDER_BAND_BREACH",
  "message": "Position 1250 pUSD exceeds max_inventory_band 1000 pUSD. BUY intent rejected; 1 NegRisk unwind intent emitted.",
  "constraints": {},
  "inputs_used": [
    "clob_auth.positions",
    "gamma.market.negrisk",
    "internal.strategy_registry.builder_code",
    "internal.killswitch.status"
  ],
  "unwind_intents_emitted": 1,
  "checked_at": "2026-05-09T11:05:00Z"
}

DecisionReport — UNWIND_COMPLETE

{
  "report_id": "rpt_f1e2d3c4b5a60718",
  "guard_id": "risk.inventory_unwinder",
  "event": "UNWIND_COMPLETE",
  "market_id": "0x5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "position_after_pusd": 795,
  "handback_threshold_pusd": 800,
  "source_bot_id": "strat.mm_v2",
  "completed_at": "2026-05-09T11:05:48Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.inventory_unwinder",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "INVENTORY_UNWINDER_BAND_BREACH",
  "message": "Position 1250 pUSD in market 0x7f8a... exceeds max_inventory_band 1000 pUSD. Incoming BUY intent rejected; unwind OrderIntents emitted.",
  "constraints": {},
  "inputs_used": [
    "clob_auth.positions",
    "gamma.market.negrisk",
    "internal.strategy_registry.builder_code",
    "internal.killswitch.status"
  ],
  "unwind_intents_emitted": 2,
  "checked_at": "2026-05-09T11:05:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / InventoryUnwinder
• Grafana — Position management / inventory band utilisation and unwind history

16. Developer Reporting

{
  "bot_id": "risk.inventory_unwinder",
  "decision": "HARD_REJECT",
  "reason_code": "INVENTORY_UNWINDER_BAND_BREACH",
  "inputs_used": [
    "clob_auth.positions",
    "gamma.market.negrisk"
  ],
  "metrics": {
    "current_position_pusd": 1250,
    "max_inventory_band": 1000,
    "unwind_size_pusd": 450,
    "negrisk": true,
    "unwind_adapter": "NegRiskAdapter",
    "source_bot_builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000"
  },
  "checked_at": "2026-05-09T11:05:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, position cache is empty. First evaluation per market triggers a blocking fetch from clob_auth. If fetch fails, order is rejected fail-closed until cache is populated.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Strategy attempting to bypass unwind by splitting large orders into many small intents just below max_inventory_band
• Race condition: two strategies simultaneously adding to the same market to exceed the band before either triggers an unwind
• Manipulated position feed showing lower-than-actual position to delay unwind trigger

Mitigations

• Per-market_id mutex prevents concurrent evaluation for the same market
• Periodic position-scan cycle (every 30s) catches breaches that slip past per-intent checks
• Position cache has strict staleness TTL (120s); expired cache → HARD_REJECT, no bypass possible

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

InventoryUnwinder incidents are typically caused by a position that has grown beyond the inventory band and an unwind that is stuck (no fills), or by stale position data from clob_auth preventing detection. Stuck unwinds require manual review of book liquidity and aggression settings.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/inventoryunwinder → 200 if position cache for all active markets is within TTL, no active unwind has been stuck for > 60s, and clob_auth and Gamma API are reachable; red if any position cache is expired and clob_auth is unreachable, or an active unwind has been in-flight for > 300s without position reduction.

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%