The Investment Policy Statement

Overview

An IPS is a versioned, status-tracked record encoded by the user during onboarding (and amended after). At any moment there is exactly one status = "active" row per user. That row is the contract the policy layer enforces.

Bundle shape

When the agent calls GET /api/agent/v1/mandate we hydrate the following:

Example payload

{
  "ipsVersion": 7,
  "tier": 2,
  "limits": {
    "cryptoMin": 0.10, "cryptoTarget": 0.20, "cryptoMax": 0.35,
    "tradfiMin": 0.55, "tradfiTarget": 0.65, "tradfiMax": 0.80,
    "cashFloor": 0.05,
    "maxDrawdown": 0.25,
    "maxSlippage": 0.01
  },
  "snapshot": {
    "totalValue": 482310,
    "cryptoPct": 0.22, "tradfiPct": 0.71, "cashPct": 0.07,
    "currentDrawdownPct": 0.136
  },
  "utilization": {
    "cryptoUsedPct": 0.48,
    "driftFromTarget": 0.02,
    "drawdownHeadroomPct": 0.114
  }
}

How bands work

• Min is the floor: the sleeve can’t drop below. A sell that would push it under returns crypto_min_allocation.
• Max is the ceiling: the sleeve can’t climb above. A buy that would push it over returns crypto_max_allocation.
• Target is the dial. The agent should size proposals toward target, not max. The rebalance logic doesn’t enforce it — that’s your call.

Standing rules + asset authority

On top of allocation bands, the IPS carries free-form standing rules (e.g. “never sell BTC”, “pause until 2026-12-31”) and per-asset authority levels (Protect, Monitor, Standard, Free). These show up as their own violation rules in validate responses — see the validate_trade reference.

Reading utilization

• cryptoUsedPct is normalized to (current − min) / (max − min). A value of 1.0 means you’re at the ceiling.
• drawdownHeadroomPct is maxDrawdown − currentDrawdownPct. Use it to size defensive trades.
• driftFromTarget is signed. Positive = over target, negative = under.