docs/API_CONTRACT.md

RazorShield API Contract & Integration Reference

This document defines the official Gradio API contract exposed by the Hugging Face Space backend (vedantjadhav701/razorshield-api) for integration with the Vercel Next.js frontend.

---

1. Overview

The backend exposes 5 logical API operations via Gradio HTTP / Client routes:

Operation	Gradio api_name	Primary Function
analyze_transaction	"analyze_transaction"	Real-time transaction fraud & merchant incident risk analysis
analyze_merchant	"analyze_merchant"	Query live merchant temporal rolling state & active campaign info
run_scenario	"run_scenario"	Chronologically replay test scenarios for interactive demo
explain_evidence	"explain_evidence"	Direct structured evidence to zero-shot SLM explanation conversion
reset_demo_state	"reset_demo_state"	Reset all merchant temporal state, incident counters, & campaigns

---

2. API Endpoint Specification

Endpoint 1: analyze_transaction

Evaluates transaction fraud probability, merchant rolling temporal state, deployable spike model, persistent incident detection, and outputs grounded SLM explanations for elevated risk levels.

Request Inputs (Ordered Arguments for Gradio Client)

Argument Index	Parameter	Type	Required	Default	Description
0	merchant_id	str	Yes	"M_101"	Unique merchant identifier
1	transaction_id	str	Yes	"TX_994182"	Unique transaction identifier
2	customer_id	str	No	"C_1048"	Customer identifier
3	device_id	str	No	"D_882"	Device identifier
4	event_time	str	Yes	ISO timestamp	Timestamp (e.g. "2026-08-22T01:30:00")
5	amount	float	Yes	125.50	Transaction amount in USD
6	payment_method	str	No	"card"	"card", "ach", "crypto", "paypal"
7	transaction_type	str	No	"sale"	"sale", "transfer", "refund"
8	policy_mode	str	No	"BALANCED"	"CONSERVATIVE", "BALANCED", "HIGH_SENSITIVITY"

Response Schema (AnalyzeTransactionResponse)

{
  "transaction_id": "TX_994182",
  "merchant_id": "M_101",
  "transaction_risk": {
    "fraud_probability": 0.8124
  },
  "merchant_risk": {
    "spike_probability": 0.8841,
    "fraud_excess_ratio": 8.24,
    "velocity_ratio": 4.10,
    "incident_state": "ALERT",
    "severity": "HIGH",
    "incident_score": 0.8483,
    "suspicious_windows": 3
  },
  "campaign": {
    "active": true,
    "campaign_name": "PROMOTIONAL_SALE"
  },
  "decision": {
    "action": "ALERT",
    "policy_mode": "BALANCED"
  },
  "explanation": {
    "title": "RazorShield Defensive Risk Assessment: ALERT (HIGH Severity)",
    "summary": "RazorShield classified merchant M_101 activity as ALERT (HIGH severity) because a fraud anomaly persisted across 3 consecutive monitoring windows. Estimated fraud excess ratio is 8.2x baseline with volume velocity 4.1x baseline.",
    "key_signals": [
      "Policy Incident Score: 0.85",
      "Fraud Excess Ratio: 8.2x baseline",
      "Volume Velocity Ratio: 4.1x baseline",
      "Consecutive Suspicious Windows: 3"
    ],
    "campaign_context": "A promotional campaign is currently active for merchant M_101. Volume velocity (4.1x baseline) is normalized, but fraud excess (8.2x baseline) remains actionable.",
    "recommended_action": "Initiate immediate merchant review, enforce step-up authentication, and review high-risk transaction batches.",
    "confidence_note": "Decision (ALERT) is authoritatively determined by RazorShield policy engine."
  },
  "performance": {
    "risk_engine_latency_ms": 0.619,
    "slm_latency_ms": 472.03,
    "total_latency_ms": 472.65
  }
}

---

Endpoint 2: analyze_merchant

Request Input: merchant_id (str)

Response:

{
  "merchant_id": "M_101",
  "rolling_window": {
    "rolling_txn_count_15m": 45,
    "baseline_txn_count_15m": 10,
    "velocity_ratio": 4.5,
    "estimated_fraud_count": 0.85,
    "expected_fraud_count": 0.10,
    "fraud_excess_ratio": 8.5
  },
  "incident_state": {
    "merchant_id": "M_101",
    "current_spike_probability": 0.88,
    "current_fraud_excess_ratio": 8.5,
    "current_velocity_ratio": 4.5,
    "suspicious_transaction_count": 3,
    "consecutive_suspicious_windows": 3,
    "campaign_active": true
  }
}

---

Endpoint 3: run_scenario

Request Inputs: scenario_name (str), policy_mode (str)

• Options: "NORMAL", "VOLUME_ONLY_SPIKE", "AMOUNT_SHIFT", "FRAUD_SPIKE", "FRAUD_DURING_FLASH_SALE"

---

Endpoint 4: explain_evidence

Request Input: evidence_json (str)

Converts raw evidence JSON into grounded SLM output with validation report.

---

Endpoint 5: reset_demo_state

Request Input: None

Response:

{
  "status": "SUCCESS",
  "message": "All merchant states and campaigns reset."
}

---

3. Vercel / Client Integration Code Snippet (JS / TS)

import { client } from "@gradio/client";

const spaceUrl = "vedantjadhav701/razorshield-api";

export async function analyzeTransaction(payload: any) {
  const app = await client(spaceUrl);
  const result = await app.predict("analyze_transaction", [
    payload.merchant_id,
    payload.transaction_id,
    payload.customer_id || "C_UNKNOWN",
    payload.device_id || "D_UNKNOWN",
    payload.event_time,
    payload.amount,
    payload.payment_method || "card",
    payload.transaction_type || "sale",
    payload.policy_mode || "BALANCED"
  ]);
  return JSON.parse(result.data[0]);
}