API Documentation

Integrate compliance checks and AI-agent detection into your applications with the AI DECISIONS API.

Authentication

All API requests require an X-API-Key header.

http
GET /compliance/status HTTP/1.1
Host: api.aidecisions.ai
X-API-Key: your-api-key

Get your API key by registering a tenant via POST /tenants/register or from the dashboard.

Machine-readable reference: OpenAPI 3 specification — import it into Postman, Insomnia or any client generator.

Quick Start

Python

python
import requests

API = "https://api.aidecisions.ai"

result = requests.post(
    f"{API}/v1/screen/ethereum/0x722122df12d4e14e13ac3b6895a86e84145b6967",
    headers={"X-API-Key": "ak_your_key_here"},
).json()

print(result["risk_score"])     "color:#6b7280"># 0.8934
print(result["category"])       "color:#6b7280"># "mixer"
print(result["risk_tier"])      "color:#6b7280"># 5  (of 5)
print(result["model_version"])  "color:#6b7280"># pinned in every response

TypeScript

typescript
const API = "https:">//api.aidecisions.ai";

const res = await fetch(
  `${API}/v1/screen/ethereum/0x722122df12d4e14e13ac3b6895a86e84145b6967`,
  { method: "POST", headers: { "X-API-Key": "ak_your_key_here" } },
);
const result = await res.json();

console.log(result.risk_score);    "color:#6b7280">// 0.8934
console.log(result.category);      "color:#6b7280">// "mixer"
console.log(result.risk_tier);     "color:#6b7280">// 5  (of 5)

The sanctions_hit field in every /v1/screen verdict is checked against the live OFAC SDN list, refreshed within the hour — a new listing reaches the API without a redeploy. Coverage follows OFAC itself: every chain it publishes addresses for (16 chains, 989 SDN addresses today, including Bitcoin and Monero), not just the six scored chains.

Open-Source Tooling

The label-production tooling behind our screening line is open source under Apache-2.0: github.com/ai-decisions/openlabels — a typed unified label schema, an OFAC SDN parser, scrapers for VASP registers across nine jurisdictions, registry builders (VASP / mixer / bridge) and a GraphSense-compatible TagPack generator with a CI-verified, byte-reproducible pipeline.

bash
pip install "openlabels-core[tagpack] @ git+https://github.com/ai-decisions/openlabels"

SDKs

Official clients wrap the screening line with typed errors and built-in retries: ai-decisions on PyPI and @aidecisions/client on npm.

Install

bash
pip install ai-decisions
npm install @aidecisions/client

Python

python
from ai_decisions import AiDecisionsClient

client = AiDecisionsClient(api_key="ak_your_key_here")

verdict = client.screen("ethereum", "0x722122df12d4e14e13ac3b6895a86e84145b6967")
print(verdict["risk_score"])   "color:#6b7280"># 0.8934
print(verdict["risk_tier"])    "color:#6b7280"># 5  (of 5)

"color:#6b7280"># Typed errors: AuthenticationError (401), RateLimitError (429),
"color:#6b7280"># ValidationError (422) — retries with backoff are built in.

TypeScript

typescript
import { AiDecisionsClient } from "@aidecisions/client";

const client = new AiDecisionsClient({ apiKey: "ak_your_key_here" });

const verdict = await client.screen(
  "ethereum",
  "0x722122df12d4e14e13ac3b6895a86e84145b6967",
);
console.log(verdict.risk_score);  "color:#6b7280">// 0.8934
console.log(verdict.risk_tier);   "color:#6b7280">// 5  (of 5)

POST /compliance/transaction-check

Check a single transaction for compliance risk. Returns a risk level, score, recommendation, and explanation.

Request Body

json
{
  "amount": 9500.00,
  "sender": "Acme Trading Ltd",
  "receiver": "Global Logistics SA",
  "sender_jurisdiction": "panama",
  "receiver_jurisdiction": "cayman_islands",
  "currency": "USD",
  "graph_centrality": 0.45,
  "gnn_score": 0.72
}

Response

json
{
  "risk_score": 0.78,
  "risk_level": "high",
  "risk_factors": [
    {
      "rule": "high_risk_sender_jurisdiction",
      "detail": "Sender jurisdiction (panama) is in FSI top-10",
      "severity": "high"
    },
    {
      "rule": "potential_structuring",
      "detail": "Amount $9,500 is 95% of $10,000 CTR threshold",
      "severity": "high"
    }
  ],
  "recommendation": "block_and_review",
  "components": {
    "graph_centrality": 0.45,
    "gnn_score": 0.72,
    "rule_score": 1.0
  }
}

Risk Levels

  • high — Block and escalate
  • medium — Enhanced review
  • low — Proceed normally

Recommendations

  • block_and_review
  • enhanced_due_diligence
  • proceed

POST /compliance/agent-detection

Detect AI-agent behavior from a set of transaction patterns. Submit multiple transactions for a single account and receive a classification.

Request Body

json
{
  "transactions": [
    {
      "timestamp": "2026-04-04T08: 00: 01Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x3c4d"
    },
    {
      "timestamp": "2026-04-04T08: 00: 02Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x5e6f"
    },
    {
      "timestamp": "2026-04-04T08: 00: 03Z",
      "amount": 499.99,
      "sender": "wallet_0x1a2b",
      "receiver": "wallet_0x7g8h"
    }
  ]
}

Response

json
{
  "agent_probability": 0.85,
  "classification": "likely_agent",
  "indicators": [
    {
      "indicator": "perfect_periodicity",
      "detail": "Transaction intervals vary by less than 5%",
      "score": 0.9
    },
    {
      "indicator": "amount_clustering",
      "detail": "Transaction amounts vary by less than 2%",
      "score": 0.8
    }
  ],
  "transaction_count": 3,
  "interval_data": [1.0, 1.0],
  "amount_data": [499.99, 499.99, 499.99],
  "weekday_counts": { "Fri": 3 },
  "topology": {
    "nodes": [
      { "id": "wallet_0x1a2b", "type": "wallet", "risk": 0.85 },
      { "id": "wallet_0x3c4d", "type": "wallet", "risk": 0.0 }
    ],
    "edges": [
      { "source": "wallet_0x1a2b", "target": "wallet_0x3c4d", "amount": 499.99, "count": 1 }
    ]
  }
}

Classification Values

  • likely_agent — High confidence of automated behavior
  • possibly_agent — Some automated signals detected
  • likely_human — Behavior consistent with human activity

POST /v1/ai-agents/score

Classify a single Ethereum address as ai_agent, human or unknown — no transaction history required. The verdict comes from the curated label registry first (Flashbots builders, known exploiters, exchange infrastructure and other sources), with the confidence, matched labels and a human-readable reasoning string.

Request Body

json
{
  "address": "0x1f9090aae28b8a3dceadf281b0f12828e676c326"
}

Response

json
{
  "address": "0x1f9090aae28b8a3dceadf281b0f12828e676c326",
  "classification": "ai_agent",
  "confidence": 0.95,
  "model_version": "labels-v2",
  "labels": [
    {
      "name": "rsync-builder",
      "source": "flashbots",
      "chain": "ethereum"
    }
  ],
  "reasoning": "Address found in known AI-agent registry (flashbots): rsync-builder."
}

Rate Limits

The billed unit is one screening check (/v1/screen), counted per calendar month. A daily cap protects against bursts; it resets at 00:00 UTC. The Research tier is free and also includes the full research corpus, intelligence digests, weekly reviews and graph export (GEXF/GraphML) at no cost.

TierScreening Checks / MonthDaily Burst Cap
Research2525
Analyst500100
Enterprise10,0002,000

Rate Limit Headers

X-RateLimit-Limit — Maximum requests allowed per day

X-RateLimit-Remaining — Requests remaining in the current window

X-RateLimit-Reset — UTC timestamp when the limit resets

X-Compliance-RateLimit-Limit — Maximum compliance checks per day

X-Compliance-RateLimit-Remaining — Compliance checks remaining

When you exceed your rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating the number of seconds to wait before retrying.

Error Codes

CodeDescription
401Invalid or missing API key. Include a valid key in the X-API-Key header.
403Feature not available on your current tier. Upgrade your plan to access this endpoint.
422Validation error. Check the request body against the schema above.
429Rate limit exceeded. Retry after the number of seconds in the Retry-After header.