Institutional Integration Guide

Pre-vendor due diligence brief. Read this if you are a procurement officer, risk lead, or technology lead at a fund, desk or treasury team evaluating RiskState.

This document is the canonical reference for how RiskState is built, operated, and integrated. It cites the technical docs that describe each capability and is written to be skimmed top-to-bottom by procurement and integrated by reference into vendor questionnaires.

Status as of 2026-04-28. v1.3.0 of the API, score_v3 of the engine, public free beta. The 6-month scoring freeze is part of how we keep the track record auditable. SOC 2, RBAC scopes and multi-region failover land after the freeze (Q4 2026 onward); we are explicit about what is shipped today versus on the roadmap.

Contents

• Audience
• Product status (today)
• What RiskState is — and is not
• Architecture overview
• Data classification
• Authentication and key management
• Audit trail
• Policy customization to mandate
• Retention and deletion
• Incident response and vulnerability disclosure
• Operational posture
• Shadow-mode pilot model
• Beta vs production-pilot
• Roadmap framed by risk committee axis
• Institutional Hardening Modes
• SIG Lite mapping
• Contact

Audience

Two readers:

• Procurement / risk lead running pre-vendor due diligence. Wants short, direct answers to compliance questions. Use the SIG Lite mapping and Audit trail sections.
• Technology / quant lead scoping integration. Wants the architecture, the data flow, and the integration handles. Use Architecture overview, Authentication and Shadow-mode pilot model.

Product status (today)

What RiskState is — and is not

If your evaluation is "does it predict the next move", RiskState is the wrong product. If your evaluation is "does it bind exposure to mandate before execution, with an audit trail we can defend in committee", that is what it is built for.

Architecture overview

        ┌─────────────────────────────────────────────────────────┐
        │  Customer system (agent / desk / OMS)                   │
        └──────────────────────────┬──────────────────────────────┘
                                   │
                       Bearer auth │  POST /v1/risk-state
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │  RiskState (Netlify Functions, single region US-East)   │
        │                                                         │
        │   1. Auth (env-var owner key + Blobs external keys)     │
        │   2. Pre-flight policy_config (block protocols, etc.)   │
        │   3. 60s shared cache (asset, protocol)                 │
        │   4. Multi-source fetch (CoinGecko / Binance / OKX /    │
        │      Bybit / CryptoCompare / FRED / DefiLlama / ...)    │
        │   5. Scoring pipeline (composite + structural +         │
        │      tactical + policy combiner)                        │
        │   6. Policy engine (4 caps × quality × volatility)      │
        │   7. Per-call policy_config tightening                  │
        │   8. Sync audit write (full record to Blobs)            │
        │                                                         │
        └──────────────────────────┬──────────────────────────────┘
                                   ▼
                          JSON response with policy_hash

A request takes ~5–12 seconds (mostly upstream data fetch latency); cached responses ~50–200 ms. There is no customer state retained between requests other than the audit record and the policy_config attached to the customer's API key.

Data sources are public-internet APIs. Failover and fallback chains are documented per source in API Reference → Data sources. When the primary fails, secondary providers are tried automatically; the resulting response carries a data_sources block tagging which provider supplied each field at decision time.

Data classification

What is deliberately not collected:

• Trading P&L or position sizes (we never see your trade book).
• Counterparty / exchange identifiers beyond what is required by the API call.
• Browser fingerprints, IP-based tracking, third-party analytics on API endpoints.

Authentication and key management

Bearer token over HTTPS. Two tiers:

1. Owner key (RiskState's master, env-var only). Cannot be created by external actors. Used for admin operations.
2. External keys (rs_live_*, 256-bit entropy). Generated via POST /api/api-keys (currently owner-only; self-service waitlist signup queues a key delivery to the email).

Rate limit. 60 requests/minute per external key. Sliding minute window. Exceeding returns HTTP 429 with a retry_after_seconds body field.

Revocation. POST /api/api-keys with action: "revoke" flips the key inactive. Propagation is typically sub-second; a known eventual-consistency window of up to ~1 second can pass before subsequent requests with the revoked key are rejected. For institutional pilots requiring instant cutoff, we recommend a complementary client-side revocation list. A formal cache-invalidation layer is on the post-freeze hardening list.

Storage. Keys live in the api-keys Blobs store. Each entry holds: email, created, active, revoked, last_used, request_count, optional policy_config. The full token is only revealed once at creation and emailed via Resend (DKIM-signed, api@riskstate.ai).

Scopes. Single-scope today (read access to /v1/risk-state plus owner-only admin paths). RBAC scopes (risk:read, audit:read, portfolio:write) ship in B5 of the institutional roadmap.

Audit trail

Every authenticated /v1/risk-state call writes a synchronous audit record before responding. The record includes policy_hash, scoring_version, data_sources snapshot, binding_constraint (with reason_codes), full request echo (without sensitive values), response_summary, policy_config_applied, policy_config_snapshot, cache_hit, and latency_ms.

The full schema, retrieval endpoint (GET /v2/audit/decisions), pagination model, and SIG Lite mapping live at:

→ Audit Log →

For procurement: this is the system of record for "show me every decision your engine made that we acted on". 365 days online; long-term cold-storage retention is a per-customer setting in the institutional pricing tier (post-freeze).

Policy customization to mandate

Each external API key can be attached to a policy_config profile that further tightens the engine's caps to the customer's mandate. Tighten only — never loosens.

Configurable today:

The full enforcement model, response shape, validation rules, and worked examples live at:

→ Policy Config →

For pilot, RiskState configures the profile with you during onboarding. Customer-side self-service writes are post-pilot (v2 of policy-config).

Retention and deletion

Right-to-be-forgotten requests: send to hello@likido.xyz with the API key prefix (16-char public part); we confirm in writing within 5 business days.

Incident response and vulnerability disclosure

→ /security (canonical reference; see also /.well-known/security.txt when published)

Disclosure model. Coordinated disclosure. We acknowledge within 72 hours and commit to a public advisory or status update within 30 days for any confirmed vulnerability that affected production.

Scope.

• In scope: riskstate.ai, riskstate.netlify.app, the published API endpoints (/v1/*, /v2/*).
• Out of scope: third-party services (CoinGlass, Binance, etc.) — report to them directly.

Hard NO. Active exploitation against live customer keys, social engineering of any RiskState contact, or denial-of-service testing without written authorization. Report; don't exploit.

Operational posture

We do not contract uptime SLAs in beta. Expected availability based on the last 60 days has tracked > 99.5%; this is a measured metric, not a guaranteed one. Production-pilot SLA is part of the Q4 paid pilot scope.

Performance:

Latency is bound primarily by upstream data-fetch waves; the engine itself is sub-second. The 60-second response cache sits between most callers and the upstream fan-out.

Shadow-mode pilot model

The default pilot template:

Shadow mode is a low-ops integration: no real-time hooks, no order-flow access, no execution layer integration. We see your portfolio shape end-of-day; you see our policy assessments + audit trail.

Pilot is non-binding, exit at any time, no payment during shadow. The fund decides at M6 whether to convert to paid pre-production pilot for Q4 2026.

Detailed pilot scope template is shared under NDA. Contact below.

Beta vs production-pilot

What is shipped today versus what production-pilot adds. This is a hard line — the items in the right column are not in beta.

Roadmap framed by risk committee axis

Rather than a feature list, here is what changes along each axis your risk committee will care about:

Time anchor. score_v4 (calibrated with pilot data) ships at 2026-10-22 when the freeze lifts. Portfolio API v2 (POST /v2/portfolio-risk-state), SOL asset mode (experimental flag), stress scenario export, RBAC and webhooks are scoped for the same window. SOC 2 Type I and multi-region failover are post-pilot, with capital and team in place.

What is explicitly not on the roadmap:

• Replacing your VaR / Monte Carlo engine.
• Running our own execution venue.
• Predicting market direction with confidence claims.
• ISO 27001 in the freeze window.

If procurement requires a deliverable that does not appear above, raise it; if it is in scope we will commit a milestone, if not we will say so plainly.

Institutional Hardening Modes

For pilot customers whose mandate requires it, the following toggles are documented as optional production-pilot modes. They are not active in beta. We surface them upfront because procurement will ask, and because they convert today's limitations into selectable maturity tiers rather than blockers.

Pilots that need any of these can request them in the pilot scope memo. Beta defaults are explicit so your risk committee can document the gap before production.

SIG Lite mapping

The full mapping table for each SIG Lite area is in the audit log doc. High-level coverage:

For procurement teams: this table reflects today's reality, not aspiration. The "Partial" and "❌" rows are the real gaps an institutional pilot would weigh against the value RiskState brings.

Contact

• General / contracting / pilot scoping: hello@likido.xyz
• Security reports: security@likido.xyz (see /security)

For pilot conversations: include the fund / desk name, mandate summary (3 lines), the assets and markets you trade, and the procurement timeline. We respond within 2 business days.