API Documentation

Authentication Required

All API requests require authentication via an API key. Include your key in the X-API-Key header with every request.

Don't have an API key yet? Sign up for free to get started with 1,000 free transactions.

Transaction Endpoints

POST /api/transactions

Submit a single transaction for real-time fraud detection. The API runs all enabled detection rules and returns risk scores and alerts immediately.

Request Body Parameters

Parameter	Type	Required	Description
`amount`	number	Required	Transaction amount
`source_account`	string	Optional	Source account identifier
`type`	string	Optional	Transaction type (payment, deposit, withdrawal, etc.)
`country_code`	string	Optional	ISO country code (US, UK, CA, etc.)
`ip_address`	string	Optional	User IP address
`device_fingerprint`	string	Optional	Device fingerprint for multi-account detection

Example Request

curl -X POST https://spectra-qqzo.polsia.app/api/transactions \
  -H "X-API-Key: sk_spectra_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.50,
    "source_account": "user_12345",
    "type": "payment",
    "country_code": "US",
    "ip_address": "192.168.1.1",
    "device_fingerprint": "fp_abc123xyz"
  }'

Example Response

{
  "transaction": {
    "id": 123,
    "amount": 250.50,
    "risk_score": 75,
    "flagged": true
  },
  "alerts": [
    {
      "alert_type": "velocity",
      "severity": "high",
      "title": "Velocity alert: 12 transactions in 60 minutes",
      "risk_score": 75
    }
  ]
}

POST /api/transactions/batch

Submit multiple transactions for batch processing. Maximum 100 transactions per request.

Example Request

curl -X POST https://spectra-qqzo.polsia.app/api/transactions/batch \
  -H "X-API-Key: sk_spectra_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      { "amount": 100, "source_account": "user_1" },
      { "amount": 250, "source_account": "user_2" },
      { "amount": 50, "source_account": "user_1" }
    ]
  }'

GET /api/transactions

Retrieve transaction history with optional filters.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 50, max: 100)
`flagged`	boolean	Filter by flagged status (true/false)
`source_account`	string	Filter by source account

Rule Evaluation

POST /api/rules/evaluate

Evaluate transactions against fraud detection rules without persisting them. Useful for testing or pre-screening.

Example Request

curl -X POST https://spectra-qqzo.polsia.app/api/rules/evaluate \
  -H "X-API-Key: sk_spectra_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "transactions": [
      { "amount": 1000, "source_account": "user_999" }
    ],
    "category": "bonus_abuse"
  }'

Metrics & Monitoring

GET /api/metrics

Get comprehensive system metrics including transaction volume, detection rates, and alert breakdowns.

Example Request

curl -X GET https://spectra-qqzo.polsia.app/api/metrics \
  -H "X-API-Key: sk_spectra_abc123..."

GET /health

Health check endpoint (no authentication required). Add ?metrics=true for extended metrics or ?check=db to verify database connectivity.

Example Request

curl https://spectra-qqzo.polsia.app/health?metrics=true&check=db

Rate Limits & Usage

Free Trial: 1,000 transactions, no time limit
Rate Limit: 100 requests per minute per API key
Batch Limit: Maximum 100 transactions per batch request
Concurrent Requests: No hard limit, but respect rate limits

When you exceed your transaction limit, you'll receive a 429 Too Many Requests response with details about your current usage.

Detection Rules

Spectra includes 17 pre-configured fraud detection rules across three categories:

General Fraud - Amount spikes, velocity checks, geo-mismatch, large thresholds, new account rush
Bonus Abuse - Signup velocity, deposit-withdraw patterns, multi-claims, low wagering, geo-mismatch, threshold matching
Multi-Account - Device fingerprint sharing, IP clustering, behavioral similarity, deposit coordination, rapid creation, cross-transfers

All rules run automatically on every transaction. Results are returned in real-time with severity levels (low, medium, high, critical) and detailed explanations.