1.10 CapitalAllocator

1. Bot Identity

Operational profile

2. Purpose

CapitalAllocator carves the user's total risk budget across active strategies and refuses new orders that would cause any strategy slice or the aggregate portfolio to exceed its configured allocation. It emits a RESHAPE constraint when a downsize is possible, and HARD_REJECT when the budget is exhausted.

3. Why This Bot Matters

• Over-allocation to a single strategy

  Unconstrained capital flow into one strategy can consume the user's full budget, preventing diversification and concentrating tail risk.

• Aggregate portfolio budget exceeded

  Without a total-portfolio cap, concurrent strategies can collectively exceed the user's acceptable exposure, especially during correlated market events.

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

{ "per_strategy_max_usd": 2000 }

if (strategyExposure + intent.size_usd > params.per_strategy_max_usd) return reshape or reject;

{ "portfolio_total_max_usd": 10000 }

if (totalExposure + intent.size_usd > params.portfolio_total_max_usd) return reject('CAPITAL_ALLOCATOR_PORTFOLIO_BUDGET_EXCEEDED');

{ "min_remaining_buffer_pct": 0.05 }

if (remainingAfterOrder / portfolioCap < params.min_remaining_buffer_pct) return reshape({ max_size_usd: remainingBudget - bufferAmount });

8. Default Configuration

{
  "bot_id": "risk.capital_allocator",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "per_strategy_max_usd": 2000,
    "portfolio_total_max_usd": 10000,
    "min_remaining_buffer_pct": 0.05
  },
  "locked": {
    "per_strategy_max_usd": {
      "min": 100
    },
    "portfolio_total_max_usd": {
      "min": 500
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent with strategy_id, size_usd, and user context.
2. Check KillSwitch; if active, HARD_REJECT(KILL_SWITCH_ACTIVE).
3. Load capital allocation config (per_strategy_max_usd, portfolio_total_max_usd, buffer_pct) from internal store.
4. Fetch current strategy exposure (open + pending) for strategy_id from CLOB and position ledger.
5. Fetch total portfolio exposure across all strategies.
6. If strategy_exposure + intent.size_usd > per_strategy_max_usd: compute safe_size = max(0, per_strategy_max_usd - strategy_exposure). If safe_size > 0, RESHAPE; else HARD_REJECT.
7. If total_exposure + intent.size_usd > portfolio_total_max_usd * (1 - min_remaining_buffer_pct): RESHAPE or HARD_REJECT.
8. All checks passed — APPROVE with budget metrics attached.

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 evaluateCapital(intent):
  ks = FETCH internal.killswitch.status
  IF ks.active: EMIT RiskVote(HARD_REJECT, KILL_SWITCH_ACTIVE); RETURN

  config = FETCH internal.capital_config(intent.user_id)
  IF config IS NULL: EMIT RiskVote(HARD_REJECT, CAPITAL_ALLOCATOR_DATA_UNAVAILABLE); RETURN

  positions = FETCH clob.get_positions(intent.user_id, intent.strategy_id)
  IF positions IS NULL: EMIT RiskVote(HARD_REJECT, CAPITAL_ALLOCATOR_DATA_UNAVAILABLE); RETURN

  strategyExposure = positions.open_usd + positions.pending_usd
  totalExposure = positions.portfolio_total_usd

  // per-strategy check
  IF strategyExposure + intent.size_usd > config.per_strategy_max_usd:
    safeSize = config.per_strategy_max_usd - strategyExposure
    IF safeSize <= 0: EMIT RiskVote(HARD_REJECT, CAPITAL_ALLOCATOR_STRATEGY_BUDGET_EXCEEDED); RETURN
    EMIT RiskVote(RESHAPE_REQUIRED, constraints={max_size_usd: safeSize}); RETURN

  // portfolio buffer check
  buffer = config.portfolio_total_max_usd * config.min_remaining_buffer_pct
  IF totalExposure + intent.size_usd > config.portfolio_total_max_usd - buffer:
    EMIT RiskVote(HARD_REJECT, CAPITAL_ALLOCATOR_PORTFOLIO_BUDGET_EXCEEDED); RETURN

  EMIT RiskVote(APPROVE, checked_at=now_ms())

SDK calls used

• clob.get_positions(user_id, strategy_id)
• internal.capital_config(user_id)
• internal.killswitch.status()

Complexity: O(1) per strategy lookup

11. Wire Examples

Input — what arrives on the wire

OrderIntent — strategy budget overflow — internal

{
  "intent_id": "int_b2c3d4e5f6a70002",
  "strategy_id": "strat_001",
  "size_usd": 400,
  "generated_at_ms": 1746800000000
}

Output — what the bot emits

RiskVote — RESHAPE_REQUIRED

{
  "guard_id": "risk.capital_allocator",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "CAPITAL_ALLOCATOR_STRATEGY_BUDGET_EXCEEDED",
  "message": "Strategy exposure 1800 pUSD + 400 pUSD exceeds cap 2000. Resized to 200 pUSD.",
  "constraints": {
    "max_size_usd": 200
  },
  "checked_at": "2026-05-10T09:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.capital_allocator",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "CAPITAL_ALLOCATOR_STRATEGY_BUDGET_EXCEEDED",
  "message": "Strategy exposure 1800 pUSD + intent 400 pUSD exceeds cap 2000 pUSD. Resized to 200 pUSD.",
  "constraints": {
    "max_size_usd": 200
  },
  "inputs_used": [
    "internal.capital_config",
    "clob_public.positions"
  ],
  "checked_at": "2026-05-10T09:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.capital_allocator",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "CAPITAL_ALLOCATOR_STRATEGY_BUDGET_EXCEEDED",
  "inputs_used": [
    "internal.capital_config",
    "clob_public.positions"
  ],
  "metrics": {
    "strategy_exposure_usd": 1800,
    "portfolio_exposure_usd": 5400,
    "intent_size_usd": 400,
    "per_strategy_cap": 2000,
    "portfolio_cap": 10000
  },
  "checked_at": "2026-05-10T09:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, position snapshot loaded from CLOB before first evaluation. If unavailable, HARD_REJECT until restored.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Submitting concurrent intents to bypass per-strategy idempotency and double-count budget
• Poisoning the position cache to show lower exposure than actual

Mitigations

• Per-intent_id deduplication within 24h window prevents double-count
• Position cache is validated against CLOB on each refresh; stale data triggers fail-closed

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

Incidents typically involve a position cache sync delay causing false budget exhaustion, or a genuine portfolio cap breach requiring position reduction.

On-call actions

Manual overrides

• polytraders risk refresh-positions --user-id <id> — After a known CLOB sync delay; forces immediate position cache refresh.

Healthcheck

GET /internal/health/capitalallocator → green: Position cache age < 30s, CLOB reachable, no DATA_UNAVAILABLE rejections in last 5m; red: Position cache age > 60s or CLOB unreachable

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%