6.7 Portfolio Sync

1. Bot Identity

2. Purpose

PortfolioSync keeps the in-memory portfolio state — open positions and open orders — continuously synchronised with on-chain pUSD balances and CLOB open-order state. It reconciles the internal position store against clob_auth open orders and the Polygon on-chain balance every sync_interval_s. For negative-risk markets (NegRiskAdapter), it correctly aggregates multi-outcome positions using the negRisk flag. On discrepancy beyond discrepancy_alert_usd, it emits an alert and, if configured, pauses the affected strategy to prevent trading against a stale view of risk. Emits both a SettlementReport (position deltas) and an OperationsReport (sync health) on every cycle.

3. Why This Bot Matters

• In-memory position state drifts from on-chain reality

  Strategies trade against a stale position view. Risk guards (PortfolioGuard, KillSwitch) see incorrect exposure, potentially allowing positions that exceed risk limits.

• Negative-risk positions aggregated incorrectly

  Multi-outcome positions in negRisk markets have correlated payoffs. Treating them as independent binary positions overstates available margin and may cause liquidation.

• Open-order count diverges from CLOB

  Strategies submit orders assuming capacity that no longer exists. This inflates fill expectations and distorts P&L projections.

• Strategy not paused on drift beyond threshold

  Trading continues against a stale portfolio state. Risk exposure is uncontrolled until the next successful sync cycle.

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

{ "sync_interval_s": 30 }

if (p.sync_interval_s > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "discrepancy_alert_usd": 10 }

if (drift > p.hard) alerting.emit('PORTFOLIO_SYNC_CRITICAL_DISCREPANCY', { drift_pusd: drift })

{ "auto_pause_strategy_on_drift": true }

if (p.auto_pause_strategy_on_drift && drift > p.discrepancy_alert_usd.hard) pauseStrategy(affected_strategy_id)

8. Default Configuration

{
  "bot_id": "gov.portfolio_sync",
  "version": "2.0.0",
  "mode": "general_live",
  "defaults": {
    "sync_interval_s": 30,
    "discrepancy_alert_usd": 10,
    "auto_pause_strategy_on_drift": true
  },
  "locked": {
    "sync_interval_s": {
      "max": 300
    },
    "discrepancy_alert_usd": {
      "max": 500
    }
  }
}

9. Implementation Flow

1. Every sync_interval_s, snapshot the internal in-memory position store (all open positions and open orders).
2. Fetch open orders from clob_auth for the wallet address; fetch on-chain pUSD balance from Polygon RPC.
3. For each open position in the internal store: fetch the corresponding CLOB position and compare size, side, and average cost.
4. For negative-risk markets (negRisk=true): use the NegRiskAdapter aggregation to compute the combined multi-outcome position before comparing.
5. Compute drift_pusd = abs(internal_position_pusd - clob_position_pusd) for each market.
6. If drift_pusd > discrepancy_alert_usd: emit WARN PORTFOLIO_SYNC_DISCREPANCY; if drift_pusd > discrepancy_alert_usd.hard, emit page and optionally pause strategy (auto_pause_strategy_on_drift).
7. Apply deltas to the internal position store: add missing positions, remove closed positions, update sizes.
8. Emit SettlementReport for each position delta (position added, removed, or updated).
9. Emit OperationsReport for the full sync cycle: total_positions, synced_count, discrepancy_count, drift_pusd_max, sync_duration_ms.
10. Retain SettlementReports for 7 years (position deltas are regulatory records). OperationsReports retained 1 year.

10. Reference Implementation

Every sync_interval_s: snapshots internal state, fetches CLOB open orders and on-chain pUSD balance, reconciles per-market positions (with negRisk aggregation), applies deltas, emits SettlementReport per delta and OperationsReport per cycle.

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

// ---- SYNC LOOP ----
FUNCTION runSync():
  sync_start = now()
  internal_snapshot = position_store.snapshot()  // all open positions

  // Fetch external state
  clob_orders = FETCH clob_auth.GET('/orders?wallet=' + wallet_address)
    ON_FAILURE: EMIT OperationsReport(event_type='PORTFOLIO_SYNC_CLOB_UNAVAILABLE'); RETURN
  onchain_balance = FETCH onchain.getBalance(wallet_address, 'pUSD')
    ON_FAILURE: EMIT OperationsReport(event_type='PORTFOLIO_SYNC_RPC_UNAVAILABLE'); RETURN

  // Reconcile per-market
  discrepancy_count = 0; drift_max = 0; deltas = []

  FOR market_id IN union(keys(internal_snapshot), keys(clob_orders)):
    internal_pos = internal_snapshot.get(market_id, ZERO)
    clob_pos = clob_orders.get(market_id, ZERO)

    market_meta = FETCH clob_auth.getMarketByConditionId(market_id)
    IF market_meta.negRisk:
      // Aggregate all outcome tokens via NegRiskAdapter
      clob_pos = negRiskAggregate(clob_orders, market_id)
      internal_pos = negRiskAggregate(internal_snapshot, market_id)

    drift_pusd = abs(internal_pos.size_pusd - clob_pos.size_pusd)
    drift_max = max(drift_max, drift_pusd)

    IF drift_pusd > config.discrepancy_alert_usd:
      discrepancy_count += 1
      alerting.emit('PORTFOLIO_SYNC_DISCREPANCY', { market_id, drift_pusd })

    IF drift_pusd > config.discrepancy_alert_usd.hard:  // 500 pUSD
      alerting.emit('PORTFOLIO_SYNC_CRITICAL_DISCREPANCY', { market_id, drift_pusd })
      IF config.auto_pause_strategy_on_drift:
        pauseStrategy(getStrategyForMarket(market_id))
        EMIT SettlementReport(event_type='PORTFOLIO_SYNC_STRATEGY_PAUSED', ...)

    delta_type = computeDeltaType(internal_pos, clob_pos)
    IF delta_type != 'NO_CHANGE':
      position_store.apply(market_id, clob_pos)
      deltas.append({ market_id, delta_type, drift_pusd, negRisk: market_meta.negRisk })
      EMIT SettlementReport(event_type='POSITION_DELTA', market_id=market_id, ...)

  // Ops report for this cycle
  EMIT OperationsReport({
    event_type:       'SYNC_CYCLE_COMPLETE',
    total_positions:  len(union(internal_snapshot, clob_orders)),
    synced_count:     len(deltas),
    discrepancy_count: discrepancy_count,
    drift_pusd_max:   drift_max,
    onchain_balance:  onchain_balance,
    sync_duration_ms: now() - sync_start
  })

SDK calls used

• clob_auth.GET('/orders?wallet=<address>')
• clob_auth.getMarketByConditionId(market_id)
• onchain.getBalance(wallet_address, 'pUSD')
• negRiskAggregate(orders, market_id)
• alerting.emit('PORTFOLIO_SYNC_DISCREPANCY', { market_id, drift_pusd })
• pauseStrategy(strategy_id)

Complexity: O(M) per sync cycle where M = number of open markets

11. Wire Examples

Input — what arrives on the wire

{
  "label": "CLOB open orders response",
  "source": "clob_auth",
  "payload": {
    "wallet": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
    "open_orders": [
      {
        "order_id": "ord_00456",
        "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
        "side": "BUY",
        "size_pusd": 1250.0,
        "price": 0.6,
        "negRisk": false,
        "timestamp": 1746791900000
      }
    ],
    "onchain_balance_pusd": 52341.0
  }
}

Output — what the bot emits

{
  "label": "SettlementReport — POSITION_DELTA",
  "payload": {
    "report_id": "settlement_portfoliosync_1746792000000",
    "bot_id": "gov.portfolio_sync",
    "event_type": "POSITION_DELTA",
    "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
    "delta_type": "UPDATED",
    "internal_size_pusd": 1200.0,
    "clob_size_pusd": 1250.0,
    "drift_pusd": 50.0,
    "negRisk": false,
    "action_taken": "internal_store_updated",
    "synced_at_ms": 1746792000000,
    "report_kind": "SettlementReport",
    "retained_until": "2033-05-09"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a SettlementReport object. See SettlementReport schema.

{
  "report_id": "settlement_portfoliosync_1746792000000",
  "bot_id": "gov.portfolio_sync",
  "event_type": "POSITION_DELTA",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "delta_type": "UPDATED",
  "internal_size_pusd": 1200.0,
  "clob_size_pusd": 1250.0,
  "drift_pusd": 50.0,
  "negRisk": false,
  "action_taken": "internal_store_updated",
  "synced_at_ms": 1746792000000,
  "report_kind": "SettlementReport"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Governance / PortfolioSync position drift timeline
• Grafana — Governance / PortfolioSync negRisk position aggregation

16. Developer Reporting

{
  "bot_id": "gov.portfolio_sync",
  "event_type": "SYNC_CYCLE_COMPLETE",
  "total_positions": 12,
  "synced_count": 11,
  "discrepancy_count": 1,
  "drift_pusd_max": 50.0,
  "negRisk_positions": 2,
  "paused_strategies": [],
  "sync_duration_ms": 420,
  "synced_at_ms": 1746792000000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, position_store is rebuilt from a full CLOB sync on startup. First sync cycle restores complete state before any trading is allowed.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

Used by (auto-aggregated)

6.3

External services

23. Security Surfaces

Abuse vectors considered

• Raising discrepancy_alert_usd hard threshold to suppress critical drift alerts
• Disabling auto_pause_strategy_on_drift to allow trading against stale state
• Manipulating the CLOB open-order response to show smaller positions than actual

Mitigations

• discrepancy_alert_usd has a hard maximum of 500 pUSD enforced at config load
• sync_interval_s has a hard maximum of 300s enforced at config load
• On-chain balance provides an independent cross-check that cannot be manipulated via CLOB API
• PortfolioSync never signs orders or holds private keys — read-only access to CLOB and RPC

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

PortfolioSync incidents fall into: critical position drift (strategy auto-paused), CLOB/RPC unavailability (sync skipped), or negRisk misconfiguration (silent exposure undercount). Drift above 500 pUSD is always P1.

On-call actions

Manual overrides

• polytraders gov portfolio force-sync — Trigger an immediate full sync cycle outside the normal interval.
• polytraders gov portfolio resume-strategy --strategy-id <id> --reviewed-by <operator> — Resume an auto-paused strategy after drift root cause has been investigated and resolved.

Healthcheck

Endpoint: /internal/health/portfolio-sync | Green: Last sync cycle completed within 2x sync_interval_s; CLOB reachable; discrepancy_count = 0; no strategies paused. | Red: No sync in 2x sync_interval_s; CLOB unavailable > 5 min; critical drift detected; strategies paused.

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%