API Documentation

One endpoint. Send a behavioral event. Receive a complete mathematical proof in under 30ms. This page covers everything you need to go from API key to first successful call.

Quick Start

Send your first event in under 5 minutes. You need your API key from the welcome email and one JSON payload.

CURL

# Your first API call. Returns a full proof in <30ms
curl -X POST https://api.significantrust.com/v1/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "login",
    "user_id": "usr_4471",
    "session_id": "ses_8f2a91bc",
    "timestamp": 1741872000,
    "ip": "203.0.113.42",
    "device_fingerprint": "d8f3a9c1b2e4"
  }'

You'll receive a response in under 30ms containing a decision, certainty score, pattern match, sequence probability, and a complete audit trail — all in a single call.

Your API key was sent to the email address you used to sign up. If you haven't received it, check spam or contact us. Don't have a key yet? Run it on my traffic free →

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is available in your dashboard after signing up.

HTTP HEADER

Authorization: Bearer st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Never expose your API key client-side. All calls should be made server-to-server. Treat your API key like a password.

Base URL

All API requests are made to the following base URL. The API is available globally with sub-30ms response times.

Base URL https://api.significantrust.com

POST /v1/score

The core endpoint. Accepts a behavioral event and returns a complete mathematical decision with proof chain. This is the only endpoint you need.

POST https://api.significantrust.com/v1/score

Request Schema

Send a JSON payload with the following fields. Required fields are marked required.

Field	Type	Required	Description
`event_type`	string	required	Type of event being scored. See Event Types.
`user_id`	string	required	Your internal identifier for the user. Used to build the behavioral profile.
`session_id`	string	required	Unique identifier for the current session.
`timestamp`	integer	required	Unix timestamp (seconds) of the event.
`ip`	string	required	IPv4 or IPv6 address of the request origin.
`device_fingerprint`	string	required	Device fingerprint hash. Use our SDK or your own fingerprinting solution.
`amount`	float	optional	Transaction amount in USD. Required for `transaction` event types.
`merchant_id`	string	optional	Merchant identifier. Used for payment fraud pattern analysis.
`behavioral_sequence`	array	optional	Array of prior behavioral events for richer VLS-Markov analysis. Increases accuracy.
`metadata`	object	optional	Any additional key-value pairs relevant to the event. Stored in the audit trail.

REQUEST · JSON

{
  "event_type": "login",
  "user_id": "usr_4471",
  "session_id": "ses_8f2a91bc",
  "timestamp": 1741872000,
  "ip": "203.0.113.42",
  "device_fingerprint": "d8f3a9c1b2e4",
  "behavioral_sequence": [
    { "event": "page_view", "ts": 1741871940 },
    { "event": "form_focus", "ts": 1741871955 },
    { "event": "keystroke", "ts": 1741871958 }
  ],
  "metadata": {
    "user_agent": "Mozilla/5.0...",
    "country": "GB"
  }
}

Response Fields

Every successful response returns HTTP 200 with a complete proof. All fields are always present.

RESPONSE · JSON

{
  "decision": "BLOCK",           // BLOCK | REVIEW | APPROVE
  "certainty_score": 99.97,      // 0–100. Mathematical certainty.
  "pattern_match": "account_takeover",
  "sequence_probability": "p < 0.0003",
  "false_positive_risk": "<8%",

  "proof_chain": {
    "events_analyzed": 847,
    "deviation_point": 312,
    "deviation_type": "typing_cadence_mismatch",
    "norm_baseline": 0.9941,
    "observed_probability": 0.0003,
    "threshold_crossed": true
  },

  "audit_trail": "generated",
  "regulator_ready": true,
  "request_id": "req_9x2k1m8n",
  "response_ms": 28
}

decision

string

The Certainty Engine's verdict. BLOCK: mathematically impossible sequence for this user. REVIEW: borderline deviation, step-up authentication recommended. APPROVE: sequence consistent with user profile.

certainty_score

float

Mathematical certainty of the decision, 0–100. Not a probability score. A calculated confidence derived from the VLS-Markov model.

pattern_match

string

The closest fraud pattern signature matched. Used for analytics and audit documentation.

sequence_probability

string

The probability that the observed behavioral sequence belongs to the registered user profile. Lower values indicate higher fraud confidence.

proof_chain

object

The complete mathematical proof. Contains the number of events analyzed, the exact deviation point, deviation type, statistical baseline, and observed probability. This is what you hand to a regulator.

audit_trail

string

Confirmation that the full audit trail has been generated and stored. Retrieve via request_id.

regulator_ready

boolean

Always true. Every decision is documented, traceable, and defensible.

response_ms

integer

Actual response time in milliseconds. Typically 20–30ms.

Event Types

Pass one of the following values in the event_type field. Each type activates the relevant behavioral pattern analysis.

Value	Description
`login`	User authentication attempt. Analyzes typing cadence, device, IP, and session behavior.
`transaction`	Payment or transfer event. Requires `amount` field. Analyzes velocity, merchant patterns, and behavioral consistency.
`account_creation`	New account registration. Detects synthetic identities and device reputation signals.
`password_reset`	Credential change event. High-risk sequence. Analyzed for ATO patterns.
`withdrawal`	Fund withdrawal or transfer initiation. Analyzed for exit fraud and fund exfiltration patterns.
`bonus_claim`	Promotional offer redemption. Analyzes for multi-accounting, ring detection, and coordinated abuse.
`kyc_submission`	Identity document submission. Detects fabricated profiles and document inconsistencies.
`session_activity`	General behavioral event during an active session. Use for continuous monitoring.

Code Examples

Production-ready examples in every supported language.

PYTHON

import requests

API_KEY = "st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.significantrust.com"

def score_event(event_data):
    response = requests.post(
        f"{BASE_URL}/v1/score",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json=event_data
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = score_event({
    "event_type": "login",
    "user_id": "usr_4471",
    "session_id": "ses_8f2a91bc",
    "timestamp": 1741872000,
    "ip": "203.0.113.42",
    "device_fingerprint": "d8f3a9c1b2e4"
})

print(result["decision"])         # BLOCK
print(result["certainty_score"])   # 99.97

NODE.JS

const API_KEY = 'st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
const BASE_URL = 'https://api.significantrust.com';

async function scoreEvent(eventData) {
  const response = await fetch(`${BASE_URL}/v1/score`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(eventData)
  });

  if (!response.ok) throw new Error(`API error: ${response.status}`);
  return response.json();
}

// Example usage
const result = await scoreEvent({
  event_type: 'login',
  user_id: 'usr_4471',
  session_id: 'ses_8f2a91bc',
  timestamp: 1741872000,
  ip: '203.0.113.42',
  device_fingerprint: 'd8f3a9c1b2e4'
});

console.log(result.decision);        // BLOCK
console.log(result.certainty_score); // 99.97

JAVA

import java.net.http.*;
import java.net.URI;

public class SignificanTrustClient {
    private static final String API_KEY = "st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    private static final String BASE_URL = "https://api.significantrust.com";

    public String scoreEvent(String jsonPayload) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/v1/score"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString()
        );
        return response.body();
    }
}

PHP

<?php

$apiKey = 'st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
$baseUrl = 'https://api.significantrust.com';

function scoreEvent($eventData) {
    global $apiKey, $baseUrl;

    $ch = curl_init($baseUrl . '/v1/score');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($eventData),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json'
        ],
        CURLOPT_RETURNTRANSFER => true
    ]);

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

$result = scoreEvent([
    'event_type' => 'login',
    'user_id'    => 'usr_4471',
    'session_id' => 'ses_8f2a91bc',
    'timestamp'  => 1741872000,
    'ip'         => '203.0.113.42',
    'device_fingerprint' => 'd8f3a9c1b2e4'
]);

echo $result['decision']; // BLOCK

GO

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

const (
    APIKey  = "st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    BaseURL = "https://api.significantrust.com"
)

func ScoreEvent(eventData map[string]interface{}) (map[string]interface{}, error) {
    payload, _ := json.Marshal(eventData)
    req, _ := http.NewRequest("POST", BaseURL+"/v1/score", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer "+APIKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil { return nil, err }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

Error Codes

Non-200 responses include an error object with a code and message field.

400

Bad Request. Missing required field or invalid value. Check the message field for details.

401

Unauthorized. Missing or invalid API key. Check your Authorization header.

403

Forbidden. API key valid but insufficient permissions for this operation.

422

Unprocessable Entity. Request format is valid but contains semantic errors. Check field values.

429

Rate Limited. You have exceeded your request quota. See Rate Limits.

500

Internal Error. Unexpected server error. Retry with exponential backoff. If persistent, contact support.

503

Service Unavailable. Temporary. Retry after a short delay. Our SLA is 99.99% uptime.

Rate Limits

Rate limits are applied per API key. The Certainty Engine is designed for high-throughput. 10,000+ requests per second on paid plans.

Plan	Requests / second	Monthly events
Free Trial	10 RPS	1,000
Starter	100 RPS	10K – 100K
Growth	500 RPS	100K – 300K
Scale	2,000 RPS	300K – 600K
Enterprise	10,000+ RPS	Custom

When rate limited, you'll receive a 429 response with a Retry-After header indicating when to retry.

SDKs

Official SDKs are available for all major languages. Each SDK handles authentication, retries, and error handling automatically.

Language	Install
Python	`pip install significantrust`
Node.js	`npm install @significantrust/sdk`
Java	`implementation 'com.significantrust:sdk:1.0.0'`
PHP	`composer require significantrust/sdk`
Go	`go get github.com/significantrust/sdk-go`

SDKs are optional. The REST API accepts plain JSON. You can integrate without any SDK in under an hour. The examples above are all you need.