Analytics Integrations API

1. Overview

The Analytics Integrations API is a multi-provider blockchain analytics aggregation service that fans out screening requests to three industry-leading providers - Chainalysis KYT, TRM Labs, and Elliptic - and returns a single composite risk score. This unified approach eliminates the need for clients to integrate with each provider individually, provides graceful degradation when a provider is unavailable, and delivers a weighted composite score that reflects the combined intelligence of all active providers.

• Base URL: https://jilsovereign.com/api/analytics
• Protocol: HTTPS (TLS 1.3)
• Content-Type: All requests and responses are application/json
• Version: v1
• Encoding: UTF-8
• Endpoints: 6 total - 4 screening endpoints + 1 batch + 1 status

2. Architecture

The Analytics Integrations API operates as a fan-out aggregator. Each inbound screening request is dispatched in parallel to all configured and healthy providers. Responses are collected, scored, and merged into a single composite result.

Request Flow

Key Design Principles

• Parallel fan-out: All provider requests are dispatched concurrently using Promise.allSettled(). The aggregator waits for all providers to respond (or timeout at 5 seconds) before computing the composite score.
• Graceful degradation: If a provider is down or times out, remaining providers continue to serve. Weights are re-normalized across the remaining healthy providers so the composite score stays on the 0-100 scale. A degraded: true flag is added to the response.
• Caching layer: Results are cached in Redis with a 5-minute TTL keyed by {type}:{chain}:{target}. Cached responses include a "cached": true flag. Cache is bypassed when force_refresh: true is sent in the request body.
• Prometheus metrics: Every screening operation emits latency histograms, provider status gauges, and risk-level counters for observability.

3. Provider Configuration

Three analytics providers are integrated, each with a configurable weight that determines its contribution to the composite risk score. Providers can be individually enabled or disabled at runtime, and weights auto-normalize when a provider is unavailable.

4. Endpoints

4.1 Screen Transaction

POST /v1/analytics/screen/transaction

Screen a blockchain transaction across all active analytics providers. Returns individual provider scores and a composite weighted risk score.

Request Body

{
  "tx_hash": "0x7a8b9c...",
  "chain": "ethereum",
  "direction": "inbound",          // optional: "inbound" | "outbound"
  "metadata": {}                       // optional: additional context
}

Response (200 OK)

{
  "ok": true,
  "screening_id": "scr_tx_abc123",
  "type": "transaction",
  "target": "0xabc123...",
  "composite_score": 15,
  "risk_level": "LOW",
  "providers": [
    {
      "provider": "chainalysis",
      "score": 12,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 245
    },
    {
      "provider": "trm_labs",
      "score": 18,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 312
    },
    {
      "provider": "elliptic",
      "score": 14,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 198
    }
  ],
  "alerts": [],
  "cached": false,
  "timestamp": "2026-03-02T12:00:00.000Z"
}

4.2 Screen Wallet

POST /v1/analytics/screen/wallet

Screen a wallet address across all active analytics providers. Returns individual provider scores and a composite weighted risk score.

Request Body

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chain": "ethereum"
}

Response (200 OK)

{
  "ok": true,
  "screening_id": "scr_wal_def456",
  "type": "wallet",
  "target": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "composite_score": 22,
  "risk_level": "LOW",
  "providers": [
    {
      "provider": "chainalysis",
      "score": 20,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 231
    },
    {
      "provider": "trm_labs",
      "score": 25,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 287
    },
    {
      "provider": "elliptic",
      "score": 19,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 176
    }
  ],
  "alerts": [],
  "cached": false,
  "timestamp": "2026-03-02T12:00:00.000Z"
}

4.3 Screen Sanctions

POST /v1/analytics/screen/sanctions

Screen an address against global sanctions lists across all active analytics providers. Returns match status, lists checked, and a composite risk score.

Request Body

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chain": "ethereum",                 // optional
  "include_partial_matches": false      // optional, default: false
}

Response (200 OK)

{
  "ok": true,
  "screening_id": "scr_san_ghi789",
  "type": "sanctions",
  "target": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "composite_score": 5,
  "risk_level": "LOW",
  "sanctions_match": false,
  "sanctions_lists_checked": ["OFAC_SDN", "EU_SANCTIONS", "UN_SANCTIONS"],
  "providers": [
    {
      "provider": "chainalysis",
      "score": 3,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 210
    },
    {
      "provider": "trm_labs",
      "score": 7,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 298
    },
    {
      "provider": "elliptic",
      "score": 4,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 185
    }
  ],
  "alerts": [],
  "cached": false,
  "timestamp": "2026-03-02T12:00:00.000Z"
}

4.4 Risk Score

GET /v1/analytics/risk-score/:address

Retrieve the cached composite risk score for a previously screened address. Returns the most recent screening result without triggering a new provider lookup.

Query Parameters

Response (200 OK)

{
  "ok": true,
  "address": "0xabc123...",
  "composite_score": 15,
  "risk_level": "LOW",
  "provider_scores": {
    "chainalysis": 12,
    "trm_labs": 18,
    "elliptic": 14
  },
  "last_screened_at": "2026-03-02T12:00:00.000Z",
  "screening_count": 5,
  "cached": true
}

4.5 Batch Screen

POST /v1/analytics/batch/screen

Screen multiple addresses in a single request. Supports wallet and sanctions screening types. Maximum 100 addresses per batch.

Request Body

{
  "addresses": ["0xabc...", "0xdef..."],
  "chain": "ethereum",
  "type": "wallet"                    // "wallet" | "sanctions"
}

Response (200 OK)

{
  "ok": true,
  "batch_id": "batch_abc123",
  "total": 2,
  "results": [
    {
      "address": "0xabc...",
      "composite_score": 15,
      "risk_level": "LOW",
      "alerts": []
    },
    {
      "address": "0xdef...",
      "composite_score": 72,
      "risk_level": "HIGH",
      "alerts": [
        {
          "type": "sanctions_match",
          "severity": "critical",
          "details": "OFAC SDN match"
        }
      ]
    }
  ],
  "processing_time_ms": 890
}

4.6 Provider Status

GET /v1/analytics/providers/status

Returns the current health status, weight configuration, and performance metrics for all configured providers. No authentication required.

Response (200 OK)

{
  "ok": true,
  "providers": [
    {
      "name": "chainalysis",
      "status": "healthy",
      "weight": 0.40,
      "avg_response_ms": 245,
      "success_rate": 0.998
    },
    {
      "name": "trm_labs",
      "status": "healthy",
      "weight": 0.35,
      "avg_response_ms": 312,
      "success_rate": 0.995
    },
    {
      "name": "elliptic",
      "status": "healthy",
      "weight": 0.25,
      "avg_response_ms": 198,
      "success_rate": 0.997
    }
  ],
  "timestamp": "2026-03-02T12:00:00.000Z"
}

5. Risk Scoring

The composite risk score is calculated as a weighted average of all active provider scores:

// Composite score formula
composite_score = SUM(provider_score * provider_weight)

// Example with all 3 providers active:
composite = (12 * 0.40) + (18 * 0.35) + (14 * 0.25)
          = 4.8 + 6.3 + 3.5
          = 14.6 // rounded to 15

// Example with Elliptic down (weights re-normalized):
composite = (12 * 0.533) + (18 * 0.467)
          = 6.4 + 8.4
          = 14.8 // rounded to 15

Risk Level Thresholds

6. Error Handling

All error responses follow a consistent format with an HTTP status code, a machine-readable error code, and a human-readable message.

{
  "ok": false,
  "error": {
    "code": "bad_request",
    "message": "Missing required field: address"
  }
}

Error Codes

Graceful Degradation

When one or more providers fail but at least one remains healthy, the API returns a successful response with partial results. The response includes a degraded: true flag and lists which providers were unavailable:

{
  "ok": true,
  "degraded": true,
  "unavailable_providers": ["elliptic"],
  "composite_score": 15,
  "risk_level": "LOW",
  "providers": [
    {
      "provider": "chainalysis",
      "score": 12,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 245
    },
    {
      "provider": "trm_labs",
      "score": 18,
      "risk_level": "LOW",
      "alerts": [],
      "response_ms": 312
    },
    {
      "provider": "elliptic",
      "status": "unavailable",
      "error": "Connection timeout after 5000ms"
    }
  ],
  "cached": false,
  "timestamp": "2026-03-02T12:00:00.000Z"
}

7. Code Examples

Screen a wallet address using the Analytics Integrations API.

curl -X POST https://jilsovereign.com/api/analytics/v1/analytics/screen/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "chain": "ethereum"
  }'

// Screen a wallet address
const response = await fetch(
  'https://jilsovereign.com/api/analytics/v1/analytics/screen/wallet',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18',
      chain: 'ethereum'
    })
  }
);

const data = await response.json();

if (data.ok) {
  console.log(`Composite score: ${data.composite_score}`);
  console.log(`Risk level: ${data.risk_level}`);

  // Check individual provider scores
  for (const provider of data.providers) {
    console.log(`${provider.provider}: ${provider.score} (${provider.response_ms}ms)`);
  }

  // Check for degraded response
  if (data.degraded) {
    console.warn('Response is degraded - some providers unavailable');
  }
} else {
  console.error(`Error: ${data.error.code} - ${data.error.message}`);
}

import requests

# Screen a wallet address
url = "https://jilsovereign.com/api/analytics/v1/analytics/screen/wallet"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
payload = {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "chain": "ethereum"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data["ok"]:
    print(f"Composite score: {data['composite_score']}")
    print(f"Risk level: {data['risk_level']}")

    # Check individual provider scores
    for provider in data["providers"]:
        print(f"  {provider['provider']}: {provider['score']} ({provider['response_ms']}ms)")

    # Check for degraded response
    if data.get("degraded"):
        print("WARNING: Response is degraded - some providers unavailable")
else:
    print(f"Error: {data['error']['code']} - {data['error']['message']}")

8. Prometheus Metrics

The Analytics Integrations API exposes Prometheus-compatible metrics on the /metrics endpoint for monitoring screening volume, provider health, latency, and cache performance.