1.1 PortfolioGuard

1. Bot Identity

Operational profile

2. Purpose

PortfolioGuard enforces account-wide exposure limits across every running strategy simultaneously. It tracks aggregate notional, rolling 24-hour drawdown, per-market concentration, and correlated-cluster concentration. When an incoming order would breach any of these limits, it is either downsized to the safe remaining budget or rejected outright. PortfolioGuard does not change the strategy intent, the market, or the direction — it only sets the maximum size an order is allowed to carry.

3. Why This Bot Matters

• Aggregate notional exceeds account limit

  Multiple strategies running simultaneously could push total exposure beyond what the account balance can safely support, creating risk of insolvency if several positions move adversely at the same time.

• Single-market concentration unchecked

  Concentrating too much capital in one market means a single bad resolution or liquidity event can cause a disproportionate drawdown relative to the account size.

• 24-hour drawdown not tracked cross-strategy

  Each strategy sees only its own losses. Without a cross-strategy drawdown check, the total intraday loss can exceed a level the account is designed to tolerate.

• Correlated cluster exposure ignored

  On neg-risk or thematically linked markets, multiple strategies may each hold positions that all resolve together. Cluster concentration can make seemingly diversified positions highly correlated.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "max_account_notional_pct": 80 }

const budget = balance * p.hard - currentNotional; if (budget <= 0) return reject('STRATEGY_BUDGET_EXCEEDED'); if (order.size_usd > budget) return reshape({ max_size_usd: budget });

{ "max_24h_drawdown_pct": 10 }

const drawdownPct = rollingLoss24h / startingBalance; if (drawdownPct > p.hard) return reject('STRATEGY_BUDGET_EXCEEDED');

{ "max_per_market_pct": 20 }

const marketBudget = balance * p.hard - currentMarketExposure; if (marketBudget <= 0) return reject('STRATEGY_BUDGET_EXCEEDED');

{ "max_cluster_pct": 35 }

const clusterBudget = balance * p.hard - currentClusterExposure; if (clusterBudget <= 0) return reject('STRATEGY_BUDGET_EXCEEDED');

8. Default Configuration

{
  "bot_id": "risk.portfolio_guard",
  "version": "1.0.0",
  "mode": "hard_guard",
  "defaults": {
    "max_account_notional_pct": 80,
    "max_24h_drawdown_pct": 10,
    "max_per_market_pct": 20,
    "max_cluster_pct": 35
  },
  "locked": {
    "max_account_notional_pct": {
      "max": 80
    },
    "max_24h_drawdown_pct": {
      "max": 10
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer including market_id, side, and size_usd.
2. Check KillSwitch active flag; if active, return REJECT with KILL_SWITCH_ACTIVE immediately.
3. Fetch current account balance in USDC from on-chain to establish the capital base.
4. Pull aggregate notional across all open positions and pending orders from StrategyRegistry and Data API.
5. Check rolling 24-hour drawdown from Data API; if > max_24h_drawdown_pct hard limit, return REJECT with STRATEGY_BUDGET_EXCEEDED.
6. Compute aggregate_budget_remaining = balance × max_account_notional_pct − current_notional. If ≤ 0, return REJECT with STRATEGY_BUDGET_EXCEEDED.
7. Compute market_budget_remaining = balance × max_per_market_pct − current_market_exposure. If ≤ 0, return REJECT with STRATEGY_BUDGET_EXCEEDED.
8. Identify the cluster for this market_id (from Admin UI cluster map) and compute cluster_budget_remaining. If ≤ 0, return REJECT with STRATEGY_BUDGET_EXCEEDED.
9. Compute allowed_size = min(order.size_usd, aggregate_budget_remaining, market_budget_remaining, cluster_budget_remaining). If allowed_size < order.size_usd, return RESHAPE_REQUIRED with constraints.max_size_usd = allowed_size.
10. Return APPROVE with budget metrics attached to inputs_used and checked_at timestamp.

10. Reference Implementation

Reads the account balance, all open positions, and the rolling 24-hour P&L from the Data API, then enforces four independent budget checks (aggregate notional, 24h drawdown, per-market, cluster) before returning a RiskVote.

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

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

  // --- 1. Fetch portfolio state ---
  balanceRaw = FETCH clob_auth.GET('/wallet/balance')
  IF balanceRaw IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN
  balance = balanceRaw.pUSD  // pUSD collateral, 6 decimals via toUsdcUnits

  positions = FETCH data_api.GET('/positions?account=' + config.account_id)
  IF positions IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN

  pending = FETCH internal.strategy_registry.pending_orders()
  currentNotional = SUM(p.notional_usd FOR p IN positions)
                  + SUM(o.size_usd FOR o IN pending)

  // --- 2. 24h drawdown check ---
  pnl24h = FETCH data_api.GET('/pnl?account=' + config.account_id + '&window=24h')
  drawdownPct = (-pnl24h.realised - pnl24h.unrealised) / balance
  IF drawdownPct > params.max_24h_drawdown_pct.hard / 100:
    EMIT RiskVote(decision=HARD_REJECT, reason=STRATEGY_BUDGET_EXCEEDED)
    RETURN

  // --- 3. Aggregate notional check ---
  aggregateBudget = balance * params.max_account_notional_pct.hard / 100 - currentNotional
  IF aggregateBudget <= 0:
    EMIT RiskVote(decision=HARD_REJECT, reason=STRATEGY_BUDGET_EXCEEDED)
    RETURN

  // --- 4. Per-market check ---
  marketExposure = SUM(p.notional_usd FOR p IN positions IF p.market_id == intent.market_id)
  marketBudget = balance * params.max_per_market_pct.hard / 100 - marketExposure
  IF marketBudget <= 0:
    EMIT RiskVote(decision=HARD_REJECT, reason=STRATEGY_BUDGET_EXCEEDED)
    RETURN

  // --- 5. Cluster check ---
  cluster = FETCH internal.cluster_map.get(intent.market_id)
  clusterExposure = SUM(p.notional_usd FOR p IN positions IF cluster.has(p.market_id))
  clusterBudget = balance * params.max_cluster_pct.hard / 100 - clusterExposure
  IF clusterBudget <= 0:
    EMIT RiskVote(decision=HARD_REJECT, reason=STRATEGY_BUDGET_EXCEEDED)
    RETURN

  // --- 6. Compute allowed size ---
  allowedSize = min(intent.size_usd,
                    aggregateBudget, marketBudget, clusterBudget)
  allowedSize = toUsdcUnits(allowedSize)
  IF allowedSize < intent.size_usd:
    EMIT RiskVote(decision=RESHAPE_REQUIRED,
                  reason=STRATEGY_BUDGET_EXCEEDED,
                  constraints={ max_size_usd: allowedSize })
    RETURN

  // --- 7. Happy path ---
  EMIT RiskVote(decision=APPROVE, checked_at=now_iso())

Helpers used

SDK calls used

• clob_auth.GET('/wallet/balance')
• data_api.GET('/positions?account=...')
• data_api.GET('/pnl?account=...&window=24h')
• internal.strategy_registry.pending_orders()
• internal.cluster_map.get(market_id)
• internal.killswitch.status()

Complexity: O(P) where P = number of open positions

11. Wire Examples

Input — what arrives on the wire

OrderIntent requiring per-market reshape — internal

{
  "intent_id": "int_4d5e6f7a8b9c0d1e",
  "market_id": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c",
  "side": "BUY",
  "outcome": "YES",
  "size_usd": 1200,
  "generated_at": "2026-05-09T08:15:00Z"
}

Portfolio state snapshot — data_api

{
  "account_balance_pusd": 10000,
  "current_notional_usd": 7500,
  "market_exposure_usd": 1150,
  "cluster_exposure_usd": 2100,
  "rolling_24h_pnl_usd": -420,
  "rolling_24h_drawdown_pct": 4.2
}

Output — what the bot emits

RiskVote — RESHAPE_REQUIRED (per-market limit binding)

{
  "guard_id": "risk.portfolio_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "message": "Order size 1200 pUSD exceeds per-market budget remaining of 850 pUSD. Resized to 850 pUSD.",
  "constraints": {
    "max_size_usd": 850,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "clob_auth.balance",
    "data_api.positions",
    "strategy_registry.pending_orders"
  ],
  "checked_at": "2026-05-09T08:15:00Z"
}

RiskVote — HARD_REJECT (drawdown circuit breaker)

{
  "guard_id": "risk.portfolio_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "message": "Rolling 24h drawdown 10.3% exceeded hard limit 10%. All new orders blocked.",
  "constraints": {},
  "inputs_used": [
    "data_api.pnl",
    "clob_auth.balance"
  ],
  "checked_at": "2026-05-09T09:00:00Z"
}

Reproduce locally

curl -H 'Authorization: Bearer <token>' 'https://clob.polymarket.com/wallet/balance'

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.portfolio_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "message": "Order size 1200 USD exceeds per-market budget remaining of 850 USD. Resized to 850 USD.",
  "constraints": {
    "max_size_usd": 850,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "on-chain.balance",
    "data_api.positions",
    "strategy_registry.pending_orders"
  ],
  "checked_at": "2026-05-09T08:15:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / PortfolioGuard
• Grafana — Account exposure / drawdown and notional utilisation

Log levels

16. Developer Reporting

{
  "bot_id": "risk.portfolio_guard",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "STRATEGY_BUDGET_EXCEEDED",
  "inputs_used": [
    "on-chain.balance",
    "data_api.positions",
    "strategy_registry.pending_orders"
  ],
  "metrics": {
    "account_balance_usd": 10000,
    "current_notional_usd": 7500,
    "aggregate_budget_remaining_usd": 500,
    "current_market_exposure_usd": 1150,
    "market_budget_remaining_usd": 850,
    "cluster_budget_remaining_usd": 2100,
    "rolling_24h_drawdown_pct": 4.2
  },
  "allowed_size_usd": 850,
  "checked_at": "2026-05-09T08:15:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Maintains a durable Postgres ledger of positions and budgets, refreshed on every fill event and reconciliation cycle.

State stores

Cold-start recovery

On cold start, position_ledger is read from Postgres. drawdown_snapshot is re-fetched from Data API.

On restart

Postgres state is immediately available. Redis drawdown cache is rebuilt within one polling cycle (60s).

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

Used by (auto-aggregated)

2.1 2.2 1.2 1.3 1.4 1.6

External services

23. Security Surfaces

PortfolioGuard reads account balance and position data via authenticated API calls. It never signs orders or holds private keys.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Feeding a stale or low balance snapshot to inflate available budget
• Racing two intents simultaneously to double-count the same budget

Mitigations

• per-market_id mutex prevents concurrent budget double-counting
• Balance and position snapshots older than 60s are rejected as STALE_MARKET_DATA
• Postgres position_ledger provides strong-consistency ground truth

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

PortfolioGuard incidents typically involve drawdown breaches or stale ledger data. Drawdown breaches require manual review before reset; ledger staleness should be resolved via Data API connectivity.

On-call actions

Manual overrides

• polytraders bot reset-drawdown risk.portfolio_guard — Manually clears the 24h drawdown circuit breaker. Requires Risk pod lead sign-off.
• polytraders bot pause risk.portfolio_guard — Stops emitting RiskVotes. All intents pass without portfolio checks. Use only with Risk pod lead explicit approval.

Healthcheck

GET /health → 200 if Postgres position_ledger is reachable and last balance fetch is < 60s old.

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%