Technical integration overview

Architecture

Where it sits in a checkout

One verdict call per checkout session, made by your server at the moment the user confirms. Only sessions that come back INTERVENE go further, into a four-question probe that runs from the browser.

Integration

Two ways to integrate

Both paths use the same server-side verdict call. They differ only in who renders the screens.

With the SDK (recommended)

straja.js collects the three browser-side signals and renders the SOFT, probe, pattern and hold screens as an overlay in a shadow root, so your page styles never leak in or out. It needs only the verdict's per-decision client_secret, never a secret key.

<script src="https://api.straja.lumosstudio.ro/sdk/v1/straja.js"></script>
<script>
  // As early as possible on the checkout page
  const straja = Straja.collect({ addressInput: "#destination-address" });

  async function onConfirm(order) {
    // Your server calls POST /v1/verdict and returns its JSON unchanged
    const verdict = await fetch("/checkout/straja-verdict", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ orderId: order.id, behavior: straja.signals() }),
    }).then((r) => r.json());

    const result = await Straja.present(verdict, {
      transfer: "€4,800 in BTC",            // used in the hold screen's copy
      theme: { accent: "#0F62FE", fontFamily: "Inter, sans-serif" },
    });
    // result.action: "proceed" | "cancel" | "hold" | "error"
  }
</script>

const res = await fetch("https://api.straja.lumosstudio.ro/v1/verdict", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STRAJA_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: order.id,                     // your own id, returned in the record
    signals: { ...behavior, ...accountSignals(order) },
  }),
  signal: AbortSignal.timeout(20_000),       // see Latency & failures
});

Preview both halves of the SDK at api.straja.lumosstudio.ro/sdk/v1/playground.html: it shows the collected signals live, and renders the screens for any test-mode verdict you paste into it.

SDK reference

present options: transfer (text for the hold screen, e.g. "€4,800 in BTC"), apiBase (defaults to the SDK's own origin), and theme with any of accent, accentText, accentSoft, background, text, muted, surface, border, radius, fontFamily (CSS values), and copy to replace any on-screen text, e.g. to translate the screens: softTitle, softBody, softContinue, softBack, probeTitle, answerLabel, decline, send, readingBack, retry, close, continueLabel, holdTitle, holdBody, holdCancel, holdConfirm, transferFallback ({hours} and {transfer} are filled in). Probe questions and the pattern screen come from the API in English. Screens render in a shadow root and meet keyboard and screen-reader basics: focus moves into the dialog and returns afterwards.

With your own UI

1. Measure three browser-side signals — gaps of over 60 seconds with no interaction, tab or window switches, and whether the destination address was pasted, typed or scanned — or use Straja.collect() for just this part.
2. Call POST /v1/verdict from your server when the user confirms amount and destination.
3. Branch on tier. PASS: continue. SOFT: show one acknowledgment screen, then continue. INTERVENE: start the probe.
4. Run the probe: call POST /v1/probe once per question, passing the transcript so far, until four questions are answered. These calls can come from the browser with the verdict's client_secret.
5. Call POST /v1/pattern with the four answers and render the returned screen, then a hold of action.delay_hours with a cancel option.
6. Report what the user did with POST /v1/outcome.

Authentication

Keys and client secrets

Every request except GET /v1 carries a credential in the Authorization header: Authorization: Bearer <credential>.

Keys are issued by Straja per integration and can be rotated or revoked at any time; revoking a key also invalidates the client secrets issued under it. Only a SHA-256 hash of each key is stored. A secret key must never appear in a browser or mobile app.

Data contract

The signal vector

All fifteen fields are required. Two accept null where the value does not exist; a request missing any field is rejected with 400 naming it. Every value is computed by your systems or the SDK — none is inferred by the model.

API reference

Endpoints

Every authenticated response carries a Straja-Request-Id header. Quote it when reporting a problem.

{
  "reference": "order_8f2c41",
  "shadow": false,
  "signals": {
    "idle_gaps_over_60s": 4,
    "tab_switches": 3,
    "address_entry_method": "pasted",
    "account_age_days": 412,
    "is_first_purchase": false,
    "amount_eur": 4800,
    "amount_vs_median": 9.6,
    "funding_method": "card",
    "minutes_to_outbound": 3,
    "destination_first_seen_days": 2,
    "destination_type": "fresh_eoa",
    "declined_attempts": 0,
    "deposit_escalation": [200, 1000, 4800],
    "kyc_retries": 0,
    "merchant_verified": null
  }
}

{
  "object": "verdict",
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "livemode": true,
  "shadow": false,
  "reference": "order_8f2c41",
  "tier": "INTERVENE",
  "probe_required": true,
  "key_signals": [
    "idle_gaps + pasted address"
  ],
  "reasoning": "Coached-session pattern: …",
  "client_secret": "cs_1790…",
  "latency_ms": 6120,
  "created_at": "2026-09-29T10:41:22.104Z"
}

{
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "transcript": [
    {
      "question": "How did you first hear about this opportunity?",
      "answer": "Someone from the exchange called me."
    }
  ]
}

{
  "object": "probe_turn",
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "question_number": 2,
  "question": "Where did you get the wallet address you're sending to?",
  "is_final": false
}

{
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "transcript": [ /* all four turns */ ]
}

{
  "object": "pattern",
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "headline": "…",
  "observations": [
    { "signal": "…", "user_quote": "…" }
  ],
  "the_pattern": "…",
  "one_thing_to_check": "…",
  "action": { "delay_hours": 24, "cancellable": true }
}

{
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "outcome": "cancelled"
}

{
  "object": "outcome",
  "decision_id": "dec_9b1f0c7e2a4d5b6c8e0f1a2b",
  "outcome": "cancelled",
  "outcome_reported_at": "2026-09-29T10:44:03.511Z"
}

Errors

One error shape

{
  "error": {
    "type": "invalid_request_error",
    "message": "signals.tab_switches: Invalid input: expected number, received undefined",
    "param": "signals.tab_switches",
    "request_id": "req_3f9a0c1d2b4e6f70"
  }
}

Rate limits are per key and per minute: 300 for live keys and 60 for test keys by default, adjustable per integration.

Latency & failures

Plan for seconds, not milliseconds

Every live verdict is a model call. Measured over 525 recorded verdicts:

• Call the verdict as the user confirms and show a "reviewing" state rather than blocking silently.
• Set a 20-second client timeout. 99.4% of recorded verdicts finished inside it.
• Decide your fallback before go-live. On timeout or a 5xx, the recommended policy is to proceed as you would without Straja and keep the order reference for review, since Straja is an additional layer rather than your only control. Stricter policies (hold on failure) are equally supported.
• Probe and pattern calls come from the browser after the user is already in the flow. Question 1 returns immediately; questions 2–4 and the pattern screen are model calls of similar duration to a verdict.

Shadow readout

Measure accuracy against your own outcomes

Once you know how a session really ended — a chargeback, a scam report, an investigation — report it. Label by your reference or by decision_id, up to 1,000 per call; a label can be sent again to correct it.

{
  "labels": [
    { "reference": "order_8f2c41", "fraud": true },
    { "reference": "order_91aa07", "fraud": false },
    { "decision_id": "dec_9b1f…", "fraud": false }
  ]
}

{
  "object": "label_result",
  "received": 3,
  "decisions_updated": 3,
  "unmatched": []
}

GET /v1/readout then reports, for any window: how sessions split across tiers, how many labeled fraud sessions were intervened on or soft-flagged (recall), and how many legitimate sessions were (false-positive rate). Parameters: created_after, created_before (ISO 8601), shadow=true|false, and unlabeled=exclude|legitimate — use legitimate when you only label confirmed fraud, so every other session counts as clean.

{
  "object": "readout",
  "sessions": { "total": 41200, "pass": 40310, "soft": 512, "intervene": 378, "intervene_rate": 0.0092 },
  "labels": { "fraud": 64, "legitimate": 0, "unlabeled": 41136 },
  "fraud_detection": {
    "fraud_sessions": 64, "intervened": 51, "soft_flagged": 7, "passed": 6,
    "intervene_recall": 0.7969, "any_flag_recall": 0.9063
  },
  "false_positives": {
    "legitimate_sessions": 41136, "intervened": 327, "soft_flagged": 505,
    "intervene_rate": 0.0079, "soft_rate": 0.0123
  },
  "latency_ms": { "mean": 6010, "p95": 11200 }
}

Illustrative numbers. Rates are null when their denominator is zero.

Test mode

Build the whole integration for free

Requests with an sk_test_ key never reach the model. Verdicts follow a fixed rule: one point each for idle gaps ≥ 2, tab switches ≥ 2, a pasted address, a fresh_eoa destination first seen ≤ 7 days ago, and a last deposit ≥ 3× the first. Three or more points gives INTERVENE, two gives SOFT, fewer gives PASS.

To force a tier, send the header Straja-Test-Tier: PASS, SOFT or INTERVENE. Probe questions are the four fixed topics, and the pattern screen is fixed copy that quotes the test answers. Responses carry "livemode": false. Test records are stored and listed separately from live ones.

Compliance

Every verdict is an audit record

One record per decision, stored when the verdict is returned and appended to as the probe, pattern and outcome happen. Retrieve it with GET /v1/decisions/{id} or list by reference.

Configurability

Threshold profiles

A deterministic step applied after the model, set per partner with PATCH /v1/settings.

Data handling

What is sent, where it goes

• No direct identifiers are required. The signal vector contains no name, email, account id, card or wallet address — only counts, amounts and classifications. reference should be an opaque id, not personal data.
• Probe answers are free text typed by the user and may contain personal information. They are stored in the decision record and sent to the model.
• Model processing: verdicts, probe questions and pattern screens are generated by Anthropic's Claude models (Anthropic acts as a subprocessor). Only the signal vector and, on INTERVENE, the transcript are sent — never your reference or key.
• Storage: decision records, key hashes and settings are stored in Postgres (Neon) in the EU, AWS eu-central-1 (Frankfurt), encrypted at rest. The API itself runs in Frankfurt. All traffic is over TLS.
• Retention: records are kept until deleted with DELETE /v1/decisions/{id}, or automatically once older than the retention_days you set.

Model

Model & reliability

Verdicts use Claude Opus 5, chosen because the hard cases — two sessions near-identical on paper, differing only in behavior — need reasoning depth. Under sustained overload, calls fail over automatically to Claude Sonnet 5, a separate capacity pool. Every model response is validated against a fixed schema; a malformed response is rejected, not passed on.

Getting started

Integration timeline

Integration runs in shadow mode before any user sees a Straja screen, so verdict accuracy is measured against your own outcomes first.

First call

With a test key, this returns a verdict immediately and costs nothing. Remove the Straja-Test-Tier header to see the test rules score the vector instead.

curl https://api.straja.lumosstudio.ro/v1/verdict \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Straja-Test-Tier: INTERVENE" \
  -d '{
    "reference": "first-test",
    "signals": {
      "idle_gaps_over_60s": 4, "tab_switches": 3, "address_entry_method": "pasted",
      "account_age_days": 412, "is_first_purchase": false, "amount_eur": 4800,
      "amount_vs_median": 9.6, "funding_method": "card", "minutes_to_outbound": 3,
      "destination_first_seen_days": 2, "destination_type": "fresh_eoa",
      "declined_attempts": 0, "deposit_escalation": [200, 1000, 4800],
      "kyc_retries": 0, "merchant_verified": null
    }
  }'

Paste the response into the SDK playground to walk through the probe as a user would.