API v2 (alpha)

Pre-stable. /v2/portfolio-risk-state is at 2.0.0-alpha.5 and /v2/stress-scenario is at 2.0.0-alpha.2. Breaking changes may occur with 2-week notice until 2.0.0. Use v1 for production-stable workflows that don't need portfolio-level aggregation or stress.

The v2 surface adds portfolio-aware endpoints on top of the v1 per-asset engine. v1 answers "what's the policy for BTC right now?" — v2 answers "given my actual book of N positions, am I within risk and what would happen under a flash crash?"

Endpoints

Both endpoints share the same positions[] request schema, the same Bearer auth, and write to the same audit-decisions blob store readable via GET /v2/audit/decisions.

Score freeze. Both endpoints inherit scoring_version: "score_v3" from v1. The score_v3 freeze is in effect until 2026-10-22 — no weight, normalisation, threshold, cap, or aggregation logic will change before then. v2 alpha changes are additive (new fields, clarified contracts) and respect the freeze.

Authentication

Identical to v1.

Authorization: Bearer <your_api_key>

Request a key from the home page — only an email is required. Free during beta. Both v1 and v2 endpoints accept the same key.

POST /v2/portfolio-risk-state

Multi-position aggregation. Up to 50 positions, BTC + ETH only, with optional per-issuer stablecoin holdings.

POST https://riskstate.netlify.app/v2/portfolio-risk-state

Request

{
  "positions": [
    { "asset": "BTC", "size_usd": 250000, "side": "long" },
    { "asset": "ETH", "size_usd": 80000,  "side": "long" }
  ],
  "stablecoin_holdings_usd": { "USDT": 50000, "USDC": 50000 },
  "include_details": false
}

Response — what's in it

The response groups into 5 blocks. The full schema is documented in specs/api/portfolio-risk-state-examples.md (12 worked scenarios + smoke script). The high-impact fields:

Example response (alpha.5)

A 75/25 BTC/ETH long-only book with $100k stables, BTC oversized vs the per-asset cap:

{
  "api_version": "2.0.0-alpha.5",
  "scoring_version": "score_v3",
  "ttl_seconds": 60,
  "portfolio": {
    "gross_exposure_usd": 330000,
    "long_exposure_usd": 330000,
    "short_exposure_usd": 0,
    "net_exposure_usd": 330000,
    "total_notional_usd": 430000,
    "stablecoin_holdings_usd": 100000,
    "stablecoin_concentration_pct": 23.26,
    "weighted_composite": 54,
    "weighted_risk_permission_score": 48,
    "portfolio_allowed": true,
    "btc_equivalent_net_usd": 351840,
    "btc_equivalent_gross_usd": 351840
  },
  "correlations": {
    "source": "live",
    "matrix": { "BTC": { "BTC": 1.0, "ETH": 0.81 }, "ETH": { "BTC": 0.81, "ETH": 1.0 } },
    "beta": { "BTC": 1.0, "ETH": 1.273 }
  },
  "positions": [
    {
      "index": 0, "asset": "BTC", "size_usd": 250000, "side": "long",
      "policy_level": 4, "direction_bias": "LONG_PREFERRED",
      "max_size_fraction": 0.42, "max_size_usd": 180600,
      "actual_pct": 58.14, "oversize_factor": 1.384,
      "direction_conflict": false,
      "allowed": false,
      "reason_codes": ["POSITION_OVER_MAX_SIZE"],
      "advisories": []
    },
    {
      "index": 1, "asset": "ETH", "size_usd": 80000, "side": "long",
      "policy_level": 4, "direction_bias": "LONG_PREFERRED",
      "max_size_fraction": 0.48, "max_size_usd": 206400,
      "actual_pct": 18.60, "oversize_factor": 0.388,
      "direction_conflict": false,
      "allowed": true,
      "reason_codes": [],
      "advisories": []
    }
  ],
  "portfolio_risk_flags": {
    "structural_blockers": [],
    "context_risks": ["BTC:HIGH_COUPLING"],
    "concentration_warnings": [],
    "stablecoin_warnings": []
  },
  "stablecoin_breakdown": {
    "issuers": [
      { "issuer": "USDT", "name": "Tether", "amount_usd": 50000, "pct_of_stables": 50.0, "pct_of_total": 11.63, "peg_deviation_pct": 0.02, "peg_status": "OK" },
      { "issuer": "USDC", "name": "USD Coin", "amount_usd": 50000, "pct_of_stables": 50.0, "pct_of_total": 11.63, "peg_deviation_pct": -0.01, "peg_status": "OK" }
    ]
  },
  "auditability": {
    "computed_at": "2026-05-05T11:32:14.123Z",
    "latency_ms": 184,
    "key_type": "external",
    "audit_id": "1714905134123-a3kf7p",
    "cache_status": {
      "BTC": { "hit": true, "age_ms": 14000 },
      "ETH": { "hit": true, "age_ms": 14000 }
    }
  }
}

How to read this:

• portfolio.portfolio_allowed: true — concentration is a non-issue here (BTC 75.76% gross of crypto-only is the older view; gross of TOTAL notional including stables is 58.14%).
• positions[0].allowed: false because BTC's actual_pct (58.14) exceeds the per-asset cap max_size_fraction (42) × 100. The fix is either reduce BTC or grow the book.
• correlations.source: "live" means the matrix was fetched fresh; "cache" means it was served from the 1h-cached snapshot.

reason_codes vs advisories

Each per-position assessment reports two arrays. They are deliberately separated.

reason_codes values:

• STRUCTURAL_BLOCK_<TAG> — propagated from per-asset risk flags. Hard structural blocker on the underlying asset.
• POSITION_OVER_MAX_SIZE — actual_pct > max_size_fraction.

advisories values:

• DIRECTION_BIAS_OPPOSITE — position side fights the engine's direction_bias. Mirrored by the boolean direction_conflict.
• NEW_ENTRY_BLOCKED_BY_ENGINE — the per-asset blocked_actions includes NEW_ENTRY. Existing positions within cap aren't blocked by this endpoint, but customer's own opening workflow should respect this.
• ALL_IN_BLOCKED_BY_ENGINE — same pattern for ALL_IN.

Pre-2026-05-04 these codes lived in reason_codes even when allowed=true, which caused integration confusion (e.g. BLOCKED_ACTION_PRESENT alongside allowed=true). The split was introduced in alpha.5. Old clients reading reason_codes for blocking checks continue to work — they just see fewer codes.

Cache layers

When per-asset cache misses, the endpoint warms in parallel (Promise.allSettled over the missing assets, 12s timeout each). If both miss simultaneously and warming fails, the response is 503 with Retry-After: 30 and a cache_status block per asset for diagnosis.

Error responses

Full reference

The complete spec — 12 worked scenarios, full per-position field reference, error code reference, smoke-test bash script, and operational notes — is in specs/api/portfolio-risk-state-examples.md. That document is the source-of-truth for v2 alpha; this page summarises the surface for landing-page readers.

POST /v2/stress-scenario

Apply a deterministic shock template to the same book and return baseline vs stressed side-by-side. Companion to /v2/portfolio-risk-state.

POST https://riskstate.netlify.app/v2/stress-scenario

Request

Same positions[] and stablecoin_holdings_usd as the portfolio endpoint, plus a scenario field:

{
  "positions": [
    { "asset": "BTC", "size_usd": 750000, "side": "long" },
    { "asset": "ETH", "size_usd": 250000, "side": "long" }
  ],
  "scenario": "flash_crash"
}

Built-in templates

Response shape

Three contract details that have surprised first-time integrators

1. stressed_size_usd on hedged shorts is post-pnl, not underlying notional

A $500k short under a −30% flash-crash reports stressed_size_usd ≈ $650k (gained $150k on the short), not $500k (the unchanged underlying notional). This is so that aggregating across an asymmetric long/short book yields a clean post-shock book value.

If you need the underlying instead (e.g. for margin-requirement math):

const stressedUnderlying = Math.abs(p.stressed_size_usd - p.pnl_usd);

This is a modeling choice, not a bug. A stressed_underlying_notional_usd field is a candidate for a future minor.

2. baseline.portfolio_allowed covers BOTH crypto concentration AND stablecoin DANGER

Pre-alpha.2 it only covered concentration, so a portfolio with a healthy crypto book + 100% USDT could pass baseline despite a structural stable issue. Alpha.2 onward, baseline checks both flag families. A book with 100% USDT can return baseline.portfolio_allowed: false before any scenario shock — that's the correct read.

3. triggered_flags is a baseline-aware diff, applied to both flag families

A flag that fires under stress AND would have fired at baseline is NOT considered "triggered by the scenario." Pre-alpha.2 stablecoin flags were always reported as triggered; alpha.2 onward both concentration and stablecoin flags use the same diff logic. So a USDC-heavy book under stablecoin_depeg reports only STABLE_DEPEG_USDC as triggered (the concentration flag was already true at baseline).

Custom override (scenario_params)

{
  "positions": [{"asset":"BTC","size_usd":50000,"side":"long"}],
  "stablecoin_holdings_usd": { "USDT": 800000 },
  "scenario": "stablecoin_depeg",
  "scenario_params": {
    "stablecoin_peg_shift_pct": { "USDT": -5 },
    "vol_multiplier": 1.0
  }
}

scenario_params deep-merges into the base template. Only the keys you supply override; everything else stays as the template default. response.scenario.custom_override_applied: true confirms the merge.

Determinism

The shocks are pre-specified constants in the function source. There are no upstream API calls during scenario execution — the only inputs are the request body. Two identical requests always produce identical responses (modulo auditability.computed_at).

Full reference

The complete spec — 5 worked scenarios including the hedged-short post-pnl example, full field reference, custom-override deep-merge semantics, and smoke-test script — is in specs/api/stress-scenario-examples.md.

Forward-compatibility commitments

Will NOT break existing integrations:

• Adding new optional fields to request body (ignore if unknown)
• Adding new fields to response body (ignore if not consumed)
• Adding new stablecoin issuers / scenario templates
• Bumping api_version minor / patch

Will be announced as breaking with 2-week notice:

• Renaming or removing any documented response field
• Changing the type of any documented field
• Tightening validation that currently accepts certain inputs
• Changing the semantics of portfolio_allowed (e.g. adding a new mandatory blocker class)
• Renaming any of the 6 built-in scenario keys
• Changing the deep-merge semantics of scenario_params

Internal, not part of the contract:

• Cache TTL adjustments
• Concentration / depeg threshold tuning (will be parametric per-key in future via policy_config)
• Adding cache layers
• Changing internal cache key shapes

Versioning

Pre-stable. Stabilises to 2.0.0 jointly when:

1. At least one institutional pilot has consumed both endpoints for ≥30 days
2. Forward-compatibility commitments are explicitly published
3. Pricing tier integration ships (free vs paid access policy)

Until 2.0.0, breaking changes may occur with 2-week notice published in the Changelog.

Looking for v1?

POST /v1/risk-state is the production-stable per-asset endpoint. Use it when you only care about a single asset and want the lowest-latency, most-tested surface. See API v1 Reference →.