API · Validate

Validate trade

The headline endpoint. Dry-runs the proposed trade against every guardrail, audit-logs the decision, and returns a structured allow/deny with violations.

POST/api/agent/v1/policy/validatescope: validate

Request body

FieldTypeDescription
actionrequired
string
buysell
Direction of the trade.
assetSymbolrequired
string
Ticker (e.g. "BTC", "AAPL").
assetTyperequired
string
cryptotradfi
Asset class. Crypto and tradfi have separate IPS bands.
amountUsdrequired
number
Notional in USD. Must be ≥ 0.
expectedSlippagePct
number
Optional. Expected slippage in percent (0.5 = 50 bps). Compared against the IPS max-slippage limit.
curl
curl -X POST https://api.advisorscrypto.com/api/agent/v1/policy/validate \
  -H "Authorization: Bearer ac_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "buy",
    "assetSymbol": "BTC",
    "assetType": "crypto",
    "amountUsd": 5000
  }'

Response — allowed

200 OK
{
  "allowed": true,
  "reason": "Within policy",
  "violations": [],
  "ipsVersion": 7,
  "snapshot": {
    "totalValue": 482310,
    "cryptoValue": 106108.20,
    "tradfiValue": 342440.10,
    "cashValue": 33761.70,
    "cryptoPct": 0.22,
    "tradfiPct": 0.71,
    "cashPct": 0.07,
    "currentDrawdownPct": 0.136
  },
  "checkedAt": "2026-06-15T05:50:19Z"
}

Response — blocked

200 OK (with violations)
{
  "allowed": false,
  "reason": "1 violation",
  "violations": [
    {
      "rule": "crypto_max_allocation",
      "message": "Would push crypto sleeve to 36.4% — cap is 35%.",
      "limit": 0.35,
      "actual": 0.364
    }
  ],
  "ipsVersion": 7,
  "snapshot": { /* ... */ },
  "checkedAt": "2026-06-15T05:50:19Z"
}

Violation rules

The full set of rule values that can fire:

  • no_active_ips — user hasn’t encoded an IPS.
  • no_portfolio_snapshot — we couldn’t build a snapshot.
  • action_not_allowed — buy/sell is currently paused for the user.
  • crypto_max_allocation / crypto_min_allocation
  • tradfi_max_allocation / tradfi_min_allocation
  • cash_floor — sell would push cash below floor.
  • insufficient_cash — buy without enough cash.
  • drawdown_exceeded — would push past the IPS drawdown limit.
  • slippage_exceeded — expected slippage above cap.
  • agent_aum_cap — per-agent AUM cap reached.
  • asset_authority_monitor / asset_authority_protect_sell — asset authority level blocks this action.
  • standing_rule_blocked / standing_rule_requires_approval
  • invalid_payload — malformed input.

Side effects

  • Audit log. Every call lands in the audit feed, attributed to your agent key, regardless of outcome.
  • No execution. Validate never writes to a ServiceRequest, never queues an attestation, never touches a custodian.
Last updated 2026-06-15
Suggest an edit·Changelog