QCA REST API
Reference v1.0

The QCA API gives you programmatic access to the world's only pre-mempool blockchain compliance engine. Score wallet addresses and transactions against QARS v1.0 — a quantum-amplitude-inspired risk model — in under 500ms. Block high-risk transactions before they are ever broadcast to the Ethereum mempool.

Authentication

All API requests require a valid API key passed in the X-API-Key header. Keys are issued per account and are tier-scoped — a Free key cannot call Pro endpoints.

X-API-Key: qca_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Get Your API Key

Free tier keys are issued instantly at signup.html. Pro and Enterprise keys are provisioned within 24 hours of subscription confirmation. Sovereign tier keys are issued under NDA.

Base URL & Versioning

https://api.quantchainanalysis.com       # Primary endpoint
https://api.quantchainanalysis.com  # QCA API endpointck)

The API is versioned via the URL path (/v1/). Breaking changes are announced 60 days in advance. The /health endpoint is unversioned and always available.

Quickstart

Score a wallet address in one API call. The response includes the QARS risk score, tier classification, gate decision, and the full 10-dimension amplitude vector.

# Score a wallet address
curl -X POST https://api.quantchainanalysis.com/v1/analyze \
  -H "X-API-Key: qca_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x722122df12d4e14e13ac3b6895a86e84145b6967",
    "chain": "ethereum",
    "analyst_name": "Compliance Engine v1"
  }'

// Node.js / browser fetch
const response = await fetch('https://api.quantchainanalysis.com/v1/analyze', {
  method: 'POST',
  headers: {
    'X-API-Key': 'qca_live_YOUR_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    wallet_address: '0x722122df12d4e14e13ac3b6895a86e84145b6967',
    chain: 'ethereum',
    analyst_name: 'My Compliance App'
  })
});
const data = await response.json();
console.log(data.risk_tier); // "HIGH"
console.log(data.gate_decision); // "PRE_MEMPOOL_BLOCK"

import requests

response = requests.post(
    'https://api.quantchainanalysis.com/v1/analyze',
    headers={
        'X-API-Key': 'qca_live_YOUR_KEY_HERE',
        'Content-Type': 'application/json'
    },
    json={
        'wallet_address': '0x722122df12d4e14e13ac3b6895a86e84145b6967',
        'chain': 'ethereum',
        'analyst_name': 'Compliance Engine'
    }
)
data = response.json()
print(data['risk_tier'])    # HIGH
print(data['risk_score'])   # 9.0

Example Response

{
  "wallet_address": "0x722122df12d4e14e13ac3b6895a86e84145b6967",
  "risk_score": 9.0000,
  "risk_tier": "HIGH",
  "gate_decision": "PRE_MEMPOOL_BLOCK",
  "interference_uplift": 0.300,
  "amplitude_vector": [0.95, 0.80, 0.90, 1.0, 0.30, 0.70, 0.60, 0.50, 1.0, 0.40],
  "signals_detected": [
    "OFAC-SDN Direct Designation",
    "Mixer Address Detected",
    "Sanction Cluster Distance: 0.000"
  ],
  "top_signal": "OFAC-SDN Direct Designation",
  "commitment_hash": "8b120cd90c473bdef357445feb39ae52dcb5ab003b1b95af68f68702af1edf9c",
  "nullifier": "3608b1747f155c17873640b671eb1a488feb2d483ced51e82a8fa0ae8d9360c0",
  "ledger_hash": "7a6f16b89537ec4971b65da519e6dd1f2f4fa50a63b2e79d19b9003d30805f57",
  "epoch": 1779896097,
  "chain": "ethereum",
  "qars_version": "1.0"
}

POST /v1/analyze

The core endpoint. Submits a wallet address (and optionally a transaction hash) for full QARS v1.0 risk scoring. Returns the risk score, tier, gate decision, amplitude vector, forensic hashes, and detected signals.

GET /health

Unauthenticated health check. Use for uptime monitoring, pre-flight checks, and warm-up pings before cold-start requests. Returns 200 OK when the engine is ready.

curl https://api.quantchainanalysis.com/health

{ "status": "ok", "engine": "qars-v1.0", "version": "3.0" }

POST /v1/batch PRO

Screen up to 500 wallet addresses in a single API call. Results are returned in the same order as the input array. Each result is a full QARS v1.0 analysis object identical to /v1/analyze.

{
  "wallets": [
    "0x722122df12d4e14e13ac3b6895a86e84145b6967",
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "0xdac17f958d2ee523a2206206994597c13d831ec7"
  ],
  "chain": "ethereum",
  "batch_reference": "SCREENING-2026-001"
}

GET /ledger PRO

Returns the 20 most recent ForensicLedger records anchored by your API key. Each record contains the full cryptographic hash chain (commitment, nullifier, ledger hash) and is on-chain verifiable against the Ethereum Sepolia ForensicLedger smart contract.

QARS v1.0 Scoring Model

The Quantum Amplitude Risk Score (QARS v1.0) applies quantum-mechanical Born-rule probability mathematics to blockchain risk signals. Each risk dimension is modelled as a quantum amplitude αᵢ. The composite risk score is computed as:

S = Σᵢ |αᵢ|² × wᵢ   +   Δ_interference

Where:
  αᵢ  = amplitude of dimension i  (0.0 – 1.0)
  wᵢ  = weight of dimension i     (see table below)
  Δ   = constructive interference uplift (0.0 – 0.45)
  S   = final QARS score           (0.0 – 10.0)

Interference uplift applies when two or more HIGH-severity dimensions (αᵢ > 0.6) co-occur in the same analysis. This models the quantum mechanical principle that correlated risk signals amplify each other non-linearly — a mixer-proximity plus sanction-cluster co-occurrence is more dangerous than the sum of its parts.

Amplitude Dimensions

The amplitude vector is a 10-element array. Each element corresponds to one risk dimension. Index order is fixed across all API responses and SDK versions.

Gate Decisions

The gate_decision field maps directly to the risk tier and tells integrators what action to take pre-mempool.

Error Codes

Rate Limits

JavaScript SDK

The qca-sdk.js file provides a lightweight wrapper around the QCA REST API for browser and Node.js environments.

// Via CDN (browser)
<script src="https://www.quantchainanalysis.com/qca-sdk.js"></script>

// Or import directly
import QCA from './qca-sdk.js';

const qca = new QCA({ apiKey: 'qca_live_YOUR_KEY_HERE' });

// Single wallet
const result = await qca.analyze({
  wallet: '0x722122df12d4e14e13ac3b6895a86e84145b6967',
  chain: 'ethereum'
});

// Batch (Pro+)
const results = await qca.batch([
  '0x722122...', '0xd8dA6B...'
]);

// Gate decision hook (Enterprise) — called pre-sendRawTransaction
qca.gateHook(async (tx) => {
  const r = await qca.analyze({ wallet: tx.from });
  if (r.gate_decision === 'PRE_MEMPOOL_BLOCK') throw new Error('Transaction blocked by QCA gate');
  return tx;
});

Python

# Until the package is published, use requests directly:
pip install requests

import requests

class QCAClient:
    BASE = 'https://api.quantchainanalysis.com'
    def __init__(self, api_key):
        self.headers = {'X-API-Key': api_key, 'Content-Type': 'application/json'}

    def analyze(self, wallet, chain='ethereum'):
        r = requests.post(f'{self.BASE}/v1/analyze',
            headers=self.headers, json={'wallet_address': wallet, 'chain': chain})
        r.raise_for_status()
        return r.json()

qca = QCAClient('qca_live_YOUR_KEY')
result = qca.analyze('0x722122df12d4e14e13ac3b6895a86e84145b6967')
print(result['risk_tier'])

Webhooks PRO

Configure a webhook URL in your Enterprise dashboard to receive real-time POST notifications whenever a HIGH or MEDIUM risk wallet is detected in your monitored address pool. Payloads are signed with HMAC-SHA256 using your webhook secret.

{
  "event": "wallet.flagged",
  "timestamp": 1779896097,
  "wallet_address": "0x722122df12d4e14e13ac3b6895a86e84145b6967",
  "risk_tier": "HIGH",
  "gate_decision": "PRE_MEMPOOL_BLOCK",
  "risk_score": 9.0,
  "top_signal": "OFAC-SDN Direct Designation",
  "ledger_hash": "7a6f16b89537..."
}

SAR/STR Generation PRO

Pro tier API responses automatically include the data required to generate pre-filled SAR/STR (Suspicious Activity Report / Suspicious Transaction Report) templates. Supported jurisdictions: DE (BaFin/FIU), EU (AMLD5/AMLD6), US (FinCEN BSA), UK (NCA/POCA 2002), AU (AUSTRAC).

The QCA web interface (demo.html, gate-simulator.html, batch-screener.html) provides one-click SAR/STR template generation from any analysis result. API integrators can use the commitment_hash, nullifier, and ledger_hash fields as the cryptographic evidence annex to any SAR filing.

FATF Travel Rule PRO

Pro tier analyses return a travel_rule block in the response when a transaction value exceeds EUR/USD 1,000. This block identifies whether the originator and beneficiary VASP data requirements of FATF Recommendation 16 are satisfied, and flags missing data fields.

"travel_rule": {
  "applicable": true,
  "threshold_usd": 1000,
  "originator_vasp_identified": false,
  "beneficiary_vasp_identified": false,
  "missing_fields": ["originator_name", "originator_account", "beneficiary_name"],
  "compliance_status": "NON_COMPLIANT",
  "regulation": "FATF Recommendation 16 · MiCA Art. 68 · EU TFR 2023/1113"
}

Law Enforcement Endpoint SOVEREIGN

The Sovereign tier provides a dedicated endpoint for FIUs, law enforcement agencies, and government bodies. Under a valid court order, investigators can submit independently-obtained biometric evidence to recompute the nullifier and cross-reference all on-chain sessions associated with a given identity — without any platform cooperation required.

Access requires a signed NDA and government-issued credentials. Contact: contact@quantchainanalysis.com (mark subject: SOVEREIGN ACCESS REQUEST).